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

List Orders

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

Query Parameters

ParameterDescription
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

FieldDescription
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