Fulfillment Endpoints

This document covers the fulfillment endpoints: creating a shipment against a confirmed order, adding tracking, and reading delivery state. Fulfillment obligations for sellers are stated in the Fulfillment by Pawz Shop: Program Terms (Fulfillment by Pawz Shop — Program Terms) and the Fulfillment Policy; this document states the endpoint mechanics.

Access through the developer API is issued by the Company and is limited by seller type: manufacturer and supplier accounts receive API access for importing data, under the Developer Agreement and the API Access Tiers. Nothing in this document grants broader access.

Endpoints

Method	Path	Purpose
GET	`/fulfillments`	List your shipments, newest first, paginated
GET	`/fulfillments/{id}`	Read one shipment, with its tracking history
POST	`/orders/{order_id}/fulfillments`	Create a shipment for an order, in whole or by line
PATCH	`/fulfillments/{id}`	Add or correct carrier and tracking details
POST	`/fulfillments/{id}/cancel`	Cancel a shipment that has not been handed to the carrier

All paths are relative to the base URL https://www.aapawz.com/api. Collections paginate as specified in Pagination and Filtering (Pagination & Filtering). Every create accepts an Idempotency-Key header (Idempotency Keys) and shall carry one: a retried create must never produce two shipments for the same lines.

The shipment object

{
  "id": "shp_28dm41",
  "order_id": "ord_64kx20",
  "order_number": "AAP-2026-104821",
  "status": "in_transit",
  "carrier": "UPS",
  "service": "Ground",
  "tracking_number": "1Z8842W90311884510",
  "tracking_url": "https://www.aapawz.com/orders/AAP-2026-104821/tracking",
  "lines": [
    { "order_line_id": "line_01", "quantity": 2 }
  ],
  "shipped_at": "2026-10-14T15:02:37Z",
  "estimated_delivery_at": "2026-10-19T23:59:59Z",
  "delivered_at": null,
  "created_at": "2026-10-14T15:02:37Z",
  "updated_at": "2026-10-15T06:12:09Z"
}

Status values are label_created, in_transit, out_for_delivery, delivered, exception, cancelled; definitions are in Data Types and Enums.

Creating a shipment

Ship only an order in confirmed status (Orders Endpoints). A shipment covers named order lines and quantities; a partial shipment is permitted, and the remaining quantities stay open for a later shipment.

POST /orders/ord_64kx20/fulfillments
Authorization: Bearer <your-api-key>
Idempotency-Key: ship-ord_64kx20-1
Content-Type: application/json

{
  "carrier": "UPS",
  "service": "Ground",
  "tracking_number": "1Z8842W90311884510",
  "lines": [
    { "order_line_id": "line_01", "quantity": 2 }
  ]
}

Rules

carrier and tracking_number are required. The Platform validates the tracking number's format for the named carrier; a number that cannot be tracked is rejected with 422 and code invalid_tracking_number.
The total shipped quantity per line, across all shipments, may not exceed the ordered quantity; excess quantities fail with 422 and code quantity_exceeds_order.
Creating a shipment draws down reserved stock (Inventory Endpoints) and moves the order to fulfilling, or to shipped when every line is fully shipped.
The buyer is notified with the carrier and tracking details when the shipment is created. Send tracking promptly and accurately: a shipment created with placeholder tracking is a policy violation, not a timing technique.
One shipment, one package. For multi-package shipments, create one shipment per package, each with its own tracking number.

A successful create returns 201 and the shipment object.

Correcting and cancelling

PATCH /fulfillments/{id} corrects carrier, service, or tracking_number: for example, when a label is reprinted. Corrections are accepted until the shipment is delivered. POST /fulfillments/{id}/cancel cancels a shipment still in label_created status and returns its lines to open quantities; a shipment already in_transit cannot be cancelled through the API: handle it with the carrier, and use the returns flow (Returns Endpoints) if the goods come back.

Tracking and delivery state

GET /fulfillments/{id} returns the shipment with a tracking_events array: carrier scans in time order, each with status, location, and occurred_at. Delivery state also arrives as events: subscribe to shipment.in_transit, shipment.out_for_delivery, shipment.delivered, and shipment.exception (Webhook Event Schemas) instead of polling. Payment for the order settles independently of delivery state, as described in Payments Endpoints.

Errors

Status	Code	Cause
404	`not_found`	No order or shipment with that identifier exists in your account
409	`invalid_state`	The order is not `confirmed`, or the shipment can no longer change
422	`invalid_tracking_number`	The tracking number does not match the carrier's format
422	`quantity_exceeds_order`	Shipped quantities would exceed the order
422	`validation_failed`	A required field is missing or malformed

Error bodies follow Error Codes.

Orders Endpoints

Returns Endpoints