Filter
What would you like to search for?
Backend API
A shipment represents physical fulfillment of a number of items after an order is placed. Shipments contain information about items being fulfilled, and shipping details such as address and tracking number.
Fields
Unique identifier for the shipment.
List of line items describing the products shipped.
Unique identifier for the shipment item.
ID of the order item shipped.
ID of the item product.
ID of the order bundle item shipped, if applicable.
Options from the order item shipped, if applicable.
Unique identifier for the object.
Name of the product option.
Name value of the product option.
Expandable link to the item product.
Quantity of the item shipped. Defaults to 1.
ID of the item variant, if applicable.
Expandable link to the item variant, if applicable.
The id of the order this shipment was created for.
Indicates the shipment was canceled.
The id of a third-party carrier offering the service, if applicable.
Name of a third-party carrier offering the service, if applicable.
Date and time the shipment was created.
Date the expected shipment is meant to arrive at the destination, if applicable.
Date and time the shipment was last updated.
The customer's shipping address.
Destination customer name.
Destination address line 1: street address/PO box/company name.
Destination address line 2: apartment/suite/unit/building.
Two-letter ISO code country code.
Destination city/district/suburb/town/village.
Destination state/county/province/region.
Destination zip/postal code.
Destination phone number.
Internal admin notes, not visible to the customer.
Expandable list of notifications sent on behalf of the shipment.
Unique incremental shipment number, assigned automatically.
Expandable link to the order.
The shipment origin location.
ID of the origin location, if applicable.
List of packages included in this shipment.
Height of the package in centimeters or inches.
Length of the package in centimeters or inches.
Type of package. This value can be enumerated, representing the types of packages used by the fulfillment provider.
Weight of the package in the unit of the store's default (lb, oz, lb).
Width of the package in centimeters or inches.
The id of a shipping service as configured in shipment settings.
Name of the shipping service.
Tracking code used to identify the shipment, if applicable.
The order’s shipping label.
Date and time the label was created.
When set to true, a shipment label will be purchased on-demand from the carrier. The carrier is set in label purchase settings.
An image of the shipment label, if present.
Unique identifier for the image.
Date the image was uploaded.
Size of the image in bytes.
An MD5 hash of the image contents. This can be used to identify the image for caching purposes.
Optional image name.
MIME content type of the image.
Arbitrary image data, typically used to store custom values. See Frontend API for more details.
A reference to the raw image data.
Indicates the image is not visible to customers.
A public URL to reference the image. Updated automatically if image content changes.
Image width in pixels, if applicable.
Image height in pixels, if applicable.
The shipment model
{
"id": "60f199509111e70000000089",
"items": [
{
"id": "5ca537326a0ec32a521139dd",
"order_item_id": null,
"product_id": "5cad15bc9b14d1990724663b",
"quantity": 2
}
],
"order_id": "60f199509111e7000000008b",
"date_created": "2021-07-16T14:36:00.413Z",
"date_updated": "2021-07-16T14:36:00.413Z",
"destination": {
"name": "Hieronymus Lex",
"address1": "South Watch Tower, Captain's Quarters",
"city": "Imperial City",
"state": "NY",
"zip": 11201,
"country": "US",
"phone": "(555) 555-5555"
},
"service": "imperial_express",
"tracking_code": "T192000000XYZ"
}Create a new shipment.
Arguments
List of line items describing the products shipped.
ID of the order item shipped.
ID of the item product.
Expandable link to the product item.
ID of the order bundle item shipped, if applicable.
Options from the order item shipped, if applicable.
Unique identifier for the object.
Name of the product option.
Name value of the product option.
Quantity of the item shipped. Defaults to 1.
ID of the item variant, if applicable.
Expandable link to the item variant, if applicable.
ID of the order this shipment was created for.
Tracking code used to identify the shipment, if applicable.
Expandable link to the order.
Indicates the shipment was canceled.
ID of a 3rd party carrier offering the service, if applicable.
Name of a 3rd party carrier offering the service, if applicable.
Date the expected shipment is meant to arrive at the destination, if applicable.
The customer's shipping address.
Destination customer name.
Destination address line 1: street address/PO box/company name.
Destination address line 2: apartment/suite/unit/building.
Destination city/district/suburb/town/village.
Two-letter ISO code country code.
Destination phone number.
Destination state/county/province/region.
Destination zip/postal code.
Internal admin notes, not visible to the customer.
The shipment origin location.
ID of the origin location, if applicable.
List of packages included in this shipment.
Height of the package in centimeters or inches.
Length of the package in centimeters or inches.
Type of package. This value can be enumerated, representing the types of packages used by the fulfillment provider.
Weight of the package in the unit of the store's default (lb, oz, lb).
Width of the package in centimeters or inches.
ID of a shipping service as configured in shipment settings.
Name of the shipping service.
const swell = require('swell-node').init('store-id', 'secret-key');
await swell.post('/shipments', {
order_id: '5a9ea7ba3f95740a914267f1',
items: [
{
order_item_id: '5a9ea7ba3f95740a914267f2',
product_id: '5cad15bc9b14d1990724663a',
quantity: 2,
}
],
tracking_code: 'T192000000XYZ',
});
Response
{
"id": "5cad15bc9b14d1990724663a",
"number": "S10001",
"order_id": "5a9ea7ba3f95740a914267f1",
"items": [
{
"id": "5a9ea7ba3f95740a914267f2",
"order_item_id": "5a9ea7ba3f95740a914267f2",
"product_id": "5cad15bc9b14d1990724663b",
"quantity": 2,
...
}
],
"tracking_code": "T192000000XYZ",
...
}Update an existing shipment using the ID that was obtained when it was created.
Arguments
Unique identifier for the shipment.
List of line items describing the products shipped.
ID of the order item shipped.
ID of the item product.
Expandable link to the product item.
ID of the order bundle item shipped, if applicable.
Options from the order item shipped, if applicable.
Unique identifier for the object.
Name of the product option.
Name value of the product option.
Quantity of the item shipped. Defaults to 1.
ID of the item variant, if applicable.
Expandable link to the item variant, if applicable.
ID of the order this shipment was created for.
Tracking code used to identify the shipment, if applicable.
Expandable link to the order.
Indicates the shipment was canceled.
ID of a 3rd party carrier offering the service, if applicable.
Name of a 3rd party carrier offering the service, if applicable.
Date the expected shipment is meant to arrive at the destination, if applicable.
The customer's shipping address.
Destination customer name.
Destination address line 1: street address/PO box/company name.
Destination address line 2: apartment/suite/unit/building.
Destination city/district/suburb/town/village.
Two-letter ISO code country code.
Destination phone number.
Destination state/county/province/region.
Destination zip/postal code.
Internal admin notes, not visible to the customer.
The shipment origin location.
ID of the origin location, if applicable.
List of packages included in this shipment.
Height of the package in centimeters or inches.
Length of the package in centimeters or inches.
Type of package. This value can be enumerated, representing the types of packages used by the fulfillment provider.
Weight of the package in the unit of the store's default (lb, oz, lb).
Width of the package in centimeters or inches.
ID of a shipping service as configured in shipment settings.
Name of the shipping service.
const swell = require('swell-node').init('store-id', 'secret-key');
await swell.put('/shipments/{id}', {
id: '60f199509111e70000000089',
tracking_code: 'T192000000XYZ'
});
Response
{
"id": "60f199509111e70000000089",
"items": [
{
"id": "5ca537326a0ec32a521139dd",
"order_item_id": null,
"product_id": "5cad15bc9b14d1990724663b",
"quantity": 2
}
],
"order_id": "60f199509111e7000000008e",
"date_created": "2021-07-16T14:36:00.413Z",
"date_updated": "2021-07-16T14:36:00.413Z",
"destination": {
"name": "Jon Snow",
"address1": "1 Main Street",
"city": "Brooklyn",
"state": "NY",
"zip": 11201,
"country": "US",
"phone": "(555) 555-5555"
},
"service": "fedex_ground",
"tracking_code": "T192000000XYZ"
}Arguments
The id of the shipment to retrieve.
Expanding link fields and child collections is performed using the expand argument.
- For example, expand=account would return a related customer account if one exists.
When the field represents a collection, you can specify the query limit.
- For example, expand=variants:10 would return up to 10 records of the variants collection.
See expanding for more details.
Return only the specified fields in the result. For example fields=name,slug would return only the fields name and slug in the response. Supports nested object and array fields using dot-notation, for example, items.product_id. The category id is always returned.
Include one or more arbitrary queries in the response, possibly related to the main query.
See including for more details.
const swell = require('swell-node').init('store-id', 'secret-key');
await swell.get('/shipments/{id}', {
id: '60f199509111e70000000090'
});
Response
{
"id": "60f199509111e70000000094",
"items": [
{
"id": "5ca537326a0ec32a521139dd",
"order_item_id": null,
"product_id": "5cad15bc9b14d1990724663b",
"quantity": 2
}
],
"order_id": "60f199509111e70000000095",
"date_created": "2021-07-16T14:36:00.413Z",
"date_updated": "2021-07-16T14:36:00.413Z",
"destination": {
"name": "Jon Snow",
"address1": "1 Main Street",
"city": "Brooklyn",
"state": "NY",
"zip": 11201,
"country": "US",
"phone": "(555) 555-5555"
},
"service": "fedex_ground",
"tracking_code": "T192000000XYZ"
}Return a list of shipments.
Arguments
Expand link fields and child collections by using the expand argument.
- For example, expand=account would return a related customer account if one exists.
When the field represents a collection, you can specify the query limit.
- For example, expand=variants:10 would return up to 10 records of the variants collection.
See expanding for more details.
Returns only the specified fields in the result.
- For example fields=name,slug would return only the fields name and slug in the response.
Supports nested object and array fields using dot-notation.
- For example, items.product_id. The product id is always returned.
Include one or more arbitrary queries in the response which are potentially related to the main query.
See including for more details.
Limit the number of records returned, ranging between 1 and 1000. Defaults to 15.
The page number of results to return given the specified or default limit.
A text search is performed using the search argument. Searchable fields are defined by the model.
- For example, search=red would return records containing the word "red" anywhere in the defined text fields.
See searching for more details.
Expression to sort results by using a format similar to a SQL sort statement.
- For example, sort=name asc would return records sorted by name ascending.
See sorting for more details.
An object with criteria to filter the result.
- For example, active=true would return records containing a field active with the value true.
It's also possible to use query operators, for example, $eq, $ne, $gt, and more.
See querying for more details.
const swell = require('swell-node').init('store-id', 'secret-key');
await swell.get('/shipments', {
limit: 25,
page: 1
});
Response
{
"count": 51,
"results": [
{
"id": "60f199509111e70000000089",
"items": [
{
"id": "5ca537326a0ec32a521139dd",
"order_item_id": null,
"product_id": "5cad15bc9b14d1990724663b",
"quantity": 2
}
],
"order_id": "60f199509111e70000000099",
"date_created": "2021-07-16T14:36:00.413Z",
"date_updated": "2021-07-16T14:36:00.413Z",
"destination": {
"name": "Jon Snow",
"address1": "1 Main Street",
"city": "Brooklyn",
"state": "NY",
"zip": 11201,
"country": "US",
"phone": "(555) 555-5555"
},
"service": "fedex_ground",
"tracking_code": "T192000000XYZ"
},
{...},
{...}
],
"page": 1,
"pages": {
"1": {
"start": 1,
"end": 25
},
"2": {
"start": 26,
"end": 50
},
"2": {
"start": 51,
"end": 51
}
}
}