The shipment object

A comprehensive list of the shipment resource's attributes and relationships

A shipment object is returned as part of the response body of each successful list, retrieve, create or update API call to the /api/shipments endpoint.

Fields

FieldTypeDescription

type

string

shipments

id

string

The shipment unique identifier

links.self

string

The shipment endpoint URL

attributes.number

string

Unique identifier for the shipment. Cannot be passed by sales channels.

attributes.status

string

The shipment status. One of 'draft' (default), 'upcoming', 'cancelled', 'on_hold', 'picking', 'packing', 'ready_to_ship', 'shipped', or 'delivered'.

attributes.currency_code

string

The international 3-letter currency code as defined by the ISO 4217 standard, automatically inherited from the associated order.

attributes.cost_amount_cents

integer

The cost of this shipment from the selected carrier account, in cents.

attributes.cost_amount_float

float

The cost of this shipment from the selected carrier account, float.

attributes.formatted_cost_amount

string

The cost of this shipment from the selected carrier account, formatted.

attributes.skus_count

integer

The total number of SKUs in the shipment's line items. This can be useful to display a preview of the shipment content.

attributes._upcoming

boolean

Send this attribute if you want to mark this shipment as upcoming. Cannot be passed by sales channels.

attributes._cancel

boolean

Send this attribute if you want to mark this shipment as cancelled (unless already shipped or delivered). Cannot be passed by sales channels.

attributes._on_hold

boolean

Send this attribute if you want to put this shipment on hold.

attributes._picking

boolean

Send this attribute if you want to start picking this shipment.

attributes._packing

boolean

Send this attribute if you want to start packing this shipment.

attributes._ready_to_ship

boolean

Send this attribute if you want to mark this shipment as ready to ship.

attributes._ship

boolean

Send this attribute if you want to mark this shipment as shipped.

attributes._deliver

boolean

Send this attribute if you want to mark this shipment as delivered.

attributes._reserve_stock

boolean

Send this attribute if you want to automatically reserve the stock for each of the associated stock line item. Can be done only when fulfillment is in progress. Cannot be passed by sales channels.

attributes._release_stock

boolean

Send this attribute if you want to automatically destroy the stock reservations for each of the associated stock line item. Can be done only when fulfillment is in progress. Cannot be passed by sales channels.

attributes._decrement_stock

boolean

Send this attribute if you want to automatically decrement and release the stock for each of the associated stock line item. Can be done only when fulfillment is in progress. Cannot be passed by sales channels.

attributes._get_rates

boolean

Send this attribute if you want get the shipping rates from the associated carrier accounts.

attributes.selected_rate_id

string

The selected purchase rate from the available shipping rates.

attributes.rates

array

The available shipping rates.

attributes._purchase

boolean

Send this attribute if you want to purchase this shipment with the selected rate.

attributes.purchase_error_code

string

The shipping rate purchase error code, if any.

attributes.purchase_error_message

string

The shipping rate purchase error message, if any.

attributes.get_rates_errors

array

Any errors collected when fetching shipping rates.

attributes.get_rates_started_at

datetime

Time at which the getting of the shipping rates started.

attributes.get_rates_completed_at

datetime

Time at which the getting of the shipping rates completed.

attributes.purchase_started_at

datetime

Time at which the purchasing of the shipping rate started.

attributes.purchase_completed_at

datetime

Time at which the purchasing of the shipping rate completed.

attributes.purchase_failed_at

datetime

Time at which the purchasing of the shipping rate failed.

attributes.on_hold_at

datetime

Time at which the shipment was put on hold.

attributes.picking_at

datetime

Time at which the shipment was picking.

attributes.packing_at

datetime

Time at which the shipment was packing.

attributes.ready_to_ship_at

datetime

Time at which the shipment was ready to ship.

attributes.shipped_at

datetime

Time at which the shipment was shipped.

attributes.created_at

datetime

Time at which the resource was created.

attributes.updated_at

datetime

Time at which the resource was last updated.

attributes.reference

string

A string that you can use to add any external identifier to the resource. This can be useful for integrating the resource to an external system, like an ERP, a marketing tool, a CRM, or whatever.

attributes.reference_origin

string

Any identifier of the third party system that defines the reference code.

attributes.metadata

object

Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.

relationships.order

object

The associated order.

relationships.shipping_category

object

The shipping category of the associated line items (SKUs). Can be updated only when fulfillment is in progress.

relationships.inventory_stock_location

object

The inventory stock location from which the shipment is managed. Can be updated only when fulfillment is in progress.

relationships.stock_location

object

The stock location associated to the inventory.

relationships.origin_address

object

The associated stock location address.

relationships.shipping_address

object

The customer shipping address. Can be updated only when fulfillment is in progress.

relationships.shipping_method

object

The shipping method selected by the customer.

relationships.delivery_lead_time

object

The delivery lead time for the shipment. Equals the one associated with the shipping method selected by the customer.

relationships.stock_line_items

array

The associated stock line items.

relationships.stock_transfers

array

The associated stock transfers.

relationships.line_items

array

The line items included in the shipment.

relationships.available_shipping_methods

array

The available shipping methods for the shipment. Useful to present the customer with a list of choices during the checkout. Only enabled shipping methods are included in the list.

relationships.carrier_accounts

array

The carrier accounts available for the order's market.

relationships.parcels

array

The associated parcels.

relationships.attachments

array

The associated attachments.

relationships.events

array

The associated events.

relationships.tags

array

The associated tags.

relationships.versions

array

The associated changes.

meta.mode

string

The resource environment (can be one of test or live)

Last updated