APIs Introduction
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 API | What it does |
|---|---|
| Address Validation API | Validates an address based on its deliverability before shipment and label generation |
| Batch Label Creation API | Creates shipping labels in batches with the ability to retrieve labels for up to 150 shipments in one API call |
| Carrier and Method Selection API | Selects the least expensive carrier and ship method that meets your criteria |
| Carrier and Method Selection & Shipment Label API | Selects 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 APIs - Product View Delivery Promise API - Cart Checkout Delivery Promise API |
- Product View Delivery Promise API._ Enables you to provide an estimated delivery date for your customers as they view products on your product detail pages - Cart Checkout Delivery Promise API._ Enables you to provide an estimated delivery date for your customers after they place products in their shopping cart |
| Fulfillment Engine API | Allocates inventory to shipments optimally in order to hit desired delivery dates (if provided) at the lowest cost |
| LTL (Less Than Truckload) APIs - LTL Shipment Cost API - LTL Shipment Cost Compare API |
- LTL Shipment Cost API._ Enables you to determine the best carrier and service method for an LTL shipment - LTL Shipment Cost Compare API._ Helps you determine if transporting a shipment via small package shipping or LTL shipping would be more cost effective |
| Packaging Planner API | Selects the best set of packaging types/sizes for the shipped items |
| Return Label API | Generates a return label for customers to return product(s) |
| Shipment Label API | Buys postage and retrieves label images |
| Shipment Planning API | Provides a recommended ship-by date to meet your desired delivery date |
| Shipment Tracking API | Provides tracking event details for single or bulk shipments |
| Shipment Tracking Registration API | Provides tracking event details for single or bulk shipments that were not generated via Shipium's Carrier and Method Selection |
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 code | What it means | What to expect |
|---|---|---|
| 200 | Success! | You'll get back what you expected. |
| 4XX | Failure | Something at your end needs to be fixed for the API call to succeed. |
| 5XX | Failure | Something 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.
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 time | Format |
|---|---|
| UTC Time | 2020-01-01T23:30:00Z |
| Time with PT | 2015-05-15T15:30:00-8:00 |
Data handling and character normalization
Shipium automatically transforms certain characters in your shipment data to ensure compatibility across carrier systems. Before integrating, review Data Handling and Character Normalization to understand how accented characters, special symbols, and whitespace are processed.