ShipStation API v2 (2.0.0)

Download OpenAPI description
Overview
License MIT
Languages
Servers
Mock server
https://docs.shipstation.com/_mock/openapi/
Production
https://api.shipstation.com/

Batches

Process labels in bulk and receive a large number of labels and customs forms in bulk responses. Batching is ideal for workflows that need to process hundreds or thousands of labels quickly.

Operations

Carriers

Retreive useful details about the carriers connected to your accounts, including carrier IDs, service IDs, advanced options, and available carrier package types.

Operations

Downloads

Download your label files in PDF, PNG, and ZPL.

Operations

Labels

Purchase and print shipping labels for any carrier active on your account. The labels endpoint also supports creating return labels, voiding labels, and getting label details like tracking.

Operations

Manifests

A manifest is a document that provides a list of the day's shipments. It typically contains a barcode that allows the pickup driver to scan a single document to register all shipments, rather than scanning each shipment individually.

Operations

Package Pickups

Scheduled pickups and manage pickup requests for supported carriers.

Operations

List scheduled pickups

Request

List all pickups that have been scheduled for this carrier

Query
carrier_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$

Carrier ID

Example: carrier_id=se-28529731
warehouse_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$

Warehouse ID

Example: warehouse_id=se-28529731
created_at_startstring(date-time)

Used to create a filter for when a resource was created (ex. A shipment that was created after a certain time)

Example: created_at_start=2019-03-12T19:24:13.657Z
created_at_endstring(date-time)

Used to create a filter for when a resource was created, (ex. A shipment that was created before a certain time)

Example: created_at_end=2019-03-12T19:24:13.657Z
pageinteger(int32)>= 1

Return a specific page of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page is returned.

Default 1
Example: page=2
page_sizeinteger(int32)>= 1

The number of results to return per response.

Default 25
Example: page_size=50
curl -i -X GET \
  'https://docs.shipstation.com/_mock/openapi/v2/pickups?carrier_id=se-28529731&created_at_end=2019-08-24T14%3A15%3A22Z&created_at_start=2019-08-24T14%3A15%3A22Z&page=1&page_size=25&warehouse_id=se-28529731' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

The request was a success.

Bodyapplication/json
pickupsArray of objects(pickup)required

An array of pickups associated with the user's account.

pickups[].​pickup_idstring(pickup_resource_id)>= 4 charactersread-only

Pickup Resource ID

Example: "pik_3YcKU5zdtJuCqoeNwyqqbW"
pickups[].​label_idsArray of strings(se_id)

Label IDs that will be included in the pickup request

Example: ["se-28529731"]
pickups[].​created_atstring(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...read-only

An ISO 8601 string that represents a date and time.

Example: "2018-09-23T15:00:00.000Z"
pickups[].​cancelled_atstring(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...read-only

An ISO 8601 string that represents a date and time.

Example: "2018-09-23T15:00:00.000Z"
pickups[].​carrier_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-only

A string that uniquely identifies a ShipStation resource, such as a carrier, label, shipment, etc.

Example: "se-28529731"
pickups[].​confirmation_numberstring or nullread-only

The carrier confirmation number for the scheduled pickup.

Example: "292513CL4A3"
pickups[].​warehouse_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-only

A string that uniquely identifies a ShipStation resource, such as a carrier, label, shipment, etc.

Example: "se-28529731"
pickups[].​pickup_addressobject(address)read-only

A complete or partial mailing address.

pickups[].​contact_detailsobject(contact_details)
pickups[].​pickup_notesstring>= 0 characters

Used by some carriers to give special instructions for a package pickup

Example: "call before 15:00"
pickups[].​pickup_windowsArray of objects(pickup_windows)read-only

An array of available pickup windows. Carriers can return multiple times that they will pickup packages.

totalinteger(int64)>= 0read-onlyrequired

The total number of pickups returned

Example: 3
pageinteger(int32)>= 1read-onlyrequired

Current page of the list pickups results

Example: 3
pagesinteger(int32)>= 1read-onlyrequired

Total number of pages for list pickups results

Example: 4
linksobject(pagination_link)read-onlyrequired

Helpful links to other pages of results

links.​firstobject(link)required

A link to a related resource, or an empty object if there is no resource to link to

links.​first.​hrefstring(url)(url)non-emptyrequired

A URL

Example: "http://api.shipstation.com/v2/labels/se-28529731"
links.​first.​typestringnon-empty

The type of resource, or the type of relationship to the parent resource

Example: "child"
links.​lastobject(link)required

A link to a related resource, or an empty object if there is no resource to link to

links.​last.​hrefstring(url)(url)non-emptyrequired

A URL

Example: "http://api.shipstation.com/v2/labels/se-28529731"
links.​last.​typestringnon-empty

The type of resource, or the type of relationship to the parent resource

Example: "child"
links.​prevobject(optional_link)required

A link to a related resource, or an empty object if there is no resource to link to

links.​prev.​hrefstring(url)(url)non-empty

A URL

Example: "http://api.shipstation.com/v2/labels/se-28529731"
links.​prev.​typestringnon-empty

The type of resource, or the type of relationship to the parent resource

Example: "child"
links.​nextobject(optional_link)required

A link to a related resource, or an empty object if there is no resource to link to

links.​next.​hrefstring(url)(url)non-empty

A URL

Example: "http://api.shipstation.com/v2/labels/se-28529731"
links.​next.​typestringnon-empty

The type of resource, or the type of relationship to the parent resource

Example: "child"
request_idstring(uuid)(uuid)= 36 characters^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...required

A UUID (a.k.a. GUID) that uniquely identifies a resource

Example: "aa3d8e8e-462b-4476-9618-72db7f7b7009"
errorsArray of objects(error)read-onlyrequired

The errors associated with the failed API call

errors[].​error_sourcestring(error_source)required

The source of the error, as indicated by the name this informs us if the API call failed because of the carrier, the order source, or the ShipStation API itself.

Enum"carrier""order_source""ShipStation"
errors[].​error_typestring(error_type)required

The type of error

Enum"account_status""business_rules""validation""security""system""integrations"
errors[].​error_codestring(error_code)required

The error code specified for the failed API Call

Enum"auto_fund_not_supported""batch_cannot_be_modified""carrier_conflict""carrier_disconnected""carrier_not_connected""carrier_not_supported""confirmation_not_supported""default_warehouse_cannot_be_deleted""field_conflict""field_value_required"
errors[].​messagestringnon-emptyread-onlyrequired

An error message associated with the failed API call

Example: "Body of request cannot be null."
Response
application/json
{ "pickups": [ {} ], "total": 3, "page": 3, "pages": 4, "links": { "first": {}, "last": {}, "prev": {}, "next": {} }, "request_id": "aa3d8e8e-462b-4476-9618-72db7f7b7009", "errors": [ {} ] }

Schedule a pickup

Request

Schedule a package pickup with a carrier

Bodyapplication/jsonrequired
label_idsArray of strings(se_id)required

Label IDs that will be included in the pickup request

Example: ["se-28529731"]
contact_detailsobject(contact_details)required
contact_details.​namestringnon-emptyrequired
Example: "Jonh"
contact_details.​emailstring(email)(email)non-emptyrequired

An email address.

Example: "john.doe@example.com"
contact_details.​phonestring>= 7 charactersrequired

Phone number associated

Example: "89876752562"
pickup_notesstring>= 0 characters

Used by some carriers to give special instructions for a package pickup

Example: "call before 15:00"
pickup_windowobject(pickup_window)write-onlyrequired

The desired time range for the package pickup.

pickup_window.​start_atstring(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...required

An ISO 8601 string that represents a date and time.

Example: "2018-09-23T15:00:00.000Z"
pickup_window.​end_atstring(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...required

An ISO 8601 string that represents a date and time.

Example: "2018-09-23T15:00:00.000Z"
curl -i -X POST \
  https://docs.shipstation.com/_mock/openapi/v2/pickups \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "label_ids": [
      "se-28529731"
    ],
    "contact_details": {
      "name": "Jonh",
      "email": "email@email.com",
      "phone": "89876752562"
    },
    "pickup_notes": "call before 15:00",
    "pickup_window": {
      "start_at": "2018-09-23T15:00:00.000Z",
      "end_at": "2018-09-23T15:00:00.000Z"
    }
  }'

Responses

The request was a success.

Bodyapplication/json
pickup_idstring(pickup_resource_id)>= 4 charactersread-onlyrequired

Pickup Resource ID

Example: "pik_3YcKU5zdtJuCqoeNwyqqbW"
label_idsArray of strings(se_id)required

Label IDs that will be included in the pickup request

Example: ["se-28529731"]
created_atstring(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...read-onlyrequired

An ISO 8601 string that represents a date and time.

Example: "2018-09-23T15:00:00.000Z"
cancelled_atstring(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...read-only

An ISO 8601 string that represents a date and time.

Example: "2018-09-23T15:00:00.000Z"
carrier_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-onlyrequired

A string that uniquely identifies a ShipStation resource, such as a carrier, label, shipment, etc.

Example: "se-28529731"
confirmation_numberstring or nullread-onlyrequired

The carrier confirmation number for the scheduled pickup.

Example: "292513CL4A3"
warehouse_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-onlyrequired

A string that uniquely identifies a ShipStation resource, such as a carrier, label, shipment, etc.

Example: "se-28529731"
pickup_addressobject(address)read-onlyrequired

A complete or partial mailing address.

pickup_address.​namestringnon-emptyrequired

The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.

Example: "John Doe"
pickup_address.​phonestringnon-emptyrequired

The phone number of a contact person at this address. The format of this phone number varies depending on the country.

Example: "+1 204-253-9411 ext. 123"
pickup_address.​emailstring or null

Email for the address owner.

Example: "example@example.com"
pickup_address.​company_namestring or nullnon-empty

If this is a business address, then the company name should be specified here.

Example: "The Home Depot"
pickup_address.​address_line1stringnon-emptyrequired

The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.

Example: "1999 Bishop Grandin Blvd."
pickup_address.​address_line2string or nullnon-empty

The second line of the street address. For some addresses, this line may not be needed.

Example: "Unit 408"
pickup_address.​address_line3string or nullnon-empty

The third line of the street address. For some addresses, this line may not be needed.

Example: "Building #7"
pickup_address.​city_localitystringnon-emptyrequired

The name of the city or locality

Example: "Winnipeg"
pickup_address.​state_provincestringnon-emptyrequired

The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.

Example: "Manitoba"
pickup_address.​postal_codestring(postal_code)non-emptyrequired

postal code

Example: "78756-3717"
pickup_address.​country_codestring(country_code)= 2 charactersrequired
Example: "CA"
pickup_address.​address_residential_indicatorstring(address_residential_indicator)required

Indicates whether an address is residential.

Default "unknown"
Enum"unknown""yes""no"
Example: "no"
contact_detailsobject(contact_details)required
contact_details.​namestringnon-emptyrequired
Example: "Jonh"
contact_details.​emailstring(email)(email)non-emptyrequired

An email address.

Example: "john.doe@example.com"
contact_details.​phonestring>= 7 charactersrequired

Phone number associated

Example: "89876752562"
pickup_notesstring>= 0 characters

Used by some carriers to give special instructions for a package pickup

Example: "call before 15:00"
pickup_windowsArray of objects(pickup_windows)read-only

An array of available pickup windows. Carriers can return multiple times that they will pickup packages.

request_idstring(uuid)(uuid)= 36 characters^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...required

A UUID (a.k.a. GUID) that uniquely identifies a resource

Example: "aa3d8e8e-462b-4476-9618-72db7f7b7009"
errorsArray of objects(error)read-onlyrequired

The errors associated with the failed API call

errors[].​error_sourcestring(error_source)required

The source of the error, as indicated by the name this informs us if the API call failed because of the carrier, the order source, or the ShipStation API itself.

Enum"carrier""order_source""ShipStation"
errors[].​error_typestring(error_type)required

The type of error

Enum"account_status""business_rules""validation""security""system""integrations"
errors[].​error_codestring(error_code)required

The error code specified for the failed API Call

Enum"auto_fund_not_supported""batch_cannot_be_modified""carrier_conflict""carrier_disconnected""carrier_not_connected""carrier_not_supported""confirmation_not_supported""default_warehouse_cannot_be_deleted""field_conflict""field_value_required"
errors[].​messagestringnon-emptyread-onlyrequired

An error message associated with the failed API call

Example: "Body of request cannot be null."
Response
application/json
{ "pickup_id": "pik_3YcKU5zdtJuCqoeNwyqqbW", "label_ids": [ "se-28529731" ], "created_at": "2018-09-23T15:00:00.000Z", "cancelled_at": "2018-09-23T15:00:00.000Z", "carrier_id": "se-1234567", "confirmation_number": "292513CL4A3", "warehouse_id": "se-28529731", "pickup_address": { "name": "John Doe", "phone": "+1 204-253-9411 ext. 123", "email": "example@example.com", "company_name": "The Home Depot", "address_line1": "1999 Bishop Grandin Blvd.", "address_line2": "Unit 408", "address_line3": "Building #7", "city_locality": "Winnipeg", "state_province": "Manitoba", "postal_code": "78756-3717", "country_code": "CA", "address_residential_indicator": "no" }, "contact_details": { "name": "Jonh", "email": "email@email.com", "phone": "89876752562" }, "pickup_notes": "call before 15:00", "pickup_windows": [ {} ], "request_id": "aa3d8e8e-462b-4476-9618-72db7f7b7009", "errors": [ {} ] }

Get pickup by id

Request

Get Pickup By ID

Path
pickup_idstring(pickup_resource_id)>= 4 charactersrequired

Pickup Resource ID

Example: pik_3YcKU5zdtJuCqoeNwyqqbW
curl -i -X GET \
  'https://docs.shipstation.com/_mock/openapi/v2/pickups/{pickup_id}' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

The request was a success.

Bodyapplication/json
pickup_idstring(pickup_resource_id)>= 4 charactersread-onlyrequired

Pickup Resource ID

Example: "pik_3YcKU5zdtJuCqoeNwyqqbW"
label_idsArray of strings(se_id)required

Label IDs that will be included in the pickup request

Example: ["se-28529731"]
created_atstring(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...read-onlyrequired

An ISO 8601 string that represents a date and time.

Example: "2018-09-23T15:00:00.000Z"
cancelled_atstring(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...read-only

An ISO 8601 string that represents a date and time.

Example: "2018-09-23T15:00:00.000Z"
carrier_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-onlyrequired

A string that uniquely identifies a ShipStation resource, such as a carrier, label, shipment, etc.

Example: "se-28529731"
confirmation_numberstring or nullread-onlyrequired

The carrier confirmation number for the scheduled pickup.

Example: "292513CL4A3"
warehouse_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-onlyrequired

A string that uniquely identifies a ShipStation resource, such as a carrier, label, shipment, etc.

Example: "se-28529731"
pickup_addressobject(address)read-onlyrequired

A complete or partial mailing address.

pickup_address.​namestringnon-emptyrequired

The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.

Example: "John Doe"
pickup_address.​phonestringnon-emptyrequired

The phone number of a contact person at this address. The format of this phone number varies depending on the country.

Example: "+1 204-253-9411 ext. 123"
pickup_address.​emailstring or null

Email for the address owner.

Example: "example@example.com"
pickup_address.​company_namestring or nullnon-empty

If this is a business address, then the company name should be specified here.

Example: "The Home Depot"
pickup_address.​address_line1stringnon-emptyrequired

The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.

Example: "1999 Bishop Grandin Blvd."
pickup_address.​address_line2string or nullnon-empty

The second line of the street address. For some addresses, this line may not be needed.

Example: "Unit 408"
pickup_address.​address_line3string or nullnon-empty

The third line of the street address. For some addresses, this line may not be needed.

Example: "Building #7"
pickup_address.​city_localitystringnon-emptyrequired

The name of the city or locality

Example: "Winnipeg"
pickup_address.​state_provincestringnon-emptyrequired

The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.

Example: "Manitoba"
pickup_address.​postal_codestring(postal_code)non-emptyrequired

postal code

Example: "78756-3717"
pickup_address.​country_codestring(country_code)= 2 charactersrequired
Example: "CA"
pickup_address.​address_residential_indicatorstring(address_residential_indicator)required

Indicates whether an address is residential.

Default "unknown"
Enum"unknown""yes""no"
Example: "no"
contact_detailsobject(contact_details)required
contact_details.​namestringnon-emptyrequired
Example: "Jonh"
contact_details.​emailstring(email)(email)non-emptyrequired

An email address.

Example: "john.doe@example.com"
contact_details.​phonestring>= 7 charactersrequired

Phone number associated

Example: "89876752562"
pickup_notesstring>= 0 characters

Used by some carriers to give special instructions for a package pickup

Example: "call before 15:00"
pickup_windowsArray of objects(pickup_windows)read-only

An array of available pickup windows. Carriers can return multiple times that they will pickup packages.

request_idstring(uuid)(uuid)= 36 characters^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...required

A UUID (a.k.a. GUID) that uniquely identifies a resource

Example: "aa3d8e8e-462b-4476-9618-72db7f7b7009"
errorsArray of objects(error)read-onlyrequired

The errors associated with the failed API call

errors[].​error_sourcestring(error_source)required

The source of the error, as indicated by the name this informs us if the API call failed because of the carrier, the order source, or the ShipStation API itself.

Enum"carrier""order_source""ShipStation"
errors[].​error_typestring(error_type)required

The type of error

Enum"account_status""business_rules""validation""security""system""integrations"
errors[].​error_codestring(error_code)required

The error code specified for the failed API Call

Enum"auto_fund_not_supported""batch_cannot_be_modified""carrier_conflict""carrier_disconnected""carrier_not_connected""carrier_not_supported""confirmation_not_supported""default_warehouse_cannot_be_deleted""field_conflict""field_value_required"
errors[].​messagestringnon-emptyread-onlyrequired

An error message associated with the failed API call

Example: "Body of request cannot be null."
Response
application/json
{ "pickup_id": "pik_3YcKU5zdtJuCqoeNwyqqbW", "label_ids": [ "se-28529731" ], "created_at": "2018-09-23T15:00:00.000Z", "cancelled_at": "2018-09-23T15:00:00.000Z", "carrier_id": "se-1234567", "confirmation_number": "292513CL4A3", "warehouse_id": "se-28529731", "pickup_address": { "name": "John Doe", "phone": "+1 204-253-9411 ext. 123", "email": "example@example.com", "company_name": "The Home Depot", "address_line1": "1999 Bishop Grandin Blvd.", "address_line2": "Unit 408", "address_line3": "Building #7", "city_locality": "Winnipeg", "state_province": "Manitoba", "postal_code": "78756-3717", "country_code": "CA", "address_residential_indicator": "no" }, "contact_details": { "name": "Jonh", "email": "email@email.com", "phone": "89876752562" }, "pickup_notes": "call before 15:00", "pickup_windows": [ {} ], "request_id": "aa3d8e8e-462b-4476-9618-72db7f7b7009", "errors": [ {} ] }

Delete a scheduled pickup

Request

Delete a previously-scheduled pickup by ID

Path
pickup_idstring(pickup_resource_id)>= 4 charactersrequired

Pickup Resource ID

Example: pik_3YcKU5zdtJuCqoeNwyqqbW
curl -i -X DELETE \
  'https://docs.shipstation.com/_mock/openapi/v2/pickups/{pickup_id}' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

Return the pickup_id of the scheduled pickup that was successfully deleted

Bodyapplication/json
request_idstring(uuid)(uuid)= 36 characters^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...required

A UUID (a.k.a. GUID) that uniquely identifies a resource

Example: "aa3d8e8e-462b-4476-9618-72db7f7b7009"
errorsArray of objects(error)read-onlyrequired

The errors associated with the failed API call

errors[].​error_sourcestring(error_source)required

The source of the error, as indicated by the name this informs us if the API call failed because of the carrier, the order source, or the ShipStation API itself.

Enum"carrier""order_source""ShipStation"
errors[].​error_typestring(error_type)required

The type of error

Enum"account_status""business_rules""validation""security""system""integrations"
errors[].​error_codestring(error_code)required

The error code specified for the failed API Call

Enum"auto_fund_not_supported""batch_cannot_be_modified""carrier_conflict""carrier_disconnected""carrier_not_connected""carrier_not_supported""confirmation_not_supported""default_warehouse_cannot_be_deleted""field_conflict""field_value_required"
errors[].​messagestringnon-emptyread-onlyrequired

An error message associated with the failed API call

Example: "Body of request cannot be null."
pickup_idstring(pickup_resource_id)>= 4 charactersrequired

Pickup Resource ID

Example: "pik_3YcKU5zdtJuCqoeNwyqqbW"
Response
application/json
{ "request_id": "aa3d8e8e-462b-4476-9618-72db7f7b7009", "errors": [ {} ], "pickup_id": "pik_3YcKU5zdtJuCqoeNwyqqbW" }

Package Types

Create custom package types to use for your shipments, rather than the carriers' default package types.

Operations

Rates

Quickly compare rates using the Rates endpoint. You can see and compare rates for the carriers connected to your account (as long as they support sending rates).

Operations

Shipments

Shipments are at the core of most ShipStation capabilities. Shipment objects are required for cretaing labels and manifests, as well as getting rates.

Operations

Tags

Tags are text-based identifiers you can add to shipments to help in your shipment management workflows.

Operations

Tracking

Use the tracking endpoint to stop receiving tracking updates (more dedicated tracking endpoint methods coming soon).

Operations

Warehouses

Get warehouse details like warehouse ID and related addresses using the warehouses endpoint.

Operations

Webhooks

Webhooks are a powerful feature that can save you from sending repeated polling requests to check on the state of something. With webhooks, ShipStation will automatically contact your servers when the stage changes. This can include parcel tracking events, notification when a batch operation completes, and more.

Operations