Shipments

Managing Order Shipments

The Shipments API allows you to manage shipments for orders in your store. You can create new shipments, update existing ones, and track shipment status.

GET /api/shipments/

Retrieve a list of all shipments. This endpoint supports pagination and filtering to help you find specific shipments.

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number (default: 1)
`items_per_page`	integer	No	Number of items per page (default: 10)
`order_id`	integer	No	Filter shipments by order ID
`status`	string	No	Filter shipments by status

Example Response

{
  "shipments": [
    {
      "shipment_id": "12",
      "order_id": "145",
      "shipping_method": "Standard Shipping",
      "tracking_number": "1Z999AA10123456784",
      "status": "S",
      "timestamp": "1649851200"
    },
    {
      "shipment_id": "13",
      "order_id": "146",
      "shipping_method": "Express Shipping",
      "tracking_number": "1Z999AA10123456785",
      "status": "P",
      "timestamp": "1649937600"
    }
  ],
  "params": {
    "page": 1,
    "items_per_page": 10,
    "total_items": 2
  }
}

GET /api/shipments/{shipment_id}/

Retrieve details for a specific shipment by its ID.

Example Response

{
  "shipment_id": "12",
  "order_id": "145",
  "shipping_method": "Standard Shipping",
  "tracking_number": "1Z999AA10123456784",
  "carrier": "UPS",
  "status": "S",
  "timestamp": "1649851200",
  "items": [
    {
      "item_id": "458",
      "product_id": "123",
      "product_name": "Premium Widget",
      "amount": "2"
    },
    {
      "item_id": "459",
      "product_id": "124",
      "product_name": "Widget Accessories",
      "amount": "1"
    }
  ],
  "comments": "Handle with care"
}

POST /api/shipments/

Create a new shipment for an order.

Request Parameters

Parameter	Type	Required	Description
`order_id`	string	Yes	ID of the order to create a shipment for
`shipping_method`	string	Yes	Shipping method to use
`tracking_number`	string	No	Tracking number for the shipment
`carrier`	string	No	Shipping carrier
`items`	array	Yes	Array of order items to include in this shipment
`comments`	string	No	Comments about the shipment

Example Request

{
  "order_id": "145",
  "shipping_method": "Standard Shipping",
  "tracking_number": "1Z999AA10123456784",
  "carrier": "UPS",
  "items": [
    {
      "item_id": "458",
      "amount": "2"
    },
    {
      "item_id": "459",
      "amount": "1"
    }
  ],
  "comments": "Handle with care"
}

Tip: You can create partial shipments by specifying only some of the order items, or by specifying quantities less than the total ordered amount.

PUT /api/shipments/{shipment_id}/

Update an existing shipment.

Example Request

{
  "tracking_number": "1Z999AA10123456789",
  "status": "D",
  "comments": "Delivered to front door"
}

Shipment Status Codes

Code	Description
`P`	Processing
`S`	Shipped
`D`	Delivered
`F`	Failed/Returned