Orders Endpoints

This document covers the orders endpoints: listing and reading the orders placed with your account, acknowledging an order, and recording a cancellation. Orders are created by buyers at checkout; the API does not create marketplace orders. What your account receives through these endpoints is its own orders, line by line, with the amounts the buyer paid and the delivery details you fulfill against.

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	`/orders`	List your orders, newest first, paginated
GET	`/orders/{id}`	Read one order in full
POST	`/orders/{id}/acknowledge`	Mark an order as seen and accepted for fulfillment
POST	`/orders/{id}/cancel`	Cancel an unshipped order, in whole or by line

All paths are relative to the base URL https://www.aapawz.com/api. Collections paginate and filter as specified in Pagination and Filtering (Pagination & Filtering); filter by status, and by placed_at range, to poll for new work. Writes accept an Idempotency-Key header (Idempotency Keys).

The order object

{
  "id": "ord_64kx20",
  "order_number": "AAP-2026-104821",
  "status": "confirmed",
  "placed_at": "2026-10-13T19:22:08Z",
  "buyer": {
    "name": "Jordan Ellis"
  },
  "shipping_address": {
    "name": "Jordan Ellis",
    "line1": "418 Poplar Avenue",
    "line2": null,
    "city": "Memphis",
    "region": "TN",
    "postal_code": "38105",
    "country": "US"
  },
  "lines": [
    {
      "id": "line_01",
      "product_id": "prod_8f3ka9",
      "variant_id": "var_51hd02",
      "seller_sku": "ACME-DOGFOOD-10LB",
      "title": "Acme Grain-Free Dog Food, 10 lb",
      "quantity": 2,
      "unit_price": "24.99",
      "line_total": "49.98"
    }
  ],
  "subtotal": "49.98",
  "shipping_charge": "4.99",
  "tax": "5.07",
  "total": "60.04",
  "currency": "USD",
  "acknowledged_at": null
}

Amounts are decimal strings with a currency field, as stated in Overview; field and status definitions are in Data Types and Enums. Use the buyer's name and shipping address only to fulfill the order. Order data is personal data: store the minimum you need, for no longer than fulfillment, tax, and returns require.

Order status

Status	Meaning
`pending_payment`	Placed; payment not yet confirmed. Do not ship.
`confirmed`	Paid and ready to fulfill.
`fulfilling`	A shipment has been created (Fulfillment Endpoints).
`shipped`	Every line is in transit or delivered.
`completed`	Delivered, and the returns window is running or closed.
`cancelled`	Cancelled before shipment; payment refunded or voided.
`returned`	Every line was returned (Returns Endpoints).

Status moves forward only. An order in pending_payment becomes confirmed when payment clears (Payments Endpoints); never treat a pending_payment order as a sale.

Acknowledging and cancelling

Acknowledge a confirmed order once your systems have accepted it

POST /orders/ord_64kx20/acknowledge
Authorization: Bearer <your-api-key>
Idempotency-Key: ack-ord_64kx20

The response is 200 with the order object and acknowledged_at set. Acknowledgement does not reserve stock: stock was reserved at placement (Inventory Endpoints): and it does not start fulfillment; create the shipment under Fulfillment Endpoints.

Cancel only an order that has not shipped, and state a reason

{
  "reason": "out_of_stock",
  "note": "Supplier delivery delayed beyond the promised ship date."
}

reason is one of out_of_stock, cannot_fulfill, buyer_requested, duplicate. A cancellation releases reserved stock, refunds the buyer in full for the cancelled lines, and returns 200 with the updated order. Cancelling a shipped order fails with 409 and code already_shipped; use the returns flow instead.

Prices on an order line are the prices in force at placement (Pricing Endpoints); later price changes never alter an existing order.

Events

Do not poll aggressively for new orders. Subscribe to the order.created and order.cancelled events and reconcile with a periodic list call (Webhook Event Schemas). Rate limits are in Rate Limit Headers and error bodies in Error Codes.

Status	Code	Cause
404	`not_found`	No order with that `id` exists in your account
409	`already_shipped`	The order has shipped and cannot be cancelled
409	`invalid_state`	The action is not available in the order's current status
422	`validation_failed`	Missing or disallowed `reason` on a cancellation

Inventory Endpoints

Fulfillment Endpoints