Stallion Express API (4.0)

Download OpenAPI specification:Download

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.

Postage Types

Get Postage Types

Get a list of all available postage types

SecuritybearerAuth
Responses
200

Successful operation

401

Unauthenticated

500

Internal error

get/postage-types
Request samples
Response samples
application/json
{
  • "success": true,
  • "postage_types": [
    ]
}

Shipments

Get Rates

Validates shipment details and returns all available rates.

SecuritybearerAuth
Request
Request Body schema: application/json
required

Shipment details

required
object

Recipient address for the shipment.

object

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_return
boolean or null

Indicates if the shipment will be a return.

weight_unit
required
string (WeightUnit)
Enum: "lbs" "kg" "g" "oz"
weight
required
number

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

length
number

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.

width
number

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.

height
number

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.

size_unit
required
string (SizeUnit)
Enum: "cm" "in"
Array of objects (Item)

An array of items in the shipment.

required
PackageType (string) or PackageCode (string)
Array of PostageType (string) or PostageCode (string) or null

Limit the results to specific postage types

signature_confirmation
boolean or null

Indicates if the shipment should require a signature upon delivery.

insured
boolean or null

Indicates if the shipment should have Stallion Protection.

region
string 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"
object

Information about tax identification for the shipment.

Responses
200

Successful operation

401

Unauthenticated

422

Validation Error

500

Internal error

post/rates
Request samples
application/json
{
  • "to_address": {
    },
  • "return_address": {
    },
  • "is_return": false,
  • "weight_unit": "lbs",
  • "weight": 0.6,
  • "length": 9,
  • "width": 12,
  • "height": 1,
  • "size_unit": "cm",
  • "items": [
    ],
  • "package_type": "Parcel",
  • "postage_types": [ ],
  • "signature_confirmation": true,
  • "insured": true,
  • "region": null,
  • "tax_identifier": {
    }
}
Response samples
application/json
{
  • "success": true,
  • "rates": [
    ]
}

Get Shipments

Get the list of paginated shipments by different search parameters.

SecuritybearerAuth
Request
query Parameters
from_date
string

return shipments with a created_at on or after the given date

to_date
string

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

ship_code
string

search by ship code

to_name
string

search by recipient

tracking_code
string

search by tracking code

order_id
string

search by order id

batch_id
string

search by batch id

closeout_id
string

search by closeout id

status
Array of strings

search by shipment statuses

Items Enum: "unpaid" "postage-expired" "pending" "incomplete" "ready" "received" "processing" "in-transit" "delivered" "exception" "void-requested" "voided" "complete"
limit
integer

number of records to return per page

page
integer

the current page number of the response

Responses
200

Successful operation

401

Unauthenticated

422

Validation Error

500

Internal error

get/shipments
Request samples
Response samples
application/json
{
  • "data": [
    ],
  • "links": null,
  • "meta": null
}

Create a New Shipment

Create a shipment and return the postage label.

SecuritybearerAuth
Request
header Parameters
Idempotency-Key
string <= 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.

Request Body schema: application/json

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

required
object

Recipient address for the shipment.

object

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_return
boolean or null

Indicates if the shipment will be a return.

weight_unit
required
string (WeightUnit)
Enum: "lbs" "kg" "g" "oz"
weight
required
number
length
number
width
number
height
number
size_unit
required
string (SizeUnit)
Enum: "cm" "in"
Array of objects (Item)
PackageType (string) or PackageCode (string)
signature_confirmation
boolean or null

Default false.

PostageType (string) or PostageCode (string)
label_format
string
Default: "pdf"

Default pdf. Set the format of the returned label.

Enum: "pdf" "zpl" "png"
is_fba
boolean or null
Default: false

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

is_draft
boolean or null
Default: false

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

insured
boolean or null

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

region
string 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"
object

Information about tax identification for the shipment.

Responses
200

Successful operation

401

Unauthenticated

422

Validation Error

500

Internal error

post/shipments
Request samples
application/json
{
  • "to_address": {
    },
  • "return_address": {
    },
  • "is_return": false,
  • "weight_unit": "lbs",
  • "weight": 0.6,
  • "length": 9,
  • "width": 12,
  • "height": 1,
  • "size_unit": "cm",
  • "items": [
    ],
  • "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": {
    }
}
Response samples
application/json
{
  • "success": true,
  • "label": "base64_label",
  • "tracking_code": "9400111969000940000011",
  • "message": "Shipment successfully completed",
  • "shipment": null,
  • "rate": {
    }
}

Track a Shipment

Fetch a shipment tracking details by different search parameters

SecuritybearerAuth
Request
query Parameters
ship_code
string

The ship_code or identifier of a shipment.

tracking_code
string

The tracking number of a shipment.

order_id
string

The order id of a shipment.

Responses
200

Successful operation

401

Unauthenticated

422

Validation Error

500

Internal error

get/track
Request samples
Response samples
application/json
{
  • "success": true,
  • "status": "Postage Expired",
  • "events": [
    ],
  • "details": {}
}

Get Shipment

Get a shipment

SecuritybearerAuth
Request
path Parameters
ship_code
required
string

The ship_code of a shipment.

Responses
200

Successful operation

401

Unauthenticated

404

Not Found

500

Internal error

get/shipments/{ship_code}
Request samples
Response samples
application/json
{
  • "success": true,
  • "label": "base64_label",
  • "tracking_code": "9400111969000940000011",
  • "message": "Shipment successfully completed",
  • "shipment": null,
  • "rate": {
    }
}

Void a Shipment

Requests a void for a shipment with the provided id.

SecuritybearerAuth
Request
path Parameters
ship_code
required
string

The ship_code of a shipment.

Responses
200

Successful operation

401

Unauthenticated

404

Not Found

422

Validation Error

500

Internal error

get/shipments/{ship_code}/void
Request samples
Response samples
application/json
{
  • "success": true,
  • "message": false
}

Orders

Get Orders

Get a paginated list of orders based on certain criteria.

SecuritybearerAuth
Request
query Parameters
limit
integer [ 10 .. 500 ]

The maximum number of orders to retrieve per page.

page
integer >= 1

The page number of results to retrieve.

order_id
string

Filter orders by a specific order ID.

from_date
string <date>

The start date for filtering orders (optional).

to_date
string <date>

The end date for filtering orders (optional). Must be after or equal to from_date.

Responses
200

Successful operation

401

Unauthenticated

500

Internal error

get/orders
Request samples
Response samples
application/json
{
  • "per_page": 100,
  • "to": 2,
  • "total": 2,
  • "success": true,
  • "data": [
    ]
}

Create Order

Create an order.

SecuritybearerAuth
Request
Request Body schema: application/json

The order object that needs to be created.

store_id
required
string

The unique identifier for the store.

name
required
string <= 40 characters

The name of the recipient.

company
string or null <= 40 characters

The company name of the recipient (optional).

address1
required
string <= 50 characters

The first line of the delivery address.

address2
string or null <= 50 characters

The second line of the delivery address (optional).

city
required
string <= 35 characters

The city where the recipient is located.

province_code
string = 2 characters

The two-letter province or state code where the recipient is located.

postal_code
string <= 10 characters

The postal code or ZIP code of the recipient's location.

country_code
required
string = 2 characters

The two-letter country code of the recipient's country.

phone
string or null <= 20 characters

The recipient's phone number (optional).

email
string or null <= 50 characters

The recipient's email address (optional).

customer_id
string or null <= 50 characters

The customer ID associated with the order (optional).

carrier_code
string or null <= 50 characters

The carrier code for shipping (optional).

postage_code
string or null <= 50 characters

The postage code for shipping (optional).

package_code
string or null <= 50 characters

The package code for shipping (optional).

note
string or null <= 255 characters

Additional notes or comments for the order (optional).

weight_unit
required
string (WeightUnit)
Enum: "lbs" "kg" "g" "oz"
weight
required
number >= 0.01

The weight of the order in the specified weight unit.

value
required
number >= 0.01

The total value of the order.

currency
required
string (Currency)
Enum: "CAD" "USD" "EUR" "AUD" "GBP"
order_id
required
string

The unique identifier for the order.

order_at
required
string <date-time>

The date and time when the order was placed.

store
string

Store Nickname or Identifier.

required
Array of objects (OrderRequestItem)

Order Line Items.

Responses
200

Successful operation

401

Unauthenticated

422

Validation Error

500

Internal error

post/orders
Request samples
application/json
{
  • "store_id": "1234",
  • "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",
  • "customer_id": "string",
  • "carrier_code": "string",
  • "postage_code": "string",
  • "package_code": "string",
  • "note": "string",
  • "weight_unit": "lbs",
  • "weight": 0.6,
  • "value": 10.5,
  • "currency": "CAD",
  • "order_id": "1234-1233",
  • "order_at": "2023-09-26 14:30:00",
  • "store": "My Shopify Store",
  • "items": [
    ]
}
Response samples
application/json
{
  • "success": true,
  • "order": {
    }
}

Get Order by ID

Retrieve a specific order by its unique ID.

SecuritybearerAuth
Request
path Parameters
id
required
string

The unique ID of the order to retrieve.

Responses
200

Successful operation

401

Unauthenticated

404

Order not found

500

Internal error

get/orders/{id}
Request samples
Response samples
application/json
{
  • "success": true,
  • "order": {
    }
}

Stores

Get Stores

Get a list of all stores associated with the authenticated user. (This only shows store create via the API.)

SecuritybearerAuth
Responses
200

Successful operation

401

Unauthenticated

500

Internal error

get/stores
Request samples
Response samples
application/json
{
  • "success": true,
  • "stores": [
    ]
}

Create Store

Create a new store for the authenticated user.

SecuritybearerAuth
Request
Request Body schema: application/json

The store data that needs to be created.

identifier
string

Unique identifier for the store

Responses
200

Successful operation

401

Unauthenticated

422

Validation Error

500

Internal error

post/stores
Request samples
application/json
{
  • "identifier": "string"
}
Response samples
application/json
{
  • "success": true,
  • "store": {
    }
}

Delete Store by ID

Delete a store by its unique ID.

SecuritybearerAuth
Request
path Parameters
id
required
integer

The unique ID of the store to delete.

Responses
200

Successful operation

401

Unauthenticated

404

Store not found

500

Internal error

delete/stores/{id}
Request samples
Response samples
application/json
{
  • "success": true
}

Batches

Create a batch

Creates a new batch to be used when creating shipments.

SecuritybearerAuth
Responses
200

Successful operation

401

Unauthenticated

500

Internal error

post/batches
Request samples
Response samples
application/json
{
  • "success": true,
  • "batch_id": "18179823"
}

Locations

Get Locations

Gets a list of all current Stallion Express locations.

SecuritybearerAuth
Responses
200

Successful operation

401

Unauthenticated

500

Internal error

get/locations
Request samples
Response samples
application/json
{
  • "success": true,
  • "locations": [
    ]
}

Credits

Get Credits

Return the current account balance

SecuritybearerAuth
Responses
200

successful operation

401

Unauthenticated

500

Internal error

get/credits
Request samples
Response samples
application/json
{
  • "success": true,
  • "amount": "0.00"
}

Add Credits

Add credits using hte account's default credit card

SecuritybearerAuth
Request
Request Body schema: application/json
required

Amount of credits to add

amount
integer <int64>
Responses
200

Successful operation

401

Unauthenticated

422

Validation Error

500

Internal error

post/credits
Request samples
application/json
{
  • "amount": 100
}
Response samples
application/json
{
  • "success": true,
  • "amount": "0.00"
}