# Create Shipment

Create a shipment and return the postage label.

Endpoint: POST /shipments
Version: 4
Security: bearerAuth

## Header parameters:

  - `Idempotency-Key` (string)
    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 fields (application/json):

  - `to_address` (object, required)
    Recipient address for the shipment.

  - `to_address.name` (string)
    The full name associated with the address.
    Example: "Pramod Thomson"

  - `to_address.company` (string,null)
    The company name associated with the address, if applicable.

  - `to_address.address1` (string)
    The primary street address or post office box number.
    Example: "30 Clearview Dr"

  - `to_address.address2` (string,null)
    Additional address information, such as suite or apartment number, if needed.

  - `to_address.city` (string)
    The city or locality of the address.
    Example: "Rock Springs"

  - `to_address.province_code` (string)
    The code for the state, province, or territory where the address is located.
    Example: "WY"

  - `to_address.postal_code` (string)
    The postal or ZIP code for the address.
    Example: "82901"

  - `to_address.country_code` (string)
    The two-letter ISO code representing the country of the address.
    Example: "US"

  - `to_address.phone` (string,null)
    The contact phone number for the address, if provided.

  - `to_address.email` (string,null)
    The email address associated with the address, if available.

  - `to_address.is_residential` (boolean)
    Specifies whether the address is residential. Assumed to be true unless indicated otherwise.
    Example: true

  - `return_address` (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,null)
    Indicates if the shipment will be a return.

  - `order_id` (string,null)
    The unique identifier for the order.
    Example: "1234-1233"

  - `weight_unit` (string, required)
    Enum: "lbs", "kg", "g", "oz"

  - `weight` (number, required)
    Example: 0.6

  - `length` (number)
    Example: 9

  - `width` (number)
    Example: 12

  - `height` (number)
    Example: 1

  - `size_unit` (string, required)
    Enum: "cm", "in"

  - `items` (array)

  - `items.description` (string)
    Example: "Two pair of socks"

  - `items.sku` (string,null)
    The SKU/ASIN of the item. Required for FBA shipments.
    Example: "SKU123"

  - `items.quantity` (integer)
    Example: 2

  - `items.value` (number)
    Example: 10

  - `items.currency` (string)
    Enum: "CAD", "USD", "EUR", "AUD", "GBP"

  - `items.country_of_origin` (string)
    Required if the shipment is being sent to US
    Example: "CN"

  - `items.hs_code` (string)
    Required if the shipment country_of_origin is CN/HK.
    Example: "123456"

  - `items.manufacturer_name` (string,null)
    The name of the item's manufacturer
    Example: "Acme Clothing Inc."

  - `items.manufacturer_address1` (string,null)
    The address of the item's manufacturer
    Example: "123 Manufacturing Blvd"

  - `items.manufacturer_city` (string,null)
    The city of the item's manufacturer
    Example: "Toronto"

  - `items.manufacturer_province_code` (string,null)
    The province/state code of the item's manufacturer
    Example: "ON"

  - `items.manufacturer_postal_code` (string,null)
    The postal/zip code of the item's manufacturer
    Example: "M5V 2H1"

  - `items.manufacturer_country_code` (string,null)
    The country code of the item's manufacturer
    Example: "CA"

  - `package_type` (any)

  - `signature_confirmation` (boolean,null)
    Default false.

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

  - `label_format` (string)
    Default pdf. Set the format of the returned label.
    Enum: "pdf", "zpl", "png"

  - `is_fba` (boolean,null)
    Default false. Set to true to create a Stallion FBA label.

  - `is_draft` (boolean,null)
    Default false. Set to true to save the shipment without purchasing the label.

  - `insured` (boolean,null)
    Set to true to apply Stallion Protection for tracked shipments only.
    Example: true

  - `region` (string,null)
    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"

  - `tax_identifier` (object)
    Information about tax identification for the shipment.

  - `tax_identifier.tax_type` (string)
    Enum: "IOSS", "EORI", "VAT"

  - `tax_identifier.number` (string)
    Tax identification number.
    Example: "IM1234567890"

  - `tax_identifier.issuing_authority` (string)
    Country code for the authority responsible for issuing the tax identification number.
    Example: "GB"

## Response 200 fields (application/json):

  - `success` (boolean)

  - `label` (string)
    Base 64 encoded label.
    Example: "base64_label"

  - `tracking_code` (string)
    Example: "9400111969000940000011"

  - `message` (string)
    Example: "Shipment successfully completed"

  - `shipment` (object)

  - `shipment.ship_code` (string)
    Example: "2019JHSJDHSJ"

  - `shipment.name` (string)
    Example: "Pramod Thomson"

  - `shipment.address1` (string)
    Example: "30 Clearview Dr"

  - `shipment.address2` (string)
    Example: "Lot 2"

  - `shipment.city` (string)
    Example: "Rock Springs"

  - `shipment.province_code` (string)
    Example: "WY"

  - `shipment.postal_code` (string)
    Example: "82901"

  - `shipment.country_code` (string)
    Example: "US"

  - `shipment.weight_unit` (string)
    Enum: "lbs", "kg", "g", "oz"

  - `shipment.weight` (number)
    Example: 0.6

  - `shipment.length` (number)
    Example: 9

  - `shipment.width` (number)
    Example: 12

  - `shipment.height` (number)
    Example: 1

  - `shipment.size_unit` (string)
    Enum: "cm", "in"

  - `shipment.items` (array)

  - `shipment.items.description` (string)
    Example: "Two pair of socks"

  - `shipment.items.sku` (string,null)
    The SKU/ASIN of the item. Required for FBA shipments.
    Example: "SKU123"

  - `shipment.items.quantity` (integer)
    Example: 2

  - `shipment.items.value` (number)
    Example: 10

  - `shipment.items.currency` (string)
    Enum: "CAD", "USD", "EUR", "AUD", "GBP"

  - `shipment.items.country_of_origin` (string)
    Required if the shipment is being sent to US
    Example: "CN"

  - `shipment.items.hs_code` (string)
    Required if the shipment country_of_origin is CN/HK.
    Example: "123456"

  - `shipment.items.manufacturer_name` (string,null)
    The name of the item's manufacturer
    Example: "Acme Clothing Inc."

  - `shipment.items.manufacturer_address1` (string,null)
    The address of the item's manufacturer
    Example: "123 Manufacturing Blvd"

  - `shipment.items.manufacturer_city` (string,null)
    The city of the item's manufacturer
    Example: "Toronto"

  - `shipment.items.manufacturer_province_code` (string,null)
    The province/state code of the item's manufacturer
    Example: "ON"

  - `shipment.items.manufacturer_postal_code` (string,null)
    The postal/zip code of the item's manufacturer
    Example: "M5V 2H1"

  - `shipment.items.manufacturer_country_code` (string,null)
    The country code of the item's manufacturer
    Example: "CA"

  - `shipment.package_type` (string)
    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", "Regional Rate Box B2", "Letter", "Large Envelope Or Flat", "Thick Envelope"

  - `shipment.postage_type` (string)
    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", "UPS Standard", "PostNL International Packet", "PostNL International Packet Tracked", "APC Priority Worldwide", "APC Priority Worldwide Tracked", "APC Priority Worldwide Expedited", "APC Priority Worldwide Expedited(DDP)", "Stallion Economy USA", "Stallion Economy CA", "US Economy", "Intelcom Standard", "Ecom Next Day", "Canada Post Expedited", "Fleet Optics Express", "ICS Express", "UPS Express Saver"

  - `shipment.region` (string)
    Enum: "Ontario", "British Columbia", "Quebec"

  - `shipment.rate` (integer)
    Example: 9

  - `shipment.tax` (integer)

  - `shipment.total_paid` (integer)

  - `shipment.insured` (boolean)
    Example: true

## Response 401 fields (application/json):

  - `message` (string)
    Example: "Unauthenticated."

## Response 422 fields (application/json):

  - `success` (boolean)

  - `errors` (array)
    Example: ["The data you entered is invalid"]

## Response 500 fields (application/json):

  - `success` (boolean)

  - `errors` (array)
    Example: ["An unknown error occured"]