Orders

List, read and create ZingaShop orders. Creating orders through the API is how
you bring in sales from external channels or point-of-sale systems.

Requires data:read to read and data:write:orders (or data:write:*) to
create.

List orders

GET /papi/v1/orders

Query parameters: limit, offset. Returns a
paginated list of order summaries.

Get an order

GET /papi/v1/orders/{id}

Returns the order with its line items:

{
  "id": "…",
  "number": "1042",
  "status": "confirmed",
  "paymentStatus": "paid",
  "fulfillmentStatus": "unfulfilled",
  "currency": "USD",
  "subtotalCents": 3998,
  "grandTotalCents": 3998,
  "placedAt": "2026-07-11T09:30:00Z",
  "customerId": "…",
  "websiteId": "…",
  "items": [
    {
      "id": "…",
      "variantId": "…",
      "name": "Premium Car Wax",
      "sku": "WAX-PREM-500",
      "quantity": 2,
      "unitPriceCents": 1999,
      "lineSubtotalCents": 3998
    }
  ]
}

Field	Values
`status`	`pending`, `confirmed`, `cancelled`
`paymentStatus`	`unpaid`, `paid`, `partial`, `failed`, `refunded`

Create an order

POST /papi/v1/orders          → 201 Created

Field	Required	Notes
`websiteId`	yes	The storefront the order belongs to
`currency`	yes	ISO currency code
`customer`	yes	`{ email, phone, firstName, lastName }` — matched to or created as a customer
`items`	yes	Line items (see below)
`billingAddress`	no	`{ line1, city, countryCode, … }`
`shippingAddress`	no	Same shape as `billingAddress`
`status`	no	Initial order status
`paymentStatus`	no	Initial payment status
`externalId`	no	Your own reference, for idempotency and reconciliation
`notes`	no	Free-text notes

Each line item identifies the product by variantId, productId, or sku,
with a quantity and an optional unitPriceCents (falls back to the catalog
price when omitted).

curl -X POST https://api-v1.zingasuite.com/papi/v1/orders \
  -H "Authorization: Bearer zk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "websiteId": "<website-id>",
    "currency": "USD",
    "customer": { "email": "[email protected]", "firstName": "Sam", "lastName": "Lee" },
    "items": [ { "sku": "WAX-PREM-500", "quantity": 2, "unitPriceCents": 1999 } ],
    "status": "pending",
    "paymentStatus": "unpaid",
    "externalId": "POS-88231"
  }'

Pass a stable externalId so you can detect and skip duplicates if a create
call is retried after a network error.