Skip to content

Stallion Express API (4)

Access to the sandbox environment can be provided upon request. (Not all rates are available in the Sandbox environment). API token can be found under "Account Settings > API Token" in the Stallion Express dashboard. To help us assist you more effectively when troubleshooting, please make sure to include the Request-ID in your email communication.

Download OpenAPI description
stallionexpress-v4.json
stallionexpress-v4.yaml
Overview
API Support
developersupport@stallionexpress.ca
Languages
Servers
Mock server
https://stallionexpress.redocly.app/_mock/stallionexpress-v4
Production server (uses live data)
https://ship.stallionexpress.ca/api/v4
Sandbox server (uses test data)
https://sandbox.stallionexpress.ca/api/v4

Postage Types

Operations

Shipments

Operations

Get Rates

Request

Validates shipment details and returns all available rates.

Security
bearerAuth
Bodyapplication/jsonrequired

Shipment details

to_addressobjectrequired

Recipient address for the shipment.

to_address.​namestring<= 40 characters

The full name associated with the address.

Example: "Pramod Thomson"
to_address.​companystring or null<= 40 characters

The company name associated with the address, if applicable.

to_address.​address1string<= 50 characters

The primary street address or post office box number.

Example: "30 Clearview Dr"
to_address.​address2string or null<= 50 characters

Additional address information, such as suite or apartment number, if needed.

to_address.​citystring<= 35 characters

The city or locality of the address.

Example: "Rock Springs"
to_address.​province_codestring= 2 characters

The code for the state, province, or territory where the address is located.

Example: "WY"
to_address.​postal_codestring<= 10 characters

The postal or ZIP code for the address.

Example: "82901"
to_address.​country_codestring= 2 characters

The two-letter ISO code representing the country of the address.

Example: "US"
to_address.​phonestring or null<= 20 characters

The contact phone number for the address, if provided.

to_address.​emailstring or null<= 50 characters

The email address associated with the address, if available.

to_address.​is_residentialboolean

Specifies whether the address is residential. Assumed to be true unless indicated otherwise.

Default true
Example: true
return_addressobject

The return address is required exclusively for generating a return label and should only be provided if is_return is set to true. This field is not applicable to regular shipments.

is_returnboolean or null

Indicates if the shipment will be a return.

Example: false
weight_unitstring(WeightUnit)required
Enum"lbs""kg""g""oz"
weightnumberrequired

Represents the total weight of the shipment in the specified weight unit (e.g., kg, g, oz, or lbs).

Example: 0.6
lengthnumber

Specifies the length of the shipment package, measured in the designated size unit (e.g., in or cm). This measurement should correspond to the longest side of the package.

Example: 9
widthnumber

Indicates the width of the shipment package, measured in the designated size unit (e.g., in or sm). Width is typically the second longest side of the package, perpendicular to the length.

Example: 12
heightnumber

Defines the height of the shipment package, measured in the designated size unit (e.g., in or cm). Height is the dimension from the base to the top of the package, perpendicular to the length and width.

Example: 1
size_unitstring(SizeUnit)required
Enum"cm""in"
itemsArray of objects(Item)

An array of items in the shipment.

package_typePackageType (string) or PackageCode (string)required
One of:
string(PackageType)
Enum"Parcel""Legal Flat Rate Envelope""Flat Rate PAdded Envelope""Small Flat Rate Box""Medium Flat Rate Box 1""Medium Flat Rate Box 2""Large Flat Rate Box""Regional Rate Box A1""Regional Rate Box A2""Regional Rate Box B1"
postage_typesArray of PostageType (string) or PostageCode (string) or null

Limit the results to specific postage types

Example: []
signature_confirmationboolean or null

Indicates if the shipment should require a signature upon delivery.

Example: true
insuredboolean or null

Indicates if the shipment should have Stallion Protection.

Example: true
regionstring or null(RegionCode)

Default account region. The region where the shipment will be delivered to Stallion. Ability to change this is needs to be enabled by Stallion.

Enum"ON""BC""QC"
Example: null
tax_identifierobject

Information about tax identification for the shipment.

curl -i -X POST \
  https://stallionexpress.redocly.app/_mock/stallionexpress-v4/rates \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "to_address": {
      "name": "Pramod Thomson",
      "company": "string",
      "address1": "30 Clearview Dr",
      "address2": "string",
      "city": "Rock Springs",
      "province_code": "WY",
      "postal_code": "82901",
      "country_code": "US",
      "phone": "string",
      "email": "string",
      "is_residential": true
    },
    "return_address": {
      "name": "Pramod Thomson",
      "company": "string",
      "address1": "30 Clearview Dr",
      "address2": "string",
      "city": "Rock Springs",
      "province_code": "WY",
      "postal_code": "82901",
      "country_code": "US",
      "phone": "string",
      "email": "string",
      "is_residential": true
    },
    "is_return": false,
    "weight_unit": "lbs",
    "weight": 0.6,
    "length": 9,
    "width": 12,
    "height": 1,
    "size_unit": "cm",
    "items": [
      {
        "description": "Two pair of socks",
        "sku": "SKU123",
        "quantity": 2,
        "value": 10,
        "currency": "CAD",
        "country_of_origin": "CN",
        "hs_code": "123456",
        "manufacturer_name": "Acme Clothing Inc.",
        "manufacturer_address1": "123 Manufacturing Blvd",
        "manufacturer_city": "Toronto",
        "manufacturer_province_code": "ON",
        "manufacturer_postal_code": "M5V 2H1",
        "manufacturer_country_code": "CA"
      }
    ],
    "package_type": "Parcel",
    "postage_types": [],
    "signature_confirmation": true,
    "insured": true,
    "region": null,
    "tax_identifier": {
      "tax_type": "IOSS",
      "number": "IM1234567890",
      "issuing_authority": "GB"
    }
  }'

Responses

Successful operation

Headers
Request-Idstring

UUID for the request

Bodyapplication/json
successboolean
Example: true
ratesArray of objects(Rate)

Array of rates

Response
application/json
{
  "success": true,
  "rates": [
    { … }
  ]
}

Get Shipments

Request

Get the list of paginated shipments by different search parameters.

Security
bearerAuth
Query
from_datestring

return shipments with a created_at on or after the given date

to_datestring

return shipments with a created_at greater than or equal to the given date.

ship_codestring

search by ship code

to_namestring

search by recipient

tracking_codestring

search by tracking code

order_idstring

search by order id

batch_idstring

search by batch id

closeout_idstring

search by closeout id

statusArray of strings

search by shipment statuses

Items Enum"unpaid""postage-expired""pending""incomplete""ready""received""processing""in-transit""delivered""exception"
limitinteger

number of records to return per page

pageinteger

the current page number of the response

curl -i -X GET \
  'https://stallionexpress.redocly.app/_mock/stallionexpress-v4/shipments?from_date=string&to_date=string&ship_code=string&to_name=string&tracking_code=string&order_id=string&batch_id=string&closeout_id=string&status=unpaid&limit=0&page=0' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful operation

Headers
Request-Idstring

UUID for the request

Bodyapplication/json
dataArray of objects(ShipmentsResponse_data)
Example: [null]
linksobject(ShipmentsResponse_links)
Example: null
metaobject(ShipmentsResponse_meta)
Example: null
Response
application/json
{
  "data": [
    null
  ],
  "links": null,
  "meta": null
}

Create Shipment

Request

Create a shipment and return the postage label.

Security
bearerAuth
Headers
Idempotency-Keystring<= 255 characters

A unique key to ensure idempotent behavior of the request. If provided and a matching key was used in the last 24 hours, the previous shipment will be returned.

Bodyapplication/json

The shipment object that needs to be created. Note that size fields are required for any shipments with the package type of Parcel.

to_addressobjectrequired

Recipient address for the shipment.

to_address.​namestring<= 40 characters

The full name associated with the address.

Example: "Pramod Thomson"
to_address.​companystring or null<= 40 characters

The company name associated with the address, if applicable.

to_address.​address1string<= 50 characters

The primary street address or post office box number.

Example: "30 Clearview Dr"
to_address.​address2string or null<= 50 characters

Additional address information, such as suite or apartment number, if needed.

to_address.​citystring<= 35 characters

The city or locality of the address.

Example: "Rock Springs"
to_address.​province_codestring= 2 characters

The code for the state, province, or territory where the address is located.

Example: "WY"
to_address.​postal_codestring<= 10 characters

The postal or ZIP code for the address.

Example: "82901"
to_address.​country_codestring= 2 characters

The two-letter ISO code representing the country of the address.

Example: "US"
to_address.​phonestring or null<= 20 characters

The contact phone number for the address, if provided.

to_address.​emailstring or null<= 50 characters

The email address associated with the address, if available.

to_address.​is_residentialboolean

Specifies whether the address is residential. Assumed to be true unless indicated otherwise.

Default true
Example: true
return_addressobject

The return address is required exclusively for generating a return label and should only be provided if is_return is set to true. This field is not applicable to regular shipments.

is_returnboolean or null

Indicates if the shipment will be a return.

Example: false
order_idstring or null

The unique identifier for the order.

Example: "1234-1233"
weight_unitstring(WeightUnit)required
Enum"lbs""kg""g""oz"
weightnumberrequired
Example: 0.6
lengthnumber
Example: 9
widthnumber
Example: 12
heightnumber
Example: 1
size_unitstring(SizeUnit)required
Enum"cm""in"
itemsArray of objects(Item)
package_typePackageType (string) or PackageCode (string)
One of:
string(PackageType)
Enum"Parcel""Legal Flat Rate Envelope""Flat Rate PAdded Envelope""Small Flat Rate Box""Medium Flat Rate Box 1""Medium Flat Rate Box 2""Large Flat Rate Box""Regional Rate Box A1""Regional Rate Box A2""Regional Rate Box B1"
signature_confirmationboolean or null

Default false.

Example: false
postage_typePostageType (string) or PostageCode (string)

Set the postage type for the shipment. ("Cheapest Tracked" or "Cheapest Express Tracked" will return the cheapest tracked or express tracked postage type available.)

One of:

Set the postage type for the shipment. ("Cheapest Tracked" or "Cheapest Express Tracked" will return the cheapest tracked or express tracked postage type available.)

string(PostageType)
Enum"USPS First Class Mail""USPS Priority Mail""USPS Priority Mail Express""USPS Parcel Select Ground""USPS Media Mail""USPS Library Mail""USPS Express Mail International""USPS Priority Mail International""USPS First Class Mail International""FedEx Ground"
label_formatstring

Default pdf. Set the format of the returned label.

Default "pdf"
Enum"pdf""zpl""png"
is_fbaboolean or null

Default false. Set to true to create a Stallion FBA label.

Default false
Example: false
is_draftboolean or null

Default false. Set to true to save the shipment without purchasing the label.

Default false
Example: false
insuredboolean or null

Set to true to apply Stallion Protection for tracked shipments only.

Example: true
regionstring or null(RegionCode)

Default account region. The region where the shipment will be delivered to Stallion. Ability to change this is needs to be enabled by Stallion.

Enum"ON""BC""QC"
Example: null
tax_identifierobject

Information about tax identification for the shipment.

curl -i -X POST \
  https://stallionexpress.redocly.app/_mock/stallionexpress-v4/shipments \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: string' \
  -d '{
    "to_address": {
      "name": "Pramod Thomson",
      "company": "string",
      "address1": "30 Clearview Dr",
      "address2": "string",
      "city": "Rock Springs",
      "province_code": "WY",
      "postal_code": "82901",
      "country_code": "US",
      "phone": "string",
      "email": "string",
      "is_residential": true
    },
    "return_address": {
      "name": "Pramod Thomson",
      "company": "string",
      "address1": "30 Clearview Dr",
      "address2": "string",
      "city": "Rock Springs",
      "province_code": "WY",
      "postal_code": "82901",
      "country_code": "US",
      "phone": "string",
      "email": "string",
      "is_residential": true
    },
    "is_return": false,
    "order_id": "1234-1233",
    "weight_unit": "lbs",
    "weight": 0.6,
    "length": 9,
    "width": 12,
    "height": 1,
    "size_unit": "cm",
    "items": [
      {
        "description": "Two pair of socks",
        "sku": "SKU123",
        "quantity": 2,
        "value": 10,
        "currency": "CAD",
        "country_of_origin": "CN",
        "hs_code": "123456",
        "manufacturer_name": "Acme Clothing Inc.",
        "manufacturer_address1": "123 Manufacturing Blvd",
        "manufacturer_city": "Toronto",
        "manufacturer_province_code": "ON",
        "manufacturer_postal_code": "M5V 2H1",
        "manufacturer_country_code": "CA"
      }
    ],
    "package_type": "Parcel",
    "signature_confirmation": false,
    "postage_type": "USPS First Class Mail",
    "label_format": "pdf",
    "is_fba": false,
    "is_draft": false,
    "insured": true,
    "region": null,
    "tax_identifier": {
      "tax_type": "IOSS",
      "number": "IM1234567890",
      "issuing_authority": "GB"
    }
  }'

Responses

Successful operation

Headers
Request-Idstring

UUID for the request

Bodyapplication/json
successboolean
labelstring

Base 64 encoded label.

Example: "base64_label"
tracking_codestring
Example: "9400111969000940000011"
messagestring
Example: "Shipment successfully completed"
shipmentobject(Shipment)
Example: null
rateobject(Rate)
Response
application/json
{
  "success": true,
  "label": "base64_label",
  "tracking_code": "9400111969000940000011",
  "message": "Shipment successfully completed",
  "shipment": null,
  "rate": {
    "postage_type": "USPS First Class Mail",
    "package_type": "Parcel",
    "trackable": true,
    "base_rate": 10,
    "add_ons": [ … ],
    "rate": 10,
    "tax": 0,
    "total": 0,
    "currency": "CAD",
    "delivery_days": "2"
  }
}

Track Shipment

Request

Fetch a shipment tracking details by different search parameters

Security
bearerAuth
Query
ship_codestring

The ship_code or identifier of a shipment.

tracking_codestring

The tracking number of a shipment.

order_idstring

The order id of a shipment.

curl -i -X GET \
  'https://stallionexpress.redocly.app/_mock/stallionexpress-v4/track?ship_code=string&tracking_code=string&order_id=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful operation

Headers
Request-Idstring

UUID for the request

Bodyapplication/json
successboolean
Example: true
statusstring(ShipmentStatus)
Enum"Postage Expired""Pending""Incomplete""Ready""Received""Processing""In Transit""Delivered""Exception""Void Requested"
eventsArray of objects(TrackResponse_events)
Example: [null]
detailsobject
Response
application/json
{
  "success": true,
  "status": "Postage Expired",
  "events": [
    null
  ],
  "details": {
    "ship_code": 2012121234,
    "destination": "Toronto ON, CA",
    "tracking": "123123123123123123",
    "url": "https://carrier.com/track/9400111969000940000011",
    "carrier_phone": "12312341234"
  }
}

Get Shipment

Request

Get a shipment

Security
bearerAuth
Path
ship_codestringrequired

The ship_code of a shipment.

curl -i -X GET \
  'https://stallionexpress.redocly.app/_mock/stallionexpress-v4/shipments/{ship_code}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful operation

Headers
Request-Idstring

UUID for the request

Bodyapplication/json
successboolean
labelstring

Base 64 encoded label.

Example: "base64_label"
tracking_codestring
Example: "9400111969000940000011"
messagestring
Example: "Shipment successfully completed"
shipmentobject(Shipment)
Example: null
rateobject(Rate)
Response
application/json
{
  "success": true,
  "label": "base64_label",
  "tracking_code": "9400111969000940000011",
  "message": "Shipment successfully completed",
  "shipment": null,
  "rate": {
    "postage_type": "USPS First Class Mail",
    "package_type": "Parcel",
    "trackable": true,
    "base_rate": 10,
    "add_ons": [ … ],
    "rate": 10,
    "tax": 0,
    "total": 0,
    "currency": "CAD",
    "delivery_days": "2"
  }
}

Void Shipment

Request

Requests a void for a shipment with the provided id.

Security
bearerAuth
Path
ship_codestringrequired

The ship_code of a shipment.

curl -i -X GET \
  'https://stallionexpress.redocly.app/_mock/stallionexpress-v4/shipments/{ship_code}/void' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful operation

Headers
Request-Idstring

UUID for the request

Bodyapplication/json
successboolean
Example: true
messageboolean
Example: false
Response
application/json
{
  "success": true,
  "message": false
}

Orders

Operations

Stores

Operations

Batches

Operations

Locations

Operations

Credits

Operations