Shipments API

Manage the shipments for an order. A shipment records which items were
shipped together, along with carrier and tracking details. An order can have
several shipments, which is useful when items ship separately.

A shipment counts as sent once it has a tracking number, and the buyer is
emailed then. When sent shipments hold every item, the order's status becomes
fulfilled. Deleting or reverting a shipment moves the order back to paid.
Stock is taken when the order is paid, so shipments never change inventory.

Endpoints

• List Shipments - GET /api/v1/orders/{order_id}/shipments/
• Create Shipment - POST /api/v1/orders/{order_id}/shipments/
• Get Shipment - GET /api/v1/orders/{order_id}/shipments/{shipment_id}/
• Update Shipment - PUT /api/v1/orders/{order_id}/shipments/{shipment_id}/
• Delete Shipment - DELETE /api/v1/orders/{order_id}/shipments/{shipment_id}/
• Revert Shipment - POST /api/v1/orders/{order_id}/shipments/{shipment_id}/revert/

List Shipments

Retrieve the shipments for an order. This endpoint is not paginated and does
not include line items. Fetch a single shipment to see its items.

Endpoint: GET /api/v1/orders/{order_id}/shipments/

Permission Required: Read

Request

curl -X GET "https://studio.easel.engineering/api/v1/orders/ord_d0b6fmv28q6vn14peun0/shipments/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 200 OK

{
  "data": [
    {
      "id": "shp_d0b6fmv28q6vn14peun0",
      "number": 1,
      "status": "label_created",
      "tracking_number": "1Z999AA10123456784",
      "tracking_url": "https://example.com/track/1Z999AA10123456784",
      "carrier_id": 1,
      "items": [],
      "created_at": "2023-01-02T09:00:00Z",
      "updated_at": "2023-01-02T09:30:00Z"
    }
  ]
}

Create Shipment

Create a shipment for one or more ordered items. Supply the
order_variant_id from the order's items array (see
Orders). Quantities are applied against the
order. The new shipment is unshipped until you add its tracking with
Update Shipment.

Endpoint: POST /api/v1/orders/{order_id}/shipments/

Permission Required: Write

Request Body

{
  "items": [
    {
      "order_variant_id": "orv_d0b6fmv28q6vn14peun0",
      "quantity": 1
    }
  ]
}

Request

curl -X POST "https://studio.easel.engineering/api/v1/orders/ord_d0b6fmv28q6vn14peun0/shipments/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -d '{
    "items": [
      { "order_variant_id": "orv_d0b6fmv28q6vn14peun0", "quantity": 1 }
    ]
  }'

Response

Status: 201 Created

{
  "id": "shp_d0b6fmv28q6vn14peun0"
}

Error Responses

No items supplied

Status: 400 Bad Request

{
  "error": "A shipment requires at least one item",
  "code": "INVALID_FIELD"
}

Negative quantity

Status: 400 Bad Request

{
  "error": "Quantity must be non-negative",
  "code": "INVALID_FIELD"
}

Order not found

Status: 404 Not Found

{
  "error": "Resource not found",
  "code": "NOT_FOUND"
}

Get Shipment

Retrieve a single shipment, including its line items.

Endpoint: GET /api/v1/orders/{order_id}/shipments/{shipment_id}/

Permission Required: Read

Request

curl -X GET "https://studio.easel.engineering/api/v1/orders/ord_d0b6fmv28q6vn14peun0/shipments/shp_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 200 OK

{
  "id": "shp_d0b6fmv28q6vn14peun0",
  "number": 1,
  "status": "label_created",
  "tracking_number": "1Z999AA10123456784",
  "tracking_url": "https://example.com/track/1Z999AA10123456784",
  "carrier_id": 1,
  "items": [
    {
      "order_variant_id": "orv_d0b6fmv28q6vn14peun0",
      "product_id": "pro_d0b6fmv28q6vn14peun0",
      "product_name": "Premium T-Shirt",
      "variant_name": "Small Red",
      "quantity": 1,
      "price": 1999
    }
  ],
  "created_at": "2023-01-02T09:00:00Z",
  "updated_at": "2023-01-02T09:30:00Z"
}

Update Shipment

Update a shipment's carrier, tracking details, or item quantities.

Endpoint: PUT /api/v1/orders/{order_id}/shipments/{shipment_id}/

Permission Required: Write

Request Body

{
  "carrier_id": 1,
  "tracking_number": "1Z999AA10123456784",
  "tracking_url": "https://example.com/track/1Z999AA10123456784",
  "items": [
    {
      "order_variant_id": "orv_d0b6fmv28q6vn14peun0",
      "quantity": 1
    }
  ]
}

carrier_id and the tracking fields are optional. Set tracking_number and
tracking_url directly if you do not have a carrier ID. Adding a tracking
number marks an unshipped shipment as sent and emails the buyer; changing it
later emails them the new one.

Request

curl -X PUT "https://studio.easel.engineering/api/v1/orders/ord_d0b6fmv28q6vn14peun0/shipments/shp_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-67890" \
  -d '{
    "carrier_id": 1,
    "tracking_number": "1Z999AA10123456784"
  }'

Response

Status: 204 No Content

Delete Shipment

Delete a shipment. Its items count as unshipped again.

Endpoint: DELETE /api/v1/orders/{order_id}/shipments/{shipment_id}/

Permission Required: Write

Request

curl -X DELETE "https://studio.easel.engineering/api/v1/orders/ord_d0b6fmv28q6vn14peun0/shipments/shp_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 204 No Content

Revert Shipment

Revert a shipment to unshipped and clear its carrier and tracking. The
shipment keeps its items.

Endpoint: POST /api/v1/orders/{order_id}/shipments/{shipment_id}/revert/

Permission Required: Write

Request

curl -X POST "https://studio.easel.engineering/api/v1/orders/ord_d0b6fmv28q6vn14peun0/shipments/shp_d0b6fmv28q6vn14peun0/revert/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Idempotency-Key: unique-request-id-24680"

Response

Status: 204 No Content

Shipment Object

Fields

Shipment Item Object

Fields

Shipment Status Values

• unshipped - recorded but not yet sent
• prelabel
• on_hold
• label_created
• in_transit
• out_for_delivery
• failed_attempt
• delivered
• available_for_pickup
• exception
• shipped - sent without tracking, such as a letter by regular post, recorded from the dashboard