Orders

List and retrieve orders

Money taken for something: its lines, payments, refunds and what is still owed.

The order object

A test key sees and writes only test rows of this object. See Test data.

idstringrequired

A order id, ord_ and 22 characters.

object"order"required

numberstringrequired

referencestringrequirednullable

typestringrequirednullable

booking, event, gift_card or pos.

statusstringrequirednullable

venuestringrequirednullable

A venue id, ven_ and 22 characters.

customerstringrequirednullable

A customer id, cus_ and 22 characters.

bookingstringrequirednullable

A booking id, bkg_ and 22 characters.

eventstringrequirednullable

A event id, evt_ and 22 characters.

billing_detailsobjectrequired

Who the order was for when it was taken. Can differ from the customer today.

billing_details.namestringrequirednullable

billing_details.emailstringrequirednullable

billing_details.phonestringrequirednullable

currencystringrequired

ISO 4217 currency code, lowercase, e.g. aud.

subtotalintegerrequired

An amount in whole cents.

discountintegerrequired

An amount in whole cents.

discount_codestringrequirednullable

gift_cardintegerrequired

An amount in whole cents.

store_creditintegerrequired

An amount in whole cents.

totalintegerrequired

An amount in whole cents.

amount_paidintegerrequired

Paid, net of refunds.

amount_refundedintegerrequired

An amount in whole cents.

amount_dueintegerrequired

An amount in whole cents.

due_datestringrequirednullable

A UTC instant, ISO 8601, e.g. 2026-10-08T03:00:00.000Z.

linesarray of objectsrequired

lines[].idstringrequired

lines[].namestringrequirednullable

lines[].typestringrequirednullable

lines[].categorystringrequirednullable

lines[].quantityintegerrequired

lines[].unit_priceintegerrequired

An amount in whole cents.

lines[].totalintegerrequired

An amount in whole cents.

lines[].discountintegerrequired

An amount in whole cents.

lines[].taxintegerrequired

An amount in whole cents.

lines[].tax_ratestringrequirednullable

lines[].adjustsstringrequirednullable

The line this one adjusts. Lines are never edited.

paymentsarray of objectsrequired

payments[].amountintegerrequired

An amount in whole cents.

payments[].methodstringrequirednullable

payments[].statusstringrequirednullable

payments[].cardobjectrequirednullable

payments[].card.brandstringrequirednullable

payments[].card.last4stringrequired

payments[].processed_atstringrequirednullable

A UTC instant, ISO 8601, e.g. 2026-10-08T03:00:00.000Z.

refundsarray of objectsrequired

refunds[].amountintegerrequired

An amount in whole cents.

refunds[].reasonstringrequirednullable

refunds[].statusstringrequirednullable

refunds[].processed_atstringrequirednullable

A UTC instant, ISO 8601, e.g. 2026-10-08T03:00:00.000Z.

livemodebooleanrequired

False for test data, true for real data.

created_atstringrequired

A UTC instant, ISO 8601, e.g. 2026-10-08T03:00:00.000Z.

updated_atstringrequired

A UTC instant, ISO 8601, e.g. 2026-10-08T03:00:00.000Z.

The order object

{
  "id": "ord_0TMXp8QPR6yGvKuV2GZQ10",
  "object": "order",
  "number": "<string>",
  "reference": "<string>",
  "type": "<string>",
  "status": "<string>",
  "venue": "ven_0TMXp8QPR6yGvKuV2GZQ10",
  "customer": "cus_0TMXp8QPR6yGvKuV2GZQ10",
  "booking": "bkg_0TMXp8QPR6yGvKuV2GZQ10",
  "event": "evt_0TMXp8QPR6yGvKuV2GZQ10",
  "billing_details": {
    "name": "<string>",
    "email": "alex@example.com",
    "phone": "<string>"
  },
  "currency": "aud",
  "subtotal": 4500,
  "discount": 4500,
  "discount_code": "<string>",
  "gift_card": 4500,
  "store_credit": 4500,
  "total": 4500,
  "amount_paid": 1,
  "amount_refunded": 4500,
  "amount_due": 4500,
  "due_date": "2026-10-08T03:00:00.000Z",
  "lines": [
    {
      "id": "<string>",
      "name": "<string>",
      "type": "<string>",
      "category": "<string>",
      "quantity": 1,
      "unit_price": 4500,
      "total": 4500,
      "discount": 4500,
      "tax": 4500,
      "tax_rate": "<string>",
      "adjusts": "<string>"
    }
  ],
  "payments": [
    {
      "amount": 4500,
      "method": "<string>",
      "status": "<string>",
      "card": {
        "brand": "<string>",
        "last4": "<string>"
      },
      "processed_at": "2026-10-08T03:00:00.000Z"
    }
  ],
  "refunds": [
    {
      "amount": 4500,
      "reason": "<string>",
      "status": "<string>",
      "processed_at": "2026-10-08T03:00:00.000Z"
    }
  ],
  "livemode": true,
  "created_at": "2026-10-08T03:00:00.000Z",
  "updated_at": "2026-10-08T03:00:00.000Z"
}

List orders

GEThttps://api.hatcel.com/orders

Any key

Every order the key can see, newest first, a page at a time.

Query parameters

limitinteger

How many to return, 1 to 100. Defaults to 25.

starting_afterstring

The next_cursor of the page before. Omit it for the first page.

updated_sincestring

Only rows changed at or after this instant, ISO 8601 with an offset.

customerstring

Only those for this customer, by its cus_ id.

bookingstring

Only those for this booking, by its bkg_ id.

venuestring

Only those for this venue, by its ven_ id.

numberstring

The order number.

curl "https://api.hatcel.com/orders?limit=25" \
  -H "Authorization: Bearer $HATCEL_API_KEY" \
  -H "Hatcel-Version: 2026-10-08"

200 response

{
  "object": "list",
  "data": [
    {
      "id": "ord_0TMXp8QPR6yGvKuV2GZQ10",
      "object": "order",
      "number": "<string>",
      "reference": "<string>",
      "type": "<string>",
      "status": "<string>",
      "venue": "ven_0TMXp8QPR6yGvKuV2GZQ10",
      "customer": "cus_0TMXp8QPR6yGvKuV2GZQ10",
      "booking": "bkg_0TMXp8QPR6yGvKuV2GZQ10",
      "event": "evt_0TMXp8QPR6yGvKuV2GZQ10",
      "billing_details": {
        "name": "<string>",
        "email": "alex@example.com",
        "phone": "<string>"
      },
      "currency": "aud",
      "subtotal": 4500,
      "discount": 4500,
      "discount_code": "<string>",
      "gift_card": 4500,
      "store_credit": 4500,
      "total": 4500,
      "amount_paid": 1,
      "amount_refunded": 4500,
      "amount_due": 4500,
      "due_date": "2026-10-08T03:00:00.000Z",
      "lines": [
        {
          "id": "<string>",
          "name": "<string>",
          "type": "<string>",
          "category": "<string>",
          "quantity": 1,
          "unit_price": 4500,
          "total": 4500,
          "discount": 4500,
          "tax": 4500,
          "tax_rate": "<string>",
          "adjusts": "<string>"
        }
      ],
      "payments": [
        {
          "amount": 4500,
          "method": "<string>",
          "status": "<string>",
          "card": {
            "brand": "<string>",
            "last4": "<string>"
          },
          "processed_at": "2026-10-08T03:00:00.000Z"
        }
      ],
      "refunds": [
        {
          "amount": 4500,
          "reason": "<string>",
          "status": "<string>",
          "processed_at": "2026-10-08T03:00:00.000Z"
        }
      ],
      "livemode": true,
      "created_at": "2026-10-08T03:00:00.000Z",
      "updated_at": "2026-10-08T03:00:00.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJ0IjoiMjAyNi0xMC0wOFQwMzowMDowMC4wMDBaIiwiaSI6IjBmOGZhZDViIn0"
}

Retrieve a order

GEThttps://api.hatcel.com/orders/{id}

Any key

One order by its id, with its version in the ETag header. Another object's id, or one this key cannot see, is a 404.

Path parameters

idstringrequired

The order's id, ord_ and 22 characters.

curl "https://api.hatcel.com/orders/ord_0TMXp8QPR6yGvKuV2GZQ10" \
  -H "Authorization: Bearer $HATCEL_API_KEY" \
  -H "Hatcel-Version: 2026-10-08"

200 response

{
  "id": "ord_0TMXp8QPR6yGvKuV2GZQ10",
  "object": "order",
  "number": "<string>",
  "reference": "<string>",
  "type": "<string>",
  "status": "<string>",
  "venue": "ven_0TMXp8QPR6yGvKuV2GZQ10",
  "customer": "cus_0TMXp8QPR6yGvKuV2GZQ10",
  "booking": "bkg_0TMXp8QPR6yGvKuV2GZQ10",
  "event": "evt_0TMXp8QPR6yGvKuV2GZQ10",
  "billing_details": {
    "name": "<string>",
    "email": "alex@example.com",
    "phone": "<string>"
  },
  "currency": "aud",
  "subtotal": 4500,
  "discount": 4500,
  "discount_code": "<string>",
  "gift_card": 4500,
  "store_credit": 4500,
  "total": 4500,
  "amount_paid": 1,
  "amount_refunded": 4500,
  "amount_due": 4500,
  "due_date": "2026-10-08T03:00:00.000Z",
  "lines": [
    {
      "id": "<string>",
      "name": "<string>",
      "type": "<string>",
      "category": "<string>",
      "quantity": 1,
      "unit_price": 4500,
      "total": 4500,
      "discount": 4500,
      "tax": 4500,
      "tax_rate": "<string>",
      "adjusts": "<string>"
    }
  ],
  "payments": [
    {
      "amount": 4500,
      "method": "<string>",
      "status": "<string>",
      "card": {
        "brand": "<string>",
        "last4": "<string>"
      },
      "processed_at": "2026-10-08T03:00:00.000Z"
    }
  ],
  "refunds": [
    {
      "amount": 4500,
      "reason": "<string>",
      "status": "<string>",
      "processed_at": "2026-10-08T03:00:00.000Z"
    }
  ],
  "livemode": true,
  "created_at": "2026-10-08T03:00:00.000Z",
  "updated_at": "2026-10-08T03:00:00.000Z"
}

Bookings Activities