List Orders

Retrieve your store's orders (POS and website), newest first. Monetary amounts are returned in cents.

Query Parameters

Parameter	Description
limit integer • optional	Number of orders to return. Default 50, maximum 100.
page integer • optional	Page number for pagination. Default 1.
status string • optional	Payment status, e.g. `PENDING`, `SUCCEEDED`, `FAILED`.
fulfillment_status string • optional	Fulfillment stage, e.g. `PENDING`, `CONFIRMED`, `DELIVERED`.
source string • optional	Order origin: `POS` or `WEBSITE`.
search string • optional	Receipt number or customer email.

Request Example

cURL

curl "https://api.posnova.store/v1/orders?status=PENDING&source=WEBSITE" \
  -H "Authorization: Bearer pn_live_YourSecretKey"

JavaScript

const res = await fetch("https://api.posnova.store/v1/orders?status=PENDING&source=WEBSITE", {
  headers: { Authorization: `Bearer ${process.env.POSNOVA_API_KEY}` },
});
const { data, pagination } = await res.json();

JSON Response

{
  "success": true,
  "data": [
    {
      "id": "0d9c1f4e-…",
      "receipt_number": "R-000123",
      "status": "PENDING",
      "fulfillment_status": "PENDING",
      "payment_method": "COD",
      "amount": 174950,
      "total_amount": 174950,
      "currency": "USD",
      "customer_name": "Rahim Uddin",
      "source": "WEBSITE",
      "created_at": "2026-07-06T09:00:00Z"
    }
  ],
  "pagination": { "total": 231, "page": 1, "limit": 50 }
}

GET

https://api.posnova.store/v1/orders/{id}

Retrieve Order

Fetch a single order by its UUID or its receipt number. The response includes the full record with line_items.

POST

https://api.posnova.store/v1/orders

Create Order

Create an order from any client — mobile app, kiosk, IoT device, or backend. Clients send only product identifiers and quantities; the server resolves names, unit prices, and totals from the live catalog.

Request Body

Field	Description
items array • required	1–100 entries of `{ product_id, variant_id?, quantity }`. Quantity is an integer 1–999. Products must be active and belong to your store; variants must belong to their product.
customer.name string • required	Customer display name.
customer.email string • optional	Customer email for receipts and lookups.
customer.phone string • optional	Customer phone number.
customer.address / city / zip string • optional	Shipping address parts (also used as billing address).
payment_method string • optional	`COD` (default) or `OFFLINE`. Card/gateway payments must use the hosted storefront checkout.
notes string • optional	Free-text note, up to 2000 characters.

Example

POST /v1/orders
Authorization: Bearer pn_live_…
Content-Type: application/json

{
  "items": [
    { "product_id": 101, "quantity": 2 },
    { "product_id": 102, "variant_id": 55, "quantity": 1 }
  ],
  "customer": { "name": "Rahim Uddin", "phone": "01700000000", "city": "Dhaka" },
  "payment_method": "COD"
}

// 201 Created
{
  "success": true,
  "data": {
    "order_id": "0d9c1f4e-…",
    "receipt_number": "R-000124",
    "subtotal": 1749.5,
    "total": 1749.5,
    "payment_method": "COD",
    "items": [
      { "productId": "101", "name": "Wireless Headphones", "quantity": 2, "price": 499.75 }
    ]
  }
}

Server-side pricing

Any prices or totals included in the request body are ignored. Every line is re-priced from the database at creation time, and gateway callbacks independently verify the paid amount against the server-computed total. Orders created here run the full pipeline — fraud analysis, inventory updates, notifications — and appear in your dashboard as website orders. Failures return 400 for invalid input or 422 when the order engine rejects the request.

Status: Operational

Customers API