Shipsi

API Reference
Create Order Label
- Create Label

Shipsi’s REST API’s

Shipsi’s APIs (Application Programming Interface) power its technology for ecommerce delivery. Behind these APIs is a software layer integrating and aggregating driver networks in 5,000+ cities.

From getting shipping rates to viewing checkout analytics to scheduling deliveries, Shipsi has an entire suite of APIs. Shipsi API reference documentation can be found throughout our product documentation. You can use this page to browse the various APIs or jump right in to Shipping Rates or Create Delivery.

What is a REST API?

An API is an application programming interface - or more simply, a set of rules which allow programs talk to each other, exposing permissible data and functionality across the internet in a format which is consistent.

REST is an acronym for Representational State Transfer. This is an architectural pattern that explains how distributed systems can expose a consistent interface. When the term ‘REST API’ is used it is typically referencing an API accessed via HTTP protocol at a defined set of URLs.

These URLs hold different resources - such as information or content at that location, which is returned in either JSON, HTML, images, or audio files. Often, resources have multiple methods that can be performed over HTTP, like GET, POST, PUT and DELETE.

Shipsi offers many different REST APIs for finding shipping rates, creating deliveries, checking analytics, managing locations, and much more. With the Shipsi technology offering, each product has a separate API, but you can work with each in a similar manner, whether over HTTP or using Shipsi’s guides for different programming languages.

Base URL

All URLs referenced within this document have the same base URL, which are predictable and resource-oriented

This REST API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

Authentication

The Shipsi API uses API keys to authenticate requests. You can view your API key in your account settings within your self-serve portal

Errors

Shipsi uses conventional HTTP response codes to indicate the success or failure of an API request. Generally it can be known: Codes within the 2xx range mean success. Codes within the 4xx range mean failure due to the information given (such as, a required parameter was omitted, an address was invalid, the scheduled time is in the past.). Codes within the 5xx range mean their is an error on our end.

Because many 4xx errors can be handled programmatically we do our best to provide a code which explains the reported error.

HTTP STATUS CODE SUMMARY

200 - OK

Everything worked as expected.

400 - Bad Request

The request was unacceptable, often due to missing a required parameter.

401 - Unauthorized

No valid API key provided.

402 - Request Failed

The parameters were valid but the request failed.

403 - Forbidden

The API key doesn't have permissions to perform the request.

404- Not Found

The request resources doesn’t exist

409 - Conflict

Conflict with another request

429 - Too Many Requests

Too many requests at once, try exponential backoff

500, 502, 503, 504 - Server Errors

Something is wrong on our end

API Error Responses

no_service_available - SHIPSI not activated

This SHIPSI account is not active since it is missing required information. Please log into the SHIPSI Portal to complete your required information.

outside_of_delivery_network_radius - Outside of delivery network radius

The destination address is outside the delivery radius of any eligible pickup locations.

disable_next_day_delivery_merchant - No delivery option matching eligible location(s) operating hours

There are no pickup locations which have operating hours during this time to accept orders. Contact SHIPSI support to active other delivery options that could expand your delivery window.

location_items_not_available - One or more items excluded from delivery from eligible location(s)

At least one item in the order is excluded for SHIPSI delivery at the eligible location. All items in an order must be included (and not excluded) at a single, eligible location. Inclusions/Exclusions by location are managed in the SHIPSI Portal in Location Settings.

no_merchant_pickup_location - No availability through delivery networks

No delivery agent within the SHIPSI network is available. This may be based on destination coverage and/or timing of delivery.

Expanding Responses

Some objects allow the request for more information shown as an expanded response using the expand request parameter. On all API requests this parameter is available, but only applies to that request alone. Responses can be expanded once or multiple times in nested fashion.

To expand a response you must use the applicable related object ID within the response properties given. A good example of this is the Compare Rates API request will return quote IDs. Those quote ID objects can be expanded inline with the expand request parameter. Within this documentation we note objects which can be expanded with the expand request parameter.

You can expand recursively by specifying nested fields after a dot (.). For example, requesting location_id.location_package on shipping rate will expand the location_id property into a full Location object, and will then expand the location_package property on that location into a full Package object.

This parameter can be used on any endpoint that returns expandable fields. Using multiple deep expansions on requests can be slow.

Expansions have a maximum depth of three levels.

Idempotent Responses

The Shipsi API supports built in idempotency. Many requests can be retried with the same parameters repeatedly and not cause any negative result.

Requests to endpoints which action events that carry a cost or associated live event are idempotent by default. All of these requests must be unique or will fail.

Request results only save if an endpoint starts executing. If request parameters failed validation, or the request conflicted with another that was executing concurrently, no idempotent result is saved because no API endpoint began execution. These requests can always be retried.

Create Label with Shipsi

Using Shipsi's REST API, create label with respect of delivery provider for your business.

Below we will explore how to create label

Get label by posting to the Create Label resource

Create Label Resource

To use the Create Label resource, make an HTTP POST to the resource:

https://app.shipsi.com/api/v1/label

Create Label

https://app.shipsi.com/api/v1/label/create

Parameters

retailer_child_id

ID of the sub account requested for create label.

label_format

Optional field, value should be zpl.

shipsi_delivery_id

required

Shipsi delivery id is used to identify which order needs to create label.

Returns

Returns a link of pdf if the call succeeded.

content

File content of label

filename

File name of label

Stuck?

No problem! Get help now from our support team to get you up and running.

Create Order Label

CURL


curl --location --request POST 'https://app.shipsi.com/api/v1/label/create' \
--header 'Content-Type: application/json' \
--header 'x-api-key: XXXXXXXXXX' \
--header 'x-api-pass: XXXXXXXXXXXXX' \
--header 'mode: live' \
--data-raw '{
      "retailer_child_id" : "cus_XXXXXXX",
      "label_format" : "zpl",
      "shipsi_delivery_id": "32435txxxx45d465"
}'

Example JSON API response


{
    "content": "data:application/pdf;base64,JVBERi0xLjcKMSAwIG9iago8PCA....",
    "filename": 32435txxxx45d465-label.pdf,
    "status": true,
    "error_code": "",
    "message": "Label created."
}

Create Order Label

CURL


curl --location --request POST 'https://app.shipsi.com/api/v1/label/create' \
--header 'Content-Type: application/json' \
--header 'x-api-key: XXXXXXXXXX' \
--header 'x-api-pass: XXXXXXXXXXXXX' \
--header 'mode: live' \
--data-raw '{
      "retailer_child_id" : "cus_XXXXXXX",
      "label_format" : "zpl",
      "shipsi_delivery_id": "32435txxxx45d465"
}'

Example JSON API response


{
    "content": "data:application/pdf;base64,JVBERi0xLjcKMSAwIG9iago8PCA....",
    "filename": 32435txxxx45d465-label.pdf,
    "status": true,
    "error_code": "",
    "message": "Label created."
}

Create Order Label

CURL


curl --location --request POST 'https://app.shipsi.com/api/v1/label/create' \
--header 'Content-Type: application/json' \
--header 'x-api-key: XXXXXXXXXX' \
--header 'x-api-pass: XXXXXXXXXXXXX' \
--header 'mode: live' \
--data-raw '{
      "retailer_child_id" : "cus_XXXXXXX",
      "label_format" : "zpl",
      "shipsi_delivery_id": "32435txxxx45d465"
}'

Example JSON API response


{
    "content": "data:application/pdf;base64,JVBERi0xLjcKMSAwIG9iago8PCA....",
    "filename": 32435txxxx45d465-label.pdf,
    "status": true,
    "error_code": "",
    "message": "Label created."
}

Create Order Label

CURL


curl --location --request POST 'https://app.shipsi.com/api/v1/label/create' \
--header 'Content-Type: application/json' \
--header 'x-api-key: XXXXXXXXXX' \
--header 'x-api-pass: XXXXXXXXXXXXX' \
--header 'mode: live' \
--data-raw '{
      "retailer_child_id" : "cus_XXXXXXX",
      "label_format" : "zpl",
      "shipsi_delivery_id": "32435txxxx45d465"
}'

Example JSON API response


{
    "content": "data:application/pdf;base64,JVBERi0xLjcKMSAwIG9iago8PCA....",
    "filename": 32435txxxx45d465-label.pdf,
    "status": true,
    "error_code": "",
    "message": "Label created."
}

Create Order Label

CURL


curl --location --request POST 'https://app.shipsi.com/api/v1/label/create' \
--header 'Content-Type: application/json' \
--header 'x-api-key: XXXXXXXXXX' \
--header 'x-api-pass: XXXXXXXXXXXXX' \
--header 'mode: live' \
--data-raw '{
      "retailer_child_id" : "cus_XXXXXXX",
      "label_format" : "zpl",
      "shipsi_delivery_id": "32435txxxx45d465"
}'

Example JSON API response


{
    "content": "data:application/pdf;base64,JVBERi0xLjcKMSAwIG9iago8PCA....",
    "filename": 32435txxxx45d465-label.pdf,
    "status": true,
    "error_code": "",
    "message": "Label created."
}

Create Order Label

CURL


curl --location --request POST 'https://app.shipsi.com/api/v1/label/create' \
--header 'Content-Type: application/json' \
--header 'x-api-key: XXXXXXXXXX' \
--header 'x-api-pass: XXXXXXXXXXXXX' \
--header 'mode: live' \
--data-raw '{
      "retailer_child_id" : "cus_XXXXXXX",
      "label_format" : "zpl",
      "shipsi_delivery_id": "32435txxxx45d465"
}'

Example JSON API response


{
    "content": "data:application/pdf;base64,JVBERi0xLjcKMSAwIG9iago8PCA....",
    "filename": 32435txxxx45d465-label.pdf,
    "status": true,
    "error_code": "",
    "message": "Label created."
}

Create Order Label

CURL


curl --location --request POST 'https://app.shipsi.com/api/v1/label/create' \
--header 'Content-Type: application/json' \
--header 'x-api-key: XXXXXXXXXX' \
--header 'x-api-pass: XXXXXXXXXXXXX' \
--header 'mode: live' \
--data-raw '{
      "retailer_child_id" : "cus_XXXXXXX",
      "label_format" : "zpl",
      "shipsi_delivery_id": "32435txxxx45d465"
}'

Example JSON API response


{
    "content": "data:application/pdf;base64,JVBERi0xLjcKMSAwIG9iago8PCA....",
    "filename": 32435txxxx45d465-label.pdf,
    "status": true,
    "error_code": "",
    "message": "Label created."
}

Create Order Label

CURL


curl --location --request POST 'https://app.shipsi.com/api/v1/label/create' \
--header 'Content-Type: application/json' \
--header 'x-api-key: XXXXXXXXXX' \
--header 'x-api-pass: XXXXXXXXXXXXX' \
--header 'mode: live' \
--data-raw '{
      "retailer_child_id" : "cus_XXXXXXX",
      "label_format" : "zpl",
      "shipsi_delivery_id": "32435txxxx45d465"
}'

Example JSON API response


{
    "content": "data:application/pdf;base64,JVBERi0xLjcKMSAwIG9iago8PCA....",
    "filename": 32435txxxx45d465-label.pdf,
    "status": true,
    "error_code": "",
    "message": "Label created."
}

Create Order Label

CURL


curl --location --request POST 'https://app.shipsi.com/api/v1/label/create' \
--header 'Content-Type: application/json' \
--header 'x-api-key: XXXXXXXXXX' \
--header 'x-api-pass: XXXXXXXXXXXXX' \
--header 'mode: live' \
--data-raw '{
      "retailer_child_id" : "cus_XXXXXXX",
      "label_format" : "zpl",
      "shipsi_delivery_id": "32435txxxx45d465"
}'

Example JSON API response


{
    "content": "data:application/pdf;base64,JVBERi0xLjcKMSAwIG9iago8PCA....",
    "filename": 32435txxxx45d465-label.pdf,
    "status": true,
    "error_code": "",
    "message": "Label created."
}

Create Order Label

CURL

curl --location --request POST 'https://app.shipsi.com/api/v1/shippingrates/getrate' \
--header 'x-api-key: XXXXXXXXXX' \
--header 'x-api-pass: XXXXXXXXXXXX' \
--header 'mode: live' \
--header 'Content-Type: application/json' \
\
--data-raw '{
"rate": {
"destination": {
"country": "US",
"postal_code": "91504",
"province": "CA",
"city": "Burbank",
"name": "Mallory Orr",
"address1": "2512 N Ontario St",
"address2": "",
"address3": null,
"phone": "(714) 651-4624",
"email": null,
"company_name": ""
},
"items": [
{
"name": "STAR BALLOON",
"sku": "362-2631-48",
"quantity": 1,
"weight": "",
"price": 199

}

],
"currency": "USD",
"locale": "en",
"location_id":"",
}
}

Example JSON API response

{
"rates": [
{
"service_name": "SHIPSI delivery",
"description": "30 hour delivery",
"locationid": "5b7ba0bb830552bb77070da2",
"delivery_network": "ts2",
"quote_code": "dqt_MKxwToNW2gfr6k",
"total_price": "832",
"currency": "usd",
"dropoff_eta": "24"
}
],
"message": "All delivery rates."
}

Create Order Label

CURL

Example JSON API response

Create Order Label

CURL

Example JSON API response

Get Direct Delivery Rate

CURL


curl --location --request POST 'https://app.shipsi.com/api/v1/direct/getrate' \
--header 'Content-Type: application/json' \
--header 'x-api-key: XXXXXXXXXX' \
--header 'x-api-pass: xxxxxxxxxxxxx' \
--header 'mode: live' \
--data-raw '{
	
	"qualified_pickup_locations": {
            "direct_delivery_pickup": {
                  "location": {
                        "address_line1": "400 Jefferson St",
                        "address_line2": "",
                        "city": "San Francisco",
                        "state": "CA",
                        "zip_code": "94109",
                        "country": "US"
                  }
            }
      },
	"destination": {
		"location": {
			"address_line1": "212 Pacific Ave",
			"address_line2": "Apt 2",
			"city": "San Francisco",
			"state": "CA",
			"country": "US",
			"zip_code": "94109"
		},
		"order_items": [{
				"item_name": "Widget A",
				"content_category": "",
				"content_sub-category": "",
				"quantity": "1",
				"price": "1600",
				"currency_code": "usd",
				"sku": "A991",
				"weight": "",
				"volume": "",
				"dimensions": ""
			},
			{
				"item_name": "Widget B",
				"content_category": "",
				"content_sub-category": "",
				"quantity": "1",
				"price": "1400",
				"currency_code": "usd",
				"sku": "B991",
				"weight": "",
				"volume": "",
				"dimensions": ""
			}
		]
	}
	
}'

Example JSON API response


{
    "service_name": "SHIPSI Instant Delivery",
    "description": "3 hour delivery with real-time tracking.",
    "delivery_network": "ts5",
    "quote_code": "5f7492a8b21d8cb4474e720f",
    "consumer_delivery_price": 1500,
    "shipsi_delivery_price": 1100,
    "currency_code": "usd",
    "status": true,
    "error_code": "",
    "message": "All delivery rates.",
    "direct_delivery_pickup": {
            "location": {
                  "address_line1": "400 Jefferson St",
                  "address_line2": "",
                  "city": "San Francisco",
                  "state": "CA",
                  "zip_code": "94109",
                  "country": "US"
            }
      }
}

API Reference

Create Order Label

Shipsi’s REST API’s

What is a REST API?

Base URL

Authentication

Errors

HTTP STATUS CODE SUMMARY

API Error Responses

Expanding Responses

Idempotent Responses

Create Label with Shipsi

Create Label Resource

Create Label

Parameters

retailer_child_id

label_format

shipsi_delivery_id

required

Returns

content

filename

Stuck?

Create Order Label

Create Order Label

Create Order Label

Create Order Label

Create Order Label

Create Order Label

Create Order Label

Create Order Label

Create Order Label

Create Order Label

Create Order Label

Create Order Label

Get Direct Delivery Rate