About the Origin Configuration API

The Origin Configuration API enables you to programmatically add, remove, and make modifications to the configuration of your organization's network origins (i.e., fulfillment centers, warehouses) from your applications instead of making them through the Shipium Console. This may be particularly useful if your organization already has systems for modifying some of these settings within your own systems and wants them quickly reflected within your Shipium applications as well.

❗️
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.

REST semantics

Shipium application programming interfaces (APIs) generally adhere to the basic REST semantics for hypertext transfer protocol, or HTTP:

POST - create a new origin entity
GET - retrieve the latest version of a given origin entity by ID
PATCH - update or add one or more properties to an existing origin entity
DELETE - remove an existing origin entity

Standard basics for using the Shipium APIs

📘
Authentication for API calls
In the cURL examples 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.

🔐

Authenticating for Curl

Open Recipe

👉
How to use test mode
Want to run some examples and not charge any real money against your account?
You can add "testMode": "true" to a call, and it will be evaluated for correctness but not applied. You can use this for validating that your calls work without making actual changes.
The examples below all contain the testMode flag to err on the side of caution – you should remove this to make production calls.

About origins

An origin is a location from which fulfillment operations occur. Most commonly, this is likely a fulfillment center, warehouse, or other dedicated location where packages are prepared and shipped. It can also be any location from which you may be pursuing fulfillment operations of some kind, including dropship locations or stores.

Using the Origin Configuration API

This section includes guidance on using the Origin Configuration API to:

create a new origin entity;
retrieve the latest version of a given origin entity by ID;
update or add one or more properties to an existing origin entity; and
delete an existing origin entity.

Notes on elements to include when calling the Origin Configuration API

Element	Data type	Notes
originType	String LOV	Exactly one of: FC - for fulfillment centers Store - for store locations, i.e. those locations that may ship and also interact directly with customers AtLarge - a special case for providing data that is used for shipping from locations that are NOT FCs or stores, e.g. shipping from a dropship partner not configured as an FC.
partnerProvidedId	String	Unique to the asset ID that is provided by your organization; this ID gives the you the ability to set your own IDs for assets within the Shipium platform.
name	String	The name of the origin
description	String	A description of the origin
contact	Object	contact has four elements referring to the contact for this origin. fullName - the full name of the contact emailAddress - the email address of the contact phoneNumber - the phone number associated with the contact phoneNumberCountryCode - an optional field for the phone country code associated with the phone number, e.g. "+1"
address	Object	address has nine elements referring to the address for this origin. city - the name of the city for the address company - the company associated with the address countryCode - the 2-character country code of the address name - the name of the origin address postalCode - a country-code-appropriate postal code for the address state - the 2-letter postal abbreviation of the state for the address street1 - the first address line street2 - the second address line addressLineComponents - an object whose components are defined in the row below Note: You may include either the street1* and street2 values OR you can include the addressLineComponents values (defined below). However, you can't include both in the same call.*
address.addressLine Components	Object	addressLineComponents has five elements referring to the address for this origin. streetName - the name of the street for the address 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

Creating an origin (POST)

Pathways and parameters	Details
POST	`<<api_url>>/api/v1/partnerConfiguration/origins`
Optional parameter for Tenant ID	`tenantId` (a string ID for the tenant with which this origin is to be associated at creation)

This example shows the Client Uniform Resource Locator (cURL) request for creating an origin:

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'

This example shows the JavaScript Object Notation (JSON) for the body contents (passed via --data in cURL) for creating an origin using the street 1 and street 2 fields for the address object.

{
  "address": {
    "city": "Reno",
    "company": "Shipium",
    "countryCode": "US",
    "name": "Reno Address",
    "postalCode": "89433",
    "state": "NV",
    "street1": "123 Shipium Way",
    "street2": "Building 123",
    "addressLineComponents": null
  },
  "contact": {
    "email": "[email protected]",
    "fullName": "Shippy Shipium",
    "name": "Reno Contact",
    "phoneNumber": "2223334444",
    "phoneNumberCountryCode": null
  },
  "description": "Reno Fulfillment Center",
  "name": "Reno Fulfillment Center",
  "originType": "at_large",
  "partnerProvidedId": "rno_fulfillment_center"
}

This example shows a JSON response for the request including street1 and street2:

{
    "address": {
        "city": "Reno",
        "company": "Shipium",
        "countryCode": "US",
        "name": "Reno Address",
        "postalCode": "89433",
        "state": "NV",
        "street1": "123 Shipium Way",
        "street2": "Building 123"
    },
    "contact": {
        "email": "[email protected]",
        "fullName": "Shippy Shipium",
        "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": "2024-04-16T20:37:01.818Z"
    },
    "originId": "5ddf6ced-eed2-4cec-bb7e-5cde30959843",
    "originType": "at_large",
    "partnerId": "76abb3d4-8990-4f80-aa13-4c2007cb852a",
    "partnerProvidedId": "rno_fulfillment_center",
    "scheduleConfigured": false
}

This is a sample request including the addressLineComponents values:

{
  "address": {
    "city": "Mexico City",
    "company": "Shipium",
    "countryCode": "MX",
    "name": "Mexico City Address",
    "postalCode": "14410",
    "state": "CDMX",
    "street1": null,
    "street2": null,
    "addressLineComponents": {
        "streetName": "Fovisste Fuentes Brotantes",
        "primaryAddressNumber": "D-1",
        "secondaryAddressNumber": "302",
        "district": "Tlalpan",
        "neighborhood": "Miguel Hidalgo",
    }
  },
  "contact": {
    "email": "[email protected]",
    "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"
}

This example shows a JSON response for the request including addressLineComponents:

{
    "address": {
        "addressLineComponents": {
            "district": "Tlalpan",
            "neighborhood": "Miguel Hidalgo",
            "primaryAddressNumber": "D-1",
            "secondaryAddressNumber": "302",
            "streetName": "Fovisste Fuentes Brotantes"
        },
        "city": "Mexico City",
        "company": "Shipium",
        "countryCode": "MX",
        "name": "Mexico City Address",
        "postalCode": "14410",
        "state": "CDMX"
    },
    "contact": {
        "email": "[email protected]",
        "fullName": "Shippy Shipium",
        "name": "Mexico City Contact",
        "phoneNumber": "2223334444",
        "phoneNumberCountryCode": "+52"
    },
    "description": "Mexico City Fulfillment Center",
    "href": "https://partner-management-service.stage.shipium.com/api/v1/partnerConfiguration/origins/befb6619-c4ae-4af6-939c-590782c7b384",
    "name": "Mexico City Fulfillment Center",
    "orchestratedAssetMetadata": {
        "orchestrationId": "369e6293-2065-4717-a482-68d53f62cfed",
        "orchestrationTimeStamp": "2024-04-16T15:52:35.032Z"
    },
    "originId": "43216619-c4ae-4af6-939c-590782c7b384",
    "originType": "fc",
    "partnerId": "1234b3d4-8990-4f80-aa13-4c2007cb852a",
    "partnerProvidedId": "cdmx_fulfillment_center",
    "scheduleConfigured": false
}

Retrieving a created origin (GET)

Here is the cURL request:

curl --request GET \
  --url <<api_url>>/api/v1/partnerConfiguration/origins/b49a5687-6393-4dab-9e83-dfcad86e6b2a \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json'

The response will be the same as the previous example for creating an origin.

Updating an existing origin (PATCH)

If you want to update a subset of an existing origin, you can update a subset by using PATCH as follows:

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

This example shows the JSON for the body contents (passed via --data in cURL):

{
  "address": {
    "addressType": "string",
    "city": "string",
    "company": "string",
    "countryCode": "string",
    "name": "string",
    "postalCode": "string",
    "state": "string",
    "street1": "string",
    "street2": "string"
  },
  "contact": {
    "email": "string",
    "fullName": "string",
    "name": "string",
    "phoneNumber": "string",
    "phoneNumberCountryCode": "+1"
  },
  "description": "string",
  "name": "string",
  "originType": "at_large"
}

The following is an example JSON response:

{
  "activeSchedule": {
    "carrierSchedules": [
      {
        "carrierId": "string",
        "carrierScheduleId": "string",
        "carrierServiceMethodIds": [
          "string"
        ],
        "cutoffExceptions": [
          {
            "cutoff": "15:30",
            "date": "2022-12-24"
          }
        ],
        "cutoffTimes": [
          {
            "cutoff": "13:45",
            "dayOfWeek": "FRIDAY"
          }
        ]
      }
    ],
    "from": "2023-05-23T19:30:47.560Z",
    "holidays": [
      {
        "date": "2020-07-04",
        "metadata": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        }
      }
    ],
    "orchestratedAssetMetadata": {
      "orchestrationId": "string",
      "orchestrationTimeStamp": "2023-05-23T19:30:47.560Z"
    },
    "processingCutoff": {
      "expectedDaysToShip": 0,
      "shippingCutoffHour": 0,
      "weekendCutoffHour": 0
    },
    "scheduleEntryId": "string",
    "shippingDays": [
      "FRIDAY"
    ],
    "to": "2023-05-23T19:30:47.560Z"
  },
  "address": {
    "addressType": "string",
    "city": "string",
    "company": "string",
    "countryCode": "string",
    "name": "string",
    "postalCode": "string",
    "state": "string",
    "street1": "string",
    "street2": "string"
  },
  "contact": {
    "email": "string",
    "name": "string",
    "phoneNumber": "string",
    "phoneNumberCountryCode": "+1"
  },
  "description": "string",
  "href": "string",
  "name": "string",
  "orchestratedAssetMetadata": {
    "orchestrationId": "string",
    "orchestrationTimeStamp": "2023-05-23T19:30:47.560Z"
  },
  "originId": "string",
  "originType": "at_large",
  "partnerId": "string",
  "partnerProvidedId": "string",
  "scheduleConfigured": true,
  "tenantLinkReference": {
    "href": "string",
    "identifier": "string",
    "name": "string"
  }
}

Deleting an existing origin (DELETE)

If you want to delete an existing origin, you can do so by using DELETE as follows:

curl --request DELETE \
  --url <<api_url>>/api/v1/partnerConfiguration/origins/{identifier} \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json'

The following is an example JSON response:

{
  "activeSchedule": {
    "carrierSchedules": [
      {
        "carrierId": "string",
        "carrierScheduleId": "string",
        "carrierServiceMethodIds": [
          "string"
        ],
        "cutoffExceptions": [
          {
            "cutoff": "15:30",
            "date": "2022-12-24"
          }
        ],
        "cutoffTimes": [
          {
            "cutoff": "13:45",
            "dayOfWeek": "FRIDAY"
          }
        ]
      }
    ],
    "from": "2023-05-23T19:40:53.582Z",
    "holidays": [
      {
        "date": "2020-07-04",
        "metadata": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        }
      }
    ],
    "orchestratedAssetMetadata": {
      "orchestrationId": "string",
      "orchestrationTimeStamp": "2023-05-23T19:40:53.582Z"
    },
    "processingCutoff": {
      "expectedDaysToShip": 0,
      "shippingCutoffHour": 0,
      "weekendCutoffHour": 0
    },
    "scheduleEntryId": "string",
    "shippingDays": [
      "FRIDAY"
    ],
    "to": "2023-05-23T19:40:53.582Z"
  },
  "address": {
    "addressType": "string",
    "city": "string",
    "company": "string",
    "countryCode": "string",
    "name": "string",
    "postalCode": "string",
    "state": "string",
    "street1": "string",
    "street2": "string"
  },
  "contact": {
    "email": "string",
    "name": "string",
    "phoneNumber": "string",
    "phoneNumberCountryCode": "+1"
  },
  "description": "string",
  "href": "string",
  "name": "string",
  "orchestratedAssetMetadata": {
    "orchestrationId": "string",
    "orchestrationTimeStamp": "2023-05-23T19:40:53.582Z"
  },
  "originId": "string",
  "originType": "at_large",
  "partnerId": "string",
  "partnerProvidedId": "string",
  "scheduleConfigured": true,
  "tenantLinkReference": {
    "href": "string",
    "identifier": "string",
    "name": "string"
  }
}

Origin Configuration API

About the Origin Configuration API

❗️
Warning: potential negative impact on your fulfillment operations

REST semantics

Standard basics for using the Shipium APIs

📘
Authentication for API calls

👉
How to use test mode

About origins

Using the Origin Configuration API

Notes on elements to include when calling the Origin Configuration API

Creating an origin (POST)

Retrieving a created origin (GET)

Updating an existing origin (PATCH)

Deleting an existing origin (DELETE)

About the Origin Configuration API

❗️Warning: potential negative impact on your fulfillment operations

REST semantics

Standard basics for using the Shipium APIs

📘Authentication for API calls

👉How to use test mode

About origins

Using the Origin Configuration API

Notes on elements to include when calling the Origin Configuration API

Creating an origin (POST)

Retrieving a created origin (GET)

Updating an existing origin (PATCH)

Deleting an existing origin (DELETE)

❗️
Warning: potential negative impact on your fulfillment operations

📘
Authentication for API calls

👉
How to use test mode