APIs Introduction

Understand the basics of Shipium's APIs.

About Shipium's APIs

Your organization can use a single Shipium API to meet a specific need, or take advantage of multiple APIs. Like standard APIs, ours enable communication between two application software entities, or endpoints, using rulesets and definitions. The following table describes in general what each API does; the Shipium's APIs page includes links to other documentation for each API.

The APIWhat it does
Address Validation APIValidates an address based on its deliverability before shipment and label generation
Batch Label Creation APICreates shipping labels in batches with the ability to retrieve labels for up to 150 shipments in one API call
Carrier and Method Selection APISelects the least expensive carrier and ship method that meets your criteria
Carrier and Method Selection & Shipment Label APISelects the least expensive carrier and ship method that meets your criteria and buys postage and retrieves label images
Configuration APIs

- Origin Configuration API
- Origin Schedule Configuration API
Origin Configuration API. Enables you to programmatically add, remove, and make modifications to the configuration of your organization's network origins
Origin Schedule Configuration API. Enables you to create and configure network fulfillment origin schedules
Delivery Promise APIInitiates a delivery with a promised delivery date
Fulfillment Engine APIAllocates inventory to shipments optimally in order to hit desired delivery dates (if provided) at the lowest cost
Packaging Planner APISelects the best set of packaging types/sizes for the shipped items
Return Label APIGenerates a return label for customers to return product(s)
Shipment Label APIBuys postage and retrieves label images
Shipment Tracking APIProvides tracking event details for single or bulk shipments
Shipment Tracking Registration APIProvides tracking event details for single or bulk shipments that were not generated via Shipium's Carrier and Method Selection
Subscription Timing APITells you when to ship product to your subscriber customers to meet a delivery date

About the general organization of the APIs

The Shipium APIs follow the REST, or REpresentational State Transfer, paradigm.

This means our APIs:

  • use predictable resource-oriented uniform resource locators (URLs);
  • accept JavaScript Object Notation (JSON) request bodies;
  • return responses as JSON-encoded data; and
  • use standardized response codes, authentication, and verbs.

You'll interact with our APIs using mostly the POST (meaning "create") or GET (meaning "read") methods.

Response codes and error conditions

Shipium responses generally follow the response codes in the following table. You can find more details in API Response Codes.

Response codeWhat it meansWhat to expect
200Success!You'll get back what you expected.
4XXFailureSomething at your end needs to be fixed for the API call to succeed.
5XXFailureSomething at Shipium's end needs to be fixed for the API call to succeed, or potentially an error from a carrier or other system on which Shipium depends needs to be resolved.

About your test and production API keys

You'll be provided with two API keys when you create your organization's Shipium account: one for production and one for testing.

The testing API key will not work in production, and the production API key will not work in testing. This prevents you from accidentally impacting your production data while testing or pointing your production services at the test endpoint.

👉

About API test mode

The Shipium API set has separate endpoints when you're in test mode. Working in test mode does not affect your organization's live data.

General format and syntax information

Authorization

Request authentication is via OAuth 2.0 using the authorization request header or authorization URL parameter. You can find more details in Authentication.

Date formats

All dates in the API are strings in the ISO 8601 "combined date and time representation" format. The following table provides Coordinated Universal Time (UTC) and Pacific Time Zone (PT) examples:

Date and timeFormat
UTC Time2020-01-01T23:30:00Z
Time with PT2015-05-15T15:30:00-8:00

Resources

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