Bill API order.bill

Retrieve bills (checks/orders) with their aggregated amounts, including the payment and product-line records belonging to each bill.

1. Getting started#

1.1 Credentials#

To call this API you need two values, issued by OrderPin:

Every request must include both. Requests are automatically scoped to the data of the store associated with your credentials; you cannot read another store's data, and you do not need to specify it.

Getting credentials: email api@orderpin.us with your Store ID — that is all OrderPin needs to issue your Client ID and API key. Credentials are issued per store: if your company has several stores, request a separate set for each Store ID.

1.2 Endpoint#

There are two equivalent ways to call the API.

Path form (recommended) — the API name is part of the URL:

POST https://{base-url}/orderpin/oapi/order/bill/v1

The version segment is optional — POST https://{base-url}/orderpin/oapi/order/bill uses the current default version (v1). Pinning the version explicitly is recommended so that your integration is not affected by future default-version changes.

⚠️ Because the API name order.bill contains a dot, the path form splits it into URL segments (/order/bill). Take care not to confuse POST …/order/bill with the Transaction API's POST …/order/bill/transaction.

Generic form — call the base endpoint and declare the API in the request body:

POST https://{base-url}/orderpin/oapi

{
  "subject": "order.bill",
  "version": "v1",
  "filter": { "createStartAt": 1767225600000, "createEndAt": 1769817600000 }
}

With this form, subject is required (an unknown or missing subject/version is reported with code 1020); version is optional and defaults to v1. All other parameters (§3) are the same. The path form is preferred.

1.3 Request headers#

A JSON request body is always required, even when you have no filters to send — use {}. A request with an empty body is rejected.

2. Request format#

{
  "filter": {
    "<parameter>": "<value or array of values>"
  },
  "skip": 0,
  "limit": 100,
  "sort": [
    { "field": "<field name>", "type": "desc" }
  ],
  "with_record_count": true
}

Example#

POST /orderpin/oapi/order/bill/v1 HTTP/1.1
Host: {base-url}
X-Client-ID: US00000001
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "filter": {
    "billType": ["sales", "refund"],
    "createStartAt": 1767225600000,
    "createEndAt":   1769817600000
  },
  "skip": 0,
  "limit": 100,
  "sort": [{ "field": "createAt", "type": "desc" }],
  "with_record_count": true
}

3. Request parameters#

Unrecognized parameters are rejected. Only the parameters listed below are accepted.

3.1 Query parameters#

3.2 Filter parameters#

All timestamps are Unix epoch time in milliseconds (UTC).

Note: createAt reflects the bill's checkout time, not the moment the record was written.

Data freshness#

Reporting data becomes queryable approximately 15 minutes after it is recorded. A timestamp filter value that is less than 15 minutes (900000 ms) old — or in the future — is rejected with data from the last 15 minutes is not yet available for query. When polling for new data, end your query range at now - 15 minutes.

Using date ranges#

createStartAt / createEndAt and modifiedStartAt / modifiedEndAt are paired range filters:

• Both halves must be sent together. Sending only one is rejected with missing pair filter.
• The range is half-open: start <= value < end.
• start must be earlier than end.
• The span must be less than 31 days (2678400000 ms). Wider ranges are rejected.
• Each half must also satisfy the data freshness rule above.

This makes range filters ideal for incremental synchronization: poll with modifiedStartAt / modifiedEndAt to pick up records that changed since your last run.

Value types#

Values are type-checked. Sending a number where a string is expected (or vice versa) is rejected — for example, uid must be a string, and modifiedAt must be a number.

When a filter accepts an array, it behaves as "matches any of these values".

4. Response format#

A successful request returns HTTP 200 with a JSON object. One record per bill — amounts are already aggregated across the bill's transactions:

{
  "bill": [
    {
      "uid": "B202601010001",
      "billNo": "N-0001",
      "originalBillId": "",
      "originalBillNo": "",
      "createAt": 1767254400000,
      "modifiedAt": 1767254400000,
      "table": "A1",
      "mealNo": "M0001",
      "employeeId": "E10086",
      "employeeName": "Alice",
      "shiftId": "S5001",
      "orderType": 10,
      "billType": "sales",
      "itemsAmount": 5000,
      "autoPricing": 0,
      "temporaryCharge": 0,
      "grossAmount": 5000,
      "discount": 500,
      "netAmount": 4500,
      "taxes": 405,
      "surcharge": 0,
      "serviceCharge": 0,
      "tips": 900,
      "grossReceipts": 5805,
      "payments": [
        {
          "uid": "T900001",
          "status": "settled",
          "paymentMethod": "card",
          "paymentChannel": "STRIPE",
          "EDCType": "credit",
          "cardIssuer": "VISA",
          "cardNo": "4242XXXXXXXX4242",
          "authCode": "A12345",
          "currency": "USD",
          "amount": 5805,
          "tipsAmount": 900,
          "commissionFee": 0,
          "ccCost": 170,
          "deviceId": "D001",
          "deviceName": "Terminal 1",
          "createAt": 1767254400000,
          "modifiedAt": 1767254400000
        }
      ],
      "products": [
        {
          "uid": "I700001",
          "skuId": "SKU001",
          "skuName": "Burger",
          "quantity": 2,
          "currency": "USD",
          "productDiscount": 0,
          "discount": 500,
          "coupon": 0,
          "grossSales": 5000,
          "amount": 4500,
          "taxes": 450,
          "taxesExempt": 0,
          "taxesPay": 405,
          "category": [
            { "categoryId": "C01", "categoryName": "Mains" }
          ]
        }
      ]
    }
  ],
  "recordCount": 300
}

All monetary values are integers in the currency's minor units (e.g. cents — 5805 = 58.05).

4.1 Bill fields (bill[])#

4.2 Payment fields (bill[].payments[])#

The same records can be queried flat (across bills) via the Transaction API.

4.3 Product fields (bill[].products[])#

5. Sorting and pagination#

5.1 Sorting#

sort accepts a single object or an array of objects (applied in order):

"sort": [
  { "field": "createAt", "type": "desc" },
  { "field": "uid",      "type": "asc" }
]

type must be asc or desc, and both field and type are required.

Sortable fields: uid, billNo, createAt, modifiedAt.

Sorting by billNo orders by checkout time, not alphabetically by the number itself.

Sorting is supported only on these fields. Using any other name is rejected:

• A valid response field that does not support sorting (e.g. billType, netAmount) → field <name> not sortable
• A name that is not a response field (including filter names such as modifiedStartAt) → unknown sort field <name>

5.2 Pagination#

Results are limited to 200 records per request. To page through a larger result set:

1. Send the first request with "with_record_count": true, "skip": 0, "limit": 200.
2. Read recordCount from the response to determine the number of pages.
3. Repeat, increasing skip by limit each time, until all records are retrieved.

Always use a sort when paginating so that the ordering is stable across pages.

6. Errors#

Successful requests return HTTP 200. Errors return the HTTP status that matches the error category, with a JSON body:

{
  "code": 1004,
  "msg": "Error: [order.bill.v1] filter billType: value expected [sales | refund | giftcard | giftcardRefund] [bogus]"
}

Read the code field for the precise reason. The HTTP status groups errors by category: 4xx for request and credential problems, 429 for rate limiting, 5xx for server-side failures.

6.1 Common 1004 validation messages#

7. Rate limits#

Requests are limited per client ID, and the quota is shared across the whole service — running several workers in parallel does not give you extra capacity.

The exact values are configured per environment. Read them from the response headers rather than hard-coding them:

When you exceed the quota the response is:

HTTP/1.1 429 Too Many Requests
Retry-After: 37
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0

{ "code": 2012, "msg": "[2012] Error: rate limit exceeded, retry after 37 second(s)" }

The window slides continuously rather than resetting at a fixed boundary, so quota comes back gradually. Waiting the full Retry-After is always sufficient.

How to stay within the limit#

• Retry on 429 using Retry-After, not a fixed sleep. Add jitter if you run multiple workers.
• Watch X-RateLimit-Remaining and slow down before you hit zero.
• Prefer wide queries over many narrow ones. Bill records are large (they embed payments and products); a range query with limit: 200 is far cheaper than one request per bill.
• Do not retry 5xx in a tight loop — those attempts also consume quota.

Rate limiting is applied only after your credentials have been verified, so a request that fails authentication does not consume your quota.

8. Recommendations#

• Filter by modifiedStartAt / modifiedEndAt for incremental synchronization; bills change after checkout (tips, refunds, voids), and the modified range picks all of that up.
• Keep ranges under 31 days. Split longer periods into multiple requests.
• Always send a sort when paginating so pages do not overlap or skip records.
• Request with_record_count once (on the first page) rather than on every page.
• Handle refunds explicitly. billType: "refund" bills reference the original via originalBillId; include or exclude them deliberately in revenue calculations.
• Exclude voided payments from tender totals.
• Protect your API key. Send it only over HTTPS, never embed it in client-side code, and email api@orderpin.us immediately if you suspect it has been exposed.
• Retry transient failures (1003, 1012) with exponential backoff, and honor Retry-After on 429.

9. Full example#

curl -X POST 'https://{base-url}/orderpin/oapi/order/bill/v1' \
  -H 'X-Client-ID: US00000001' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
        "filter": {
          "createStartAt": 1767225600000,
          "createEndAt":   1769817600000
        },
        "skip": 0,
        "limit": 200,
        "sort": [{ "field": "createAt", "type": "desc" }],
        "with_record_count": true
      }'