# Get started

To use the Origin Configuration API, you can follow the instructions on this page. More information about the Origin Configuration API can be found in [Configuration APIs](https://docs.shipium.com/docs/configuration-apis). In addition, if you prefer to configure your origins via the [Shipium Console](https://partner.shipium.com/login), you can find guidance for doing so in the [Origins](https://docs.shipium.com/docs/origins) documentation.

### Warning: potential negative impact on your fulfillment operations

This API can modify elements of your organization's network fulfillment configuration in ways that could negatively impact the production of your fulfillment operations. You should only use the API if you are familiar with how any changes you make could affect your network fulfillment configuration.

# Configure origins with the Origin Configuration API

The Origin Configuration API assumes you're using one of the authentication mechanisms detailed in our [authentication documentation](https://docs.shipium.com/docs/authentication). The general endpoint for Origin Configuration calls is included in the table below.

| API type | API endpoint |
| --- | --- |
| POST | `https://api.shipium.com/api/v1/partnerConfiguration/origins` |

### Authentication for API Calls

In the cURL example on this page, the environment variable `AUTHSTRING` is used to handle authorization. The recipe below shows how to set it correctly for both API Key and OAuth users.

## Request fields for API calls

The following tables provide required and optional fields for calling the Origin Configuration API. Path elements are described for each use case in the sections that follow.

### Required request fields

| Request field | Details |
| --- | --- |
| `originType` | **Type:** String (enumeration)<br>**Values:**`fc`, `store`, `at_large`<br>**Description:** The type of [origin](https://docs.shipium.com/docs/origins); `fc` refers to fulfillment center, `store` refers to locations that may ship and also interact directly with customers, and `at_large` refers to a special case for providing data that is used for shipping from locations that are NOT fulfillment centers or stores (e.g., shipping from a dropship partner not configured as a fulfillment center). |

### Optional request fields

| Request field | Details |
| --- | --- |
| `partnerProvidedId` | **Type:** String<br>**Description:** Unique to the asset ID that is provided by your organization; this ID gives you the ability to set your own IDs for assets within the Shipium platform. |
| `name` | **Type:** String<br>**Description:** The name of the [origin](https://docs.shipium.com/docs/origins) |
| `description` | **Type:** String<br>**Description:** A description of the [origin](https://docs.shipium.com/docs/origins) |
| `contact` | **Type:** Object<br>**Description:** Contains contact information for this [origin](https://docs.shipium.com/docs/origins)<br>**Child fields:**`fullName` (the full name of the contact), `emailAddress` (the email address of the contact), `phoneNumber` (the phone number associated with the contact), `phoneNumberCountryCode` (the phone country code associated with the phone number, e.g., "+1") |
| `address` | **Type:** Object<br>**Description:** Contains address information for this [origin](https://docs.shipium.com/docs/origins)<br>**Child fields:**`city` (the name of the city), `company` (the company associated with the address), `countryCode` (the 2-character country code), `name` (the name of the origin address), `postalCode` (a country-code-appropriate postal code), `state` (the 2-letter postal abbreviation of the state), `street1` (the first address line), `street2` (the second address line), `addressLineComponents` (an object for non-US address formats; see below)<br>**Note:** You may include either the `street1` and `street2` values OR the `addressLineComponents` values, but not both in the same call. |
| `address.addressLineComponents` | **Type:** Object<br>**Description:** Contains address line components for [non-US address](https://docs.shipium.com/docs/non-us-address-formats) formats<br>**Child fields:**`streetName` (the name of the street), `primaryAddressNumber` (the primary number for the address), `secondaryAddressNumber` (the secondary number for the address), `district` (the district for the address), `neighborhood` (the neighborhood name for the address) |

## Create an origin

The endpoint for creating an [origin](https://docs.shipium.com/docs/origins) is provided below, along with the optional parameter for associating a tenant with the origin, if your organization employs tenants. You can find information on tenants within the Shipium platform in the [Tenant Details](https://docs.shipium.com/docs/fulfillment-contexts#tenant-details) documentation.

### Path

**POST**`https://api.shipium.com/api/v1/partnerConfiguration/origins`

**Required path element:**`originId`

**Optional parameter:**`tenantId` (a string ID for the tenant with which this origin is to be associated at creation)

### Example cURL call

This example shows a request to create an origin:

```curl
curl --request POST \
  --url <<api_url>>/api/v1/partnerConfiguration/origins \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json' \
  --data 'INSERT CONTENTS FROM BELOW'
```

### Example request body using street1 and street2

This example shows the JSON request for creating an origin using the `street 1` and `street 2` fields for the `address` object:

```json
{
  "address": {
    "city": "Reno",
    "company": "Shipium",
    "countryCode": "US",
    "name": "Reno Address",
    "postalCode": "89433",
    "state": "NV",
    "street1": "123 Shipium Way",
    "street2": "Building 123"
  },
  "contact": {
    "email": "shippy@shipium.com",
    "fullName": "Shippy Shipium",
    "name": "Reno Contact",
    "phoneNumber": "2223334444"
  },
  "description": "Reno Fulfillment Center",
  "name": "Reno Fulfillment Center",
  "originType": "at_large",
  "partnerProvidedId": "rno_fulfillment_center"
}
```

### Example request body using addressLineComponents

This is a sample request including the `addressLineComponents` values:

```json
{
  "address": {
    "city": "Mexico City",
    "company": "Shipium",
    "countryCode": "MX",
    "name": "Mexico City Address",
    "postalCode": "14410",
    "state": "CDMX",
    "addressLineComponents": {
        "streetName": "Fovisste Fuentes Brotantes",
        "primaryAddressNumber": "D-1",
        "secondaryAddressNumber": "302",
        "district": "Tlalpan",
        "neighborhood": "Miguel Hidalgo"
    }
  },
  "contact": {
    "email": "shippy@shipium.com",
    "fullName": "Shippy Shipium",
    "name": "Mexico City Contact",
    "phoneNumber": "2223334444",
    "phoneNumberCountryCode": "+52"
  },
  "description": "Mexico City Fulfillment Center",
  "name": "Mexico City Fulfillment Center",
  "originType": "fc",
  "partnerProvidedId": "cdmx_fulfillment_center"
}
```

### Retrieve a specific origin by ID

### Path

**GET**`https://api.shipium.com/api/v1/partnerConfiguration/origins/{originId}`

**Required path element** : `originId`

**Optional parameter**: `tenantId` (a string ID for the tenant with which this origin is to be associated at creation)

### Example response body

```json
{
  "activeSchedule": {
    "from": "2022-10-17T22:33:42.548Z",
    "holidays": [
      {
        "date": "2020-07-04",
        "metadata": {
          "additionalProp1": "company holiday",
          "additionalProp2": "national"
        }
      }
    ],
    "processingCutoff": {
      "expectedDaysToShip": 0,
      "shippingCutoffHour": 0,
      "weekendCutoffHour": 0
    },
    "shippingDays": [
      "friday"
    ],
    "to": "2022-10-17T22:33:42.549Z"
  },
  "address": {
    "addressType": "residential",
    "name": "Reno Address",
    "company": "Shipium",
    "street1": "123 Shipium Way",
    "street2": "Building 123",
    "city": "Reno",
    "state": "NV",
    "countryCode": "US",
    "postalCode": "89433"
  },
  "contact": {
    "email": "shippy@shipium.com",
    "name": "Reno Contact",
    "phoneNumber": "2223334444"
  },
  "description": "Reno Fulfillment Center",
  "href": "https://partner-management-service.stage.shipium.com/api/v1/partnerConfiguration/origins/5ddf6ced-eed2-4cec-bb7e-5cde30959843",
  "name": "Reno Fulfillment Center",
  "orchestratedAssetMetadata": {
    "orchestrationId": "4ad3b5d5-f256-4184-b9af-15ccca60ea99",
    "orchestrationTimeStamp": "2022-10-17T22:33:42.549Z"
  },
  "originId": "5ddf6ced-eed2-4cec-bb7e-5cde30959843",
  "originType": "at_large",
  "partnerId": "76abb3d4-8990-4f80-aa13-4c2007cb852a",
  "partnerProvidedId": "rno_fulfillment_center",
  "scheduleConfigured": true,
  "tenantLink": {
    "href": "https://partner-management-service.stage.shipium.com/api/v1/partnerConfiguration/origins/5ddf6ced-eed2-4cec-bb7e-5cde30959843",
    "tenantId": "f7092716-1b4b-4ce6-b4a6-e18b11f16c9d"
  }
}
```

## Update an existing origin

### Path

**PATCH**`https://api.shipium.com/api/v1/partnerConfiguration/origins/{originId}`

**Required path element**: `originId`

**Optional parameter**: `tenantId` (a string ID for the tenant with which this origin is to be associated at creation)

### Example request body

```json
{
  "name": "Reno Fulfillment Center",
  "description": "Reno Fulfillment Center",
  "originType": "at_large",
  "address": {
    "addressType": "residential",
    "name": "Reno Address",
    "company": "Shipium",
    "street1": "123 Shipium Way",
    "street2": "Building 123",
    "city": "Reno",
    "state": "NV",
    "countryCode": "US",
    "postalCode": "89433"
  },
  "contact": {
    "name": "Reno Contact",
    "email": "shippy@shipium.com",
    "phoneNumber": "2223334444"
  }
}
```

### Example response body

```json
{
  "activeSchedule": {
    "from": "2022-10-17T22:45:31.652Z",
    "holidays": [
      {
        "date": "2020-07-04"
      }
    ],
    "processingCutoff": {
      "expectedDaysToShip": 0,
      "shippingCutoffHour": 0,
      "weekendCutoffHour": 0
    },
    "shippingDays": [
      "friday"
    ],
    "to": "2022-10-17T22:45:31.652Z"
  },
  "address": {
    "addressType": "residential",
    "name": "Reno Address",
    "company": "Shipium",
    "street1": "123 Shipium Way",
    "street2": "Building 123",
    "city": "Reno",
    "state": "NV",
    "countryCode": "US",
    "postalCode": "89433"
  },
  "contact": {
    "email": "shippy@shipium.com",
    "name": "Reno Contact",
    "phoneNumber": "2223334444"
  },
  "description": "Reno Fulfillment Center",
  "href": "https://partner-management-service.stage.shipium.com/api/v1/partnerConfiguration/origins/5ddf6ced-eed2-4cec-bb7e-5cde30959843",
  "name": "Reno Fulfillment Center",
  "orchestratedAssetMetadata": {
    "orchestrationId": "4ad3b5d5-f256-4184-b9af-15ccca60ea99",
    "orchestrationTimeStamp": "2022-10-17T22:45:31.652Z"
  },
  "originId": "5ddf6ced-eed2-4cec-bb7e-5cde30959843",
  "originType": "at_large",
  "partnerId": "76abb3d4-8990-4f80-aa13-4c2007cb852a",
  "partnerProvidedId": "rno_fulfillment_center",
  "scheduleConfigured": true,
  "tenantLink": {
    "href": "https://partner-management-service.stage.shipium.com/api/v1/partnerConfiguration/origins/5ddf6ced-eed2-4cec-bb7e-5cde30959843",
    "tenantId": "f7092716-1b4b-4ce6-b4a6-e18b11f16c9d"
  }
}
```

## Delete an existing origin

### Path

**DELETE**`https://api.shipium.com/api/v1/partnerConfiguration/origins/{originId}`

**Required path element**: `originId`

### Example response body

```json
{
  "activeSchedule": {
    "from": "2022-10-17T22:48:36.908Z",
    "holidays": [
      {
        "date": "2020-07-04"
      }
    ],
    "processingCutoff": {
      "expectedDaysToShip": 0,
      "shippingCutoffHour": 0,
      "weekendCutoffHour": 0
    },
    "shippingDays": [
      "friday"
    ],
    "to": "2022-10-17T22:48:36.908Z"
  },
  "address": {
    "addressType": "residential",
    "name": "Reno Address",
    "company": "Shipium",
    "street1": "123 Shipium Way",
    "street2": "Building 123",
    "city": "Reno",
    "state": "NV",
    "countryCode": "US",
    "postalCode": "89433"
  },
  "contact": {
    "email": "shippy@shipium.com",
    "name": "Reno Contact",
    "phoneNumber": "2223334444"
  },
  "description": "Reno Fulfillment Center",
  "href": "https://partner-management-service.stage.shipium.com/api/v1/partnerConfiguration/origins/5ddf6ced-eed2-4cec-bb7e-5cde30959843",
  "name": "Reno Fulfillment Center",
  "orchestratedAssetMetadata": {
    "orchestrationId": "4ad3b5d5-f256-4184-b9af-15ccca60ea99",
    "orchestrationTimeStamp": "2022-10-17T22:48:36.908Z"
  },
  "originId": "5ddf6ced-eed2-4cec-bb7e-5cde30959843",
  "originType": "at_large",
  "partnerId": "76abb3d4-8990-4f80-aa13-4c2007cb852a",
  "partnerProvidedId": "rno_fulfillment_center",
  "scheduleConfigured": true,
  "tenantLink": {
    "href": "https://partner-management-service.stage.shipium.com/api/v1/partnerConfiguration/origins/5ddf6ced-eed2-4cec-bb7e-5cde30959843",
    "tenantId": "f7092716-1b4b-4ce6-b4a6-e18b11f16c9d"
  }
}
```

# Resources

Your Shipium team member is available to help along the way. However, you might find these resources helpful:

- [Terms and Definitions](https://docs.shipium.com/docs/common-terms)
- [Troubleshooting Guide](https://docs.shipium.com/docs/troubleshooting-guide)
- [Contact Shipium Support](https://docs.shipium.com/docs/contacting-shipium-support)