About the Tenant Configuration API

The Tenant Configuration API enables you to programmatically add, remove, and make modifications to the configuration of the tenants associated with 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 tenant for an origin entity
GET - retrieve the latest version of a given tenant for an origin entity by ID
PATCH - update or add one or more properties to an existing tenant for an origin entity
DELETE - remove an existing tenant from an 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.

REST semantics

Shipium APIs generally adhere to the basic REST semantics for hypertext transfer protocol, or HTTP:

POST - create a new tenant for an origin entity
GET - retrieve the latest version of a given tenant for an origin entity by ID
PATCH - update or add one or more properties to an existing tenant for an origin entity
DELETE - remove an existing tenant from an 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 tenants

A tenant represents an entity that is capable of generating shipments and doing other fulfillment operations within your organization's account. A tenant is composed of one or more origins (and their associated origin schedules), your organization's information, and corporate and tax information that is used as part of international shipping.

Using the Tenant Configuration API

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

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

Creating a tenant for an origin entity (POST)

Pathways and parameters	Details
POST	`<<api_url>>/api/v1/partnerConfiguration/tenants`

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

curl --request POST \ 
  --url <<api_url>>/api/v1/partnerConfiguration/tenants \
  --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):

{
  "description": "string",
  "name": "string",
  "partnerProvidedId": "string",
  "taxIdentificationNumber": "string",
  "unitedStatesPrincipalPartyInInterestAddress": {
    "addressType": "string",
    "city": "string",
    "company": "string",
    "countryCode": "string",
    "name": "string",
    "postalCode": "string",
    "state": "string",
    "street1": "string",
    "street2": "string"
  },
  "unitedStatesPrincipalPartyInInterestContact": {
    "email": "string",
    "name": "string",
    "phoneNumber": "string"
  }
}

This example shows a JSON response:

{
  "description": "string",
  "href": "string",
  "name": "string",
  "orchestratedAssetMetadata": {
    "orchestrationId": "string",
    "orchestrationTimeStamp": "2023-05-23T20:56:05.385Z"
  },
  "origins": [
    {
      "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-23T20:56:05.385Z",
        "holidays": [
          {
            "date": "2020-07-04",
            "metadata": {
              "additionalProp1": "string",
              "additionalProp2": "string",
              "additionalProp3": "string"
            }
          }
        ],
        "orchestratedAssetMetadata": {
          "orchestrationId": "string",
          "orchestrationTimeStamp": "2023-05-23T20:56:05.385Z"
        },
        "processingCutoff": {
          "expectedDaysToShip": 0,
          "shippingCutoffHour": 0,
          "weekendCutoffHour": 0
        },
        "scheduleEntryId": "string",
        "shippingDays": [
          "FRIDAY"
        ],
        "to": "2023-05-23T20:56:05.385Z"
      },
      "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"
      },
      "description": "string",
      "href": "string",
      "name": "string",
      "orchestratedAssetMetadata": {
        "orchestrationId": "string",
        "orchestrationTimeStamp": "2023-05-23T20:56:05.385Z"
      },
      "originId": "string",
      "originType": "at_large",
      "partnerId": "string",
      "partnerProvidedId": "string",
      "scheduleConfigured": true,
      "tenantLinkReference": {
        "href": "string",
        "identifier": "string",
        "name": "string"
      }
    }
  ],
  "partnerId": "string",
  "partnerProvidedId": "string",
  "taxIdentificationNumber": "string",
  "tenantId": "string",
  "unitedStatesPrincipalPartyInInterestAddress": {
    "addressType": "string",
    "city": "string",
    "company": "string",
    "countryCode": "string",
    "name": "string",
    "postalCode": "string",
    "state": "string",
    "street1": "string",
    "street2": "string"
  },
  "unitedStatesPrincipalPartyInInterestContact": {
    "email": "string",
    "name": "string",
    "phoneNumber": "string"
  }
}

Retrieving all tenants for an origin entity (GET)

Pathways and parameters	Details
GET	`<<api_url>>/api/v1/partnerConfiguration/tenants/{identifier}`
Required path element	`tenantID` (a string ID for the tenant with which the origin is associated) Note: `tenantId` can be replaced with your custom `partnerProvidedId` if previously provided.
Optional path element	`asOfDateTime` (a string value of the date and time for which you want the list of tenants; defaults to call time)

The request body is empty for this call.

This example shows a JSON response:

{
  "description": "string",
  "href": "string",
  "name": "string",
  "orchestratedAssetMetadata": {
    "orchestrationId": "string",
    "orchestrationTimeStamp": "2023-05-23T21:02:13.061Z"
  },
  "origins": [
    {
      "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-23T21:02:13.061Z",
        "holidays": [
          {
            "date": "2020-07-04",
            "metadata": {
              "additionalProp1": "string",
              "additionalProp2": "string",
              "additionalProp3": "string"
            }
          }
        ],
        "orchestratedAssetMetadata": {
          "orchestrationId": "string",
          "orchestrationTimeStamp": "2023-05-23T21:02:13.061Z"
        },
        "processingCutoff": {
          "expectedDaysToShip": 0,
          "shippingCutoffHour": 0,
          "weekendCutoffHour": 0
        },
        "scheduleEntryId": "string",
        "shippingDays": [
          "FRIDAY"
        ],
        "to": "2023-05-23T21:02:13.061Z"
      },
      "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"
      },
      "description": "string",
      "href": "string",
      "name": "string",
      "orchestratedAssetMetadata": {
        "orchestrationId": "string",
        "orchestrationTimeStamp": "2023-05-23T21:02:13.061Z"
      },
      "originId": "string",
      "originType": "at_large",
      "partnerId": "string",
      "partnerProvidedId": "string",
      "scheduleConfigured": true,
      "tenantLinkReference": {
        "href": "string",
        "identifier": "string",
        "name": "string"
      }
    }
  ],
  "partnerId": "string",
  "partnerProvidedId": "string",
  "taxIdentificationNumber": "string",
  "tenantId": "string",
  "unitedStatesPrincipalPartyInInterestAddress": {
    "addressType": "string",
    "city": "string",
    "company": "string",
    "countryCode": "string",
    "name": "string",
    "postalCode": "string",
    "state": "string",
    "street1": "string",
    "street2": "string"
  },
  "unitedStatesPrincipalPartyInInterestContact": {
    "email": "string",
    "name": "string",
    "phoneNumber": "string"
  }
}

Updating an existing tenant for an origin entity (PATCH)

Pathways and parameters	Details
PATCH	`<<api_url>>/api/v1/partnerConfiguration/tenants/{identifier}`
Required path element	`tenantID` (a string ID for the tenant with which the origin is associated) Note: `tenantId` can be replaced with your custom `partnerProvidedId` if previously provided.
Required path element	`tenantUpdate` (an object including the active/archived status for the tenant, description, name, origin information, partner-provided ID, and tax identification number)

If you want to update a tenant for an existing origin, you can do so by using PATCH as follows:

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

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

{
  "description": "string",
  "name": "string",
  "taxIdentificationNumber": "string",
  "unitedStatesPrincipalPartyInInterestAddress": {
    "addressType": "string",
    "city": "string",
    "company": "string",
    "countryCode": "string",
    "name": "string",
    "postalCode": "string",
    "state": "string",
    "street1": "string",
    "street2": "string"
  },
  "unitedStatesPrincipalPartyInInterestContact": {
    "email": "string",
    "name": "string",
    "phoneNumber": "string"
  }
}

The following is an example JSON response:

{
  "description": "string",
  "href": "string",
  "name": "string",
  "orchestratedAssetMetadata": {
    "orchestrationId": "string",
    "orchestrationTimeStamp": "2023-05-23T21:11:59.852Z"
  },
  "origins": [
    {
      "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-23T21:11:59.852Z",
        "holidays": [
          {
            "date": "2020-07-04",
            "metadata": {
              "additionalProp1": "string",
              "additionalProp2": "string",
              "additionalProp3": "string"
            }
          }
        ],
        "orchestratedAssetMetadata": {
          "orchestrationId": "string",
          "orchestrationTimeStamp": "2023-05-23T21:11:59.852Z"
        },
        "processingCutoff": {
          "expectedDaysToShip": 0,
          "shippingCutoffHour": 0,
          "weekendCutoffHour": 0
        },
        "scheduleEntryId": "string",
        "shippingDays": [
          "FRIDAY"
        ],
        "to": "2023-05-23T21:11:59.852Z"
      },
      "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"
      },
      "description": "string",
      "href": "string",
      "name": "string",
      "orchestratedAssetMetadata": {
        "orchestrationId": "string",
        "orchestrationTimeStamp": "2023-05-23T21:11:59.852Z"
      },
      "originId": "string",
      "originType": "at_large",
      "partnerId": "string",
      "partnerProvidedId": "string",
      "scheduleConfigured": true,
      "tenantLinkReference": {
        "href": "string",
        "identifier": "string",
        "name": "string"
      }
    }
  ],
  "partnerId": "string",
  "partnerProvidedId": "string",
  "taxIdentificationNumber": "string",
  "tenantId": "string",
  "unitedStatesPrincipalPartyInInterestAddress": {
    "addressType": "string",
    "city": "string",
    "company": "string",
    "countryCode": "string",
    "name": "string",
    "postalCode": "string",
    "state": "string",
    "street1": "string",
    "street2": "string"
  },
  "unitedStatesPrincipalPartyInInterestContact": {
    "email": "string",
    "name": "string",
    "phoneNumber": "string"
  }
}

Deleting an existing tenant for an origin entity (DELETE)

Pathways and parameters	Details
DELETE	`<<api_url>>/api/v1/partnerConfiguration/tenants/{identifier}`
Required path element	`tenantID` (a string ID for the tenant with which the origin is associated) Note: `tenantId` can be replaced with your custom `partnerProvidedId` if previously provided.

The request body is empty for this call.

This example shows a JSON response:

{
  "description": "string",
  "href": "string",
  "name": "string",
  "orchestratedAssetMetadata": {
    "orchestrationId": "string",
    "orchestrationTimeStamp": "2023-05-23T21:15:46.238Z"
  },
  "origins": [
    {
      "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-23T21:15:46.238Z",
        "holidays": [
          {
            "date": "2020-07-04",
            "metadata": {
              "additionalProp1": "string",
              "additionalProp2": "string",
              "additionalProp3": "string"
            }
          }
        ],
        "orchestratedAssetMetadata": {
          "orchestrationId": "string",
          "orchestrationTimeStamp": "2023-05-23T21:15:46.238Z"
        },
        "processingCutoff": {
          "expectedDaysToShip": 0,
          "shippingCutoffHour": 0,
          "weekendCutoffHour": 0
        },
        "scheduleEntryId": "string",
        "shippingDays": [
          "FRIDAY"
        ],
        "to": "2023-05-23T21:15:46.238Z"
      },
      "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"
      },
      "description": "string",
      "href": "string",
      "name": "string",
      "orchestratedAssetMetadata": {
        "orchestrationId": "string",
        "orchestrationTimeStamp": "2023-05-23T21:15:46.239Z"
      },
      "originId": "string",
      "originType": "at_large",
      "partnerId": "string",
      "partnerProvidedId": "string",
      "scheduleConfigured": true,
      "tenantLinkReference": {
        "href": "string",
        "identifier": "string",
        "name": "string"
      }
    }
  ],
  "partnerId": "string",
  "partnerProvidedId": "string",
  "taxIdentificationNumber": "string",
  "tenantId": "string",
  "unitedStatesPrincipalPartyInInterestAddress": {
    "addressType": "string",
    "city": "string",
    "company": "string",
    "countryCode": "string",
    "name": "string",
    "postalCode": "string",
    "state": "string",
    "street1": "string",
    "street2": "string"
  },
  "unitedStatesPrincipalPartyInInterestContact": {
    "email": "string",
    "name": "string",
    "phoneNumber": "string"
  }
}

Tenant Configuration API

About the Tenant 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

REST semantics

Standard basics for using the Shipium APIs

📘
Authentication for API calls

👉
How to use test mode

About tenants

Using the Tenant Configuration API

Creating a tenant for an origin entity (POST)

Retrieving all tenants for an origin entity (GET)

Updating an existing tenant for an origin entity (PATCH)

Deleting an existing tenant for an origin entity (DELETE)

About the Tenant 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

REST semantics

Standard basics for using the Shipium APIs

📘Authentication for API calls

👉How to use test mode

About tenants

Using the Tenant Configuration API

Creating a tenant for an origin entity (POST)

Retrieving all tenants for an origin entity (GET)

Updating an existing tenant for an origin entity (PATCH)

Deleting an existing tenant for an origin entity (DELETE)

❗️
Warning: potential negative impact on your fulfillment operations

📘
Authentication for API calls

👉
How to use test mode

📘
Authentication for API calls

👉
How to use test mode