Shipments

An order can be split into more shipments for one of the following reasons:

  • The order contains line items from more than one stock location.
  • The order contains line items belonging to more than one shipping category.
The combination of stock locations and shipping categories determine the number of shipments. Each shipment gets fulfilled separately.

The shipment object

A shipment object is returned as part of the response body of each successful create, list, retrieve or update API call. The following table contains the list of all its fields along with their type, description and example values.
Object fields:
status
string
The shipment status, one of 'draft', 'upcoming', 'cancelled', 'on_hold', 'picking', 'packing', 'ready_to_ship' or 'shipped'
Example:
draft
currency_code
string
The international 3-letter currency code as defined by the ISO 4217 standard, automatically inherited from the associated order.
Example:
EUR
cost_amount_cents
integer
The cost of this shipment from the selected carrier account, in cents.
Example:
1000
cost_amount_float
float
The cost of this shipment from the selected carrier account, float.
Example:
10.00
formatted_cost_amount
string
The cost of this shipment from the selected carrier account, formatted.
Example:
€10,00
id
integer
Unique identifier for the resource.
Example:
1234
created_at
datetime
Time at which the resource was created.
Example:
2018-01-01T12:00:00.000Z
updated_at
datetime
Time at which the resource was last updated.
Example:
2018-01-01T12:00:00.000Z
reference
string
A string that you can use to add your own identifier to the resource. This can be useful for intergrating the resource to an external system, like an ERP, a marketing tool or a CRM.
Example:
ANYREFEFERNCE
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.
Example:
{"foo":"bar"}
relationship (N:1)
The shipping category of the associated line items (skus).
relationship (N:1)
The stock location from which the shipment is managed.
relationship (N:1)
The customer shipping address.
relationship (N:1)
The shipping method selected by the customer.
relationship (1:N)
The order line items assigned to the shipment.
relationship (1:N)
The available shipping method for the shipment. Useful to present the customer with a list of choices during the checkout.
relationship (1:N)
The parcels associated to the shipment.

Create a shipment

To create a new shipment, send a POST request to the /api/shipments endpoint, passing the resource arguments in the request body. The following table contains the list of all the possible arguments, along with their type, description and examples values. All the arguments marked as required must be present in the request.
Arguments:
reference
optional
A string that you can use to add your own identifier to the resource. This can be useful for intergrating the resource to an external system, like an ERP, a marketing tool or a CRM.
Example:
ANYREFEFERNCE
metadata
optional
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.
Example:
#
Example request:
POST /api/shipments HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
}
Example response: 201 Created
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1234",
    "type": "shipments",
    "links": {
      "self": "https://your-brand.commercelayer.io/api/shipments/1234"
    },
    "attributes": {
      "status": "draft",
      "currency_code": "EUR",
      "cost_amount_cents": "1000",
      "cost_amount_float": "10.00",
      "formatted_cost_amount": "€10,00",
      "id": "1234",
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "metadata": {
        "foo": "bar"
      }
    },
    "relationships": {
      "shipping_category": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/shipping_category",
          "related": "https://your-brand.commercelayer.io/api/shipments/1234/shipping_category"
        }
      },
      "stock_location": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/stock_location",
          "related": "https://your-brand.commercelayer.io/api/shipments/1234/stock_location"
        }
      },
      "shipping_address": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/shipping_address",
          "related": "https://your-brand.commercelayer.io/api/shipments/1234/shipping_address"
        }
      },
      "shipping_method": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/shipping_method",
          "related": "https://your-brand.commercelayer.io/api/shipments/1234/shipping_method"
        }
      },
      "shipment_line_items": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/shipment_line_items",
          "related": "https://your-brand.commercelayer.io/api/shipments/1234/shipment_line_items"
        }
      },
      "available_shipping_methods": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/available_shipping_methods",
          "related": "https://your-brand.commercelayer.io/api/shipments/1234/available_shipping_methods"
        }
      },
      "parcels": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/parcels",
          "related": "https://your-brand.commercelayer.io/api/shipments/1234/parcels"
        }
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

List all shipments

To fetch a collection of shipments, send a GET request to the /api/shipments endpoint.

Example request:
GET /api/shipments HTTP/1.1
Accept: application/vnd.api+json
Example response: 200 OK
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "id": "1234",
      "type": "shipments",
      "links": {
        "self": "https://your-brand.commercelayer.io/api/shipments/1234"
      },
      "attributes": {
        "status": "draft",
        "currency_code": "EUR",
        "cost_amount_cents": "1000",
        "cost_amount_float": "10.00",
        "formatted_cost_amount": "€10,00",
        "id": "1234",
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": "ANYREFEFERNCE",
        "metadata": {
          "foo": "bar"
        }
      },
      "relationships": {
        "shipping_category": {
          "links": {
            "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/shipping_category",
            "related": "https://your-brand.commercelayer.io/api/shipments/1234/shipping_category"
          }
        },
        "stock_location": {
          "links": {
            "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/stock_location",
            "related": "https://your-brand.commercelayer.io/api/shipments/1234/stock_location"
          }
        },
        "shipping_address": {
          "links": {
            "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/shipping_address",
            "related": "https://your-brand.commercelayer.io/api/shipments/1234/shipping_address"
          }
        },
        "shipping_method": {
          "links": {
            "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/shipping_method",
            "related": "https://your-brand.commercelayer.io/api/shipments/1234/shipping_method"
          }
        },
        "shipment_line_items": {
          "links": {
            "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/shipment_line_items",
            "related": "https://your-brand.commercelayer.io/api/shipments/1234/shipment_line_items"
          }
        },
        "available_shipping_methods": {
          "links": {
            "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/available_shipping_methods",
            "related": "https://your-brand.commercelayer.io/api/shipments/1234/available_shipping_methods"
          }
        },
        "parcels": {
          "links": {
            "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/parcels",
            "related": "https://your-brand.commercelayer.io/api/shipments/1234/parcels"
          }
        }
      },
      "meta": {
        "mode": "test"
      }
    },
    {
      "other": "... 24 shipments (first page)"
    }
  ],
  "meta": {
    "record_count": 125,
    "page_count": 5
  },
  "links": {
    "first": "/api/shipments?page[number]=1&page[size]=25",
    "prev": "/api/shipments?page[number]=2&page[size]=25",
    "next": "/api/shipments?page[number]=4&page[size]=25",
    "last": "/api/shipments?page[number]=5&page[size]=25"
  }
}
Available filters
idstatusreferencestock_location_ididscreated_at_fromcreated_at_toupdated_at_fromupdated_at_to
Sortable attributes
statusidcreated_atupdated_atreference

Retrieve a shipment

To fetch a single shipment, send a GET request to the /api/shipments/{{id}} endpoint, where {{id}} is the id of the resource that you want to retrieve.
Example request:
GET /api/shipments/1234 HTTP/1.1
Accept: application/vnd.api+json
Example response: 200 OK
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1234",
    "type": "shipments",
    "links": {
      "self": "https://your-brand.commercelayer.io/api/shipments/1234"
    },
    "attributes": {
      "status": "draft",
      "currency_code": "EUR",
      "cost_amount_cents": "1000",
      "cost_amount_float": "10.00",
      "formatted_cost_amount": "€10,00",
      "id": "1234",
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "metadata": {
        "foo": "bar"
      }
    },
    "relationships": {
      "shipping_category": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/shipping_category",
          "related": "https://your-brand.commercelayer.io/api/shipments/1234/shipping_category"
        }
      },
      "stock_location": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/stock_location",
          "related": "https://your-brand.commercelayer.io/api/shipments/1234/stock_location"
        }
      },
      "shipping_address": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/shipping_address",
          "related": "https://your-brand.commercelayer.io/api/shipments/1234/shipping_address"
        }
      },
      "shipping_method": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/shipping_method",
          "related": "https://your-brand.commercelayer.io/api/shipments/1234/shipping_method"
        }
      },
      "shipment_line_items": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/shipment_line_items",
          "related": "https://your-brand.commercelayer.io/api/shipments/1234/shipment_line_items"
        }
      },
      "available_shipping_methods": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/available_shipping_methods",
          "related": "https://your-brand.commercelayer.io/api/shipments/1234/available_shipping_methods"
        }
      },
      "parcels": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/parcels",
          "related": "https://your-brand.commercelayer.io/api/shipments/1234/parcels"
        }
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

Update a shipment

To update an existing shipment, send a PATCH request to the /api/shipments/{{id}} endpoint, where {{id}} is the id of the resource that you want to update. The following table contains the list of all the possible arguments that you can pass with the request body, along with their type, description and examples values. Please note that all arguments are optional.
Arguments:
_on_hold
optional
Send this attribute if you want to put this shipment on hold.
Example:
_picking
optional
Send this attribute if you want to start picking this shipment.
Example:
_packing
optional
Send this attribute if you want to start packing this shipment.
Example:
_ready_to_ship
optional
Send this attribute if you want to mark this shipment as ready to ship.
Example:
_ship
optional
Send this attribute if you want to mark this shipment as shipped.
Example:
_get_rates
optional
Send this attribute if you want get the shipping rates from the associated carrier accounts.
Example:
selected_rate_id
optional
The selected purchase rate from the available shipping rates.
Example:
rate_f89e4663c3ed47ee94d37763f6d21d54
_purchase
optional
Send this attribute if you want to purchase this shipment with the selected rate.
Example:
reference
optional
A string that you can use to add your own identifier to the resource. This can be useful for intergrating the resource to an external system, like an ERP, a marketing tool or a CRM.
Example:
ANYREFEFERNCE
metadata
optional
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.
Example:
#
optional
The shipping method selected by the customer.
Example request:
PATCH /api/shipments/1234 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "shipments",
    "id": 1234,
    "attributes": {
      "_on_hold": null
    },
    "relationships": {
    }
  }
}
Example response: 200 OK
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1234",
    "type": "shipments",
    "links": {
      "self": "https://your-brand.commercelayer.io/api/shipments/1234"
    },
    "attributes": {
      "status": "draft",
      "currency_code": "EUR",
      "cost_amount_cents": "1000",
      "cost_amount_float": "10.00",
      "formatted_cost_amount": "€10,00",
      "id": "1234",
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "metadata": {
        "foo": "bar"
      }
    },
    "relationships": {
      "shipping_category": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/shipping_category",
          "related": "https://your-brand.commercelayer.io/api/shipments/1234/shipping_category"
        }
      },
      "stock_location": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/stock_location",
          "related": "https://your-brand.commercelayer.io/api/shipments/1234/stock_location"
        }
      },
      "shipping_address": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/shipping_address",
          "related": "https://your-brand.commercelayer.io/api/shipments/1234/shipping_address"
        }
      },
      "shipping_method": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/shipping_method",
          "related": "https://your-brand.commercelayer.io/api/shipments/1234/shipping_method"
        }
      },
      "shipment_line_items": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/shipment_line_items",
          "related": "https://your-brand.commercelayer.io/api/shipments/1234/shipment_line_items"
        }
      },
      "available_shipping_methods": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/available_shipping_methods",
          "related": "https://your-brand.commercelayer.io/api/shipments/1234/available_shipping_methods"
        }
      },
      "parcels": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/shipments/1234/relationships/parcels",
          "related": "https://your-brand.commercelayer.io/api/shipments/1234/parcels"
        }
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

Delete a shipment

To delete a shipment, send a DELETE request to the /api/shipments/{{id}} endpoint, where {{id}} is the id of the resource that you want to delete.
Example request:
DELETE /api/shipments/1234 HTTP/1.1
Accept: application/vnd.api+json
Example response: 204 No Content
HTTP/1.1 204 No Content

Get our machine-readable JSON schema that follows the OpenAPI Specification (formerly Swagger).

Get our Postman collection in one click and start making real calls to Commerce Layer API in minutes.

Get in touch with our support team if you have any questions or want to learn more about Commerce Layer.