API · Orders | Usetix

Orders contain commercial product lines. Today a checkout can combine tickets from several events and gift vouchers; merchandise and other product types use the same line contract. Complimentary guest-list parties remain orders without a commercial checkout. Pending carts and abandoned checkouts are filtered out.

The detail response deliberately separates lines from items: lines are what the buyer paid for, while items are individual ticket admissions with check-in state. A group-ticket line can therefore have quantity 1 and several admission items; a voucher line has no admission item.

The status field reflects current state: paid, refund_pending, refund_failed, refunded, partially_refunded, or booking_cancelled (a guest-list party that was later removed). origin is checkout for paid sales and guest_list for comps.

Guest-list parties have no customer_email. Use delivery_email for optional ticket delivery and staff_note for the door hint. To create or cancel comps, use the Guest list API — do not treat them as Stripe refunds.

Order URLs accept either identifier returned by the API: the stable public_id (abcd1234efgh5678) or the human order code (7K3Q-9D2A). Formatting and letter case in an order code are ignored. Store public_id as your durable correlation key; use display_number when a person needs to type or read it.

Use shop_url to send the buyer directly to this order in the shop. It uses the verified custom domain when configured, otherwise the account shop subdomain. The link requires no login and grants access to the entire order, including its tickets and available invoice. Share it only with the buyer. Cancelled, refunded, or archived orders show their current state; the link does not sign the buyer into their customer account.

`GET /admin/orders`

Returns paid orders in your account, with revenue stats for the period filter.

curl -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  https://app.usetix.io/admin/orders

Query parameters:

Parameter	Description
`period`	One of `today`, `week`, `month`, `year`, `all`. Defaults to `all` (no time restriction). The period applies only to the current request.
`event_slug`	Filter to orders for a specific event.
`query`	Free-text search across order code, order public ID, ticket check-in code, ticket public ID, voucher-purchase ID, voucher public ID or code, customer name, customer email, delivery email, attendee name, and Stripe payment intent ID. Prefix an event slug with `@`.
`include_archived`	Set to `1` to include archived paid/refunded orders. Defaults to excluding archived orders.
`limit`	Orders per page, from `1` to `100`. Defaults to `50`.
`page`	Opaque cursor from the previous response’s `pagination.next_page` value. Do not parse or construct it.

Response:

{
  "orders": [
    {
      "public_id": "abcd1234efgh5678",
      "shop_url": "https://example-shop.usetix.io/orders/abcd1234efgh5678",
      "order_code": "7K3Q9D2A",
      "display_number": "7K3Q-9D2A",
      "status": "paid",
      "origin": "checkout",
      "customer_name": "Jane Doe",
      "customer_email": "jane@example.com",
      "delivery_email": null,
      "staff_note": null,
      "total": { "amount": "42.00", "currency": "EUR" },
      "fees": { "buyer_platform_fee": "0.00", "custom": "0.00" },
      "payment_provider": "stripe",
      "archived": false,
      "paid_at": "2026-04-22T12:34:50Z",
      "created_at": "2026-04-22T12:34:00Z",
      "item_count": 2,
      "line_count": 2,
      "product_quantity": 3,
      "attribution": {
        "utm_source": "google",
        "utm_medium": "cpc",
        "utm_campaign": "spring-launch"
      }
    }
  ],
  "stats": {
    "order_count": 137,
    "revenue": { "amount": "5754.00", "currency": "EUR" }
  },
  "pagination": {
    "total_count": 137,
    "limit": 50,
    "next_page": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNC0yMlQxMjozNDowMC4wMDAwMDBaIiwicHVibGljX2lkIjoiYWJjZDEyMzRlZmdoNTY3OCJ9"
  }
}

stats and pagination.total_count describe the full filtered result, not only the current page. When another page exists, the same cursor is also exposed as an RFC 8288 Link response header with rel="next"; X-Total-Count contains the total number of matching orders. next_page is null on the final page.

CSV and Excel exports

The order CSV/XLSX export appends an Order link column containing shop_url. Event attendee exports also append the order link after all existing columns, including custom checkout answers. Every admission in the same order has the same link, even when the order contains tickets for several events.

`GET /admin/orders/:identifier`

Returns a single order with its line items. identifier may be its public_id, unformatted order_code, or formatted display_number.

curl -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  https://app.usetix.io/admin/orders/7K3Q-9D2A

Response:

{
  "public_id": "abcd1234efgh5678",
  "shop_url": "https://example-shop.usetix.io/orders/abcd1234efgh5678",
  "order_code": "7K3Q9D2A",
  "display_number": "7K3Q-9D2A",
  "status": "paid",
  "origin": "checkout",
  "customer_name": "Jane Doe",
  "customer_email": "jane@example.com",
  "delivery_email": null,
  "staff_note": null,
  "total": { "amount": "42.00", "currency": "EUR" },
  "fees": { "buyer_platform_fee": "0.00", "custom": "2.50" },
  "payment_provider": "stripe",
  "archived": false,
  "paid_at": "2026-04-22T12:34:50Z",
  "created_at": "2026-04-22T12:34:00Z",
  "item_count": 2,
  "line_count": 2,
  "product_quantity": 2,
  "attribution": {
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "spring-launch",
    "utm_term": "concert tickets berlin",
    "utm_content": "ad-variant-a",
    "ref": "partner:radiox"
  },
  "lines": [
    {
      "public_id": "line_ticket_123",
      "product_id": "product_ticket_123",
      "product_type": "ticket",
      "name": "General Admission",
      "description": "Spring Showcase",
      "quantity": 1,
      "unit_price": { "amount": "17.00", "currency": "EUR" },
      "subtotal": { "amount": "17.00", "currency": "EUR" },
      "discount": { "amount": "0.00", "currency": "EUR" },
      "tax": { "rate": "19.0", "amount": "2.71", "currency": "EUR" },
      "total": { "amount": "17.00", "currency": "EUR" },
      "fulfilled_at": "2026-04-22T12:34:50Z"
    },
    {
      "public_id": "line_voucher_456",
      "product_id": "product_voucher_456",
      "product_type": "voucher",
      "name": "Gift 25",
      "description": "A gift for any Usetix Club event",
      "quantity": 1,
      "unit_price": { "amount": "25.00", "currency": "EUR" },
      "subtotal": { "amount": "25.00", "currency": "EUR" },
      "discount": { "amount": "0.00", "currency": "EUR" },
      "tax": { "rate": "0.0", "amount": "0.00", "currency": "EUR" },
      "total": { "amount": "25.00", "currency": "EUR" },
      "fulfilled_at": "2026-04-22T12:34:50Z",
      "voucher_purchase": {
        "public_id": "voucher_purchase_456",
        "status": "paid",
        "voucher_amount": { "amount": "75.00", "currency": "EUR" },
        "paid_amount": { "amount": "50.00", "currency": "EUR" },
        "bonus_amount": { "amount": "25.00", "currency": "EUR" },
        "recipient_name": "Alex Doe",
        "recipient_email": "alex@example.com",
        "delivery_mode": "email_scheduled",
        "scheduled_for": "2026-04-30T08:00:00Z",
        "delivered_at": null,
        "voucher_id": "voucher_456"
      }
    }
  ],
  "items": [
    {
      "public_id": "ord_item_xyz789",
      "check_in_code": "9M5V2H8C",
      "display_check_in_code": "9M5V-2H8C",
      "ticket_title": "General Admission",
      "attendee_name": "Jane Doe",
      "place_label": null,
      "event_id": 42,
      "event_slug": "spring-showcase",
      "redeemed": false,
      "redeemed_at": null,
      "admission_status": "active",
      "admission_cancellation_status": null,
      "blocked_reason": null
    }
  ]
}

`POST /admin/orders/:identifier/refund`

Refunds a paid order. Requires a Read + Write token. Send amount for a partial refund; omit it for a full refund of the remaining amount.

curl -X POST \
  -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"amount": "5.00"}' \
  https://app.usetix.io/admin/orders/abcd1234efgh5678/refund

Response: 200 OK with the updated order object. The refund is processed asynchronously by the payment provider, so the order returns as refund_pending and settles to partially_refunded or refunded.

Validation failures return 422 Unprocessable Entity with an error map:

{ "errors": { "amount": ["Please enter a valid amount"] } }

A full-amount refund on an order that still qualifies for whole-booking cancellation is rejected with 422; use the cancellation endpoint below so inventory is released together with the payment. Arbitrary partial-amount refunds on mixed-tax orders are also rejected because the tax credit would be ambiguous; refund a specific admission or cancel the full order instead.

When the order sold a voucher, a successful full refund blocks that voucher and drains its remaining balance. Usetix refuses an organizer-initiated full refund after the voucher was used, reserved by another checkout, or manually adjusted. This prevents refunding the buyer after value has already left the voucher.

`POST /admin/orders/:identifier/cancellation`

Cancels the whole booking: releases the tickets back to inventory and refunds the full remaining amount. Requires a Read + Write token. Free and guest-list bookings are cancelled without a payment refund.

curl -X POST \
  -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  https://app.usetix.io/admin/orders/abcd1234efgh5678/cancellation

Response: 200 OK with the updated order — refund_pending for paid orders, booking_cancelled for free ones. Orders that cannot be cancelled (already redeemed tickets, unresolved refunds) return 422 with { "errors": { "base": ["…"] } }.

`POST /admin/orders/:identifier/archival`

Archives a settled checkout order and releases its inventory. Requires a Read + Write token. Archived orders disappear from the default list; include them with include_archived=1.

curl -X POST \
  -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  https://app.usetix.io/admin/orders/abcd1234efgh5678/archival

`DELETE /admin/orders/:identifier/archival`

Restores an archived order and reclaims its tickets.

Response: both archival calls return 200 OK with the updated order; the archived field reflects the new state. Orders with unresolved refunds or cancellations return 422 with { "errors": { "base": ["…"] } }.

Order fields

Field	Type	Notes
`public_id`	string	Public order ID. Stable; safe to store as your correlation key. URL-safe random token.
`shop_url`	string	Customer link to the entire order, including tickets and the available invoice. No login required.
`order_code`	string	Human-readable order code. Safe to show in admin/customer-facing UI.
`display_number`	string	Formatted order code for display, typically grouped as `XXXX-XXXX`.
`status`	string	`paid`, `refund_pending`, `refund_failed`, `refunded`, `partially_refunded`, or `booking_cancelled`.
`origin`	string	`checkout` or `guest_list`.
`customer_name`	string	Buyer name, or the guest-list lead name.
`customer_email`	string \| null	Buyer’s email. Always `null` on guest-list parties.
`delivery_email`	string \| null	Guest-list ticket delivery address. `null` on checkout orders.
`staff_note`	string \| null	Guest-list door hint. `null` on checkout orders.
`total.amount`	string	Order total as decimal string.
`total.currency`	string	ISO 4217 code.
`fees.buyer_platform_fee`	string	Snapshotted Usetix fee the buyer paid. `"0.00"` when the organizer absorbed it. Retained on organizer-initiated refunds, but returned when a captured sale cannot be fulfilled.
`fees.custom`	string	Snapshotted extra checkout fee. Organizer revenue; refundable with the rest of the order.
`payment_provider`	string	`stripe` or `paypal`.
`archived`	boolean	`true` once the order has been archived. Archived orders are excluded from the default index.
`paid_at`	string \| null	ISO 8601 UTC. `null` if status is no longer `paid`.
`created_at`	string	ISO 8601 UTC. When the order was first opened.
`item_count`	integer	Number of ticket admissions in the order. Kept for compatibility; vouchers and future non-ticket products are not included.
`line_count`	integer	Number of commercial product lines. Guest-list and legacy orders may return `0`.
`product_quantity`	integer	Sum of line quantities, falling back to `item_count` for legacy orders. A group-ticket bundle counts as one product even when it fulfills several admissions.
`attribution`	object	Marketing attribution captured at checkout. Always present; `{}` if the buyer arrived with no tracking parameters. See Attribution.
`lines[].public_id`	string	Stable public ID of the snapshotted commercial line.
`lines[].product_id`	string \| null	Stable catalog product ID. `null` only for a historical line whose product was deleted before the catalog migration.
`lines[].product_type`	string	Domain kind such as `ticket` or `voucher`. New product kinds extend this field without changing the line contract.
`lines[].name`	string	Product name snapshotted at checkout.
`lines[].description`	string \| null	Product context snapshotted at checkout, such as the event title.
`lines[].quantity`	integer	Purchased product units or bundles.
`lines[].unit_price`, `lines[].subtotal`, `lines[].discount`, `lines[].total`	money object	Snapshotted commercial amounts with decimal `amount` and ISO `currency`. `total` includes checkout fees allocated to the line and, for tax-exclusive shops, that line’s tax.
`lines[].tax`	object	Snapshotted `rate`, `amount`, and `currency`. Voucher stored value uses rate `0`; tax is charged when the voucher buys the eventual goods or admission.
`lines[].fulfilled_at`	string \| null	ISO 8601 UTC timestamp after admissions or voucher issuance completed.
`lines[].voucher_purchase`	object \| omitted	Present on voucher lines. Contains purchase ID, state, voucher credit, paid amount, promotional bonus amount, recipient name/email, `delivery_mode` (`self_managed`, `email_now`, or `email_scheduled`), optional `scheduled_for`, `delivered_at`, and the issued voucher public ID. It never exposes the bearer voucher code.
`items[].public_id`	string	Public ID of the order item (one per ticket). Used in scanner URLs and as the canonical queued-sync identifier.
`items[].check_in_code`	string	Human-readable ticket check-in code. Safe to show to staff and customers.
`items[].display_check_in_code`	string	Formatted check-in code for UI, typically grouped as `XXXX-XXXX`.
`items[].ticket_title`	string	Title of the ticket type at time of purchase.
`items[].attendee_name`	string \| null	Door display name. On guest list this is the lead or “Guest of …” companion name.
`items[].place_label`	string \| null	Numbered or standing label when the admission holds a place.
`items[].place_snapshot`	object	Present only when a place snapshot exists.
`items[].event_id`	integer	Internal ID of the event this ticket belongs to.
`items[].event_slug`	string	Slug of the event. Useful for linking.
`items[].redeemed`	boolean	`true` once the QR code has been scanned at the door.
`items[].redeemed_at`	string \| null	ISO 8601 UTC. `null` if not yet redeemed.
`items[].admission_status`	string	`active`, `cancelled`, `refund_pending`, or `refund_failed_reactivated`.
`items[].admission_cancellation_status`	string \| null	Underlying cancellation record status, when present.
`items[].blocked_reason`	string \| null	Why redemption is currently blocked.

Attribution

The attribution object captures where the buyer came from. UTM parameters and ref are read from the checkout page’s URL, and as a fallback the previous page’s URL via the Referer header, at the moment the buyer submits the order. There is no client-side persistence: the data only travels with the form submission itself. Practically this means last-click attribution: the source that delivered the buyer to the checkout page is what’s recorded.

Field	Type	Notes
`utm_source`	string \| omitted	e.g. `"google"`, `"facebook"`, `"newsletter"`.
`utm_medium`	string \| omitted	e.g. `"cpc"`, `"email"`, `"social"`.
`utm_campaign`	string \| omitted	Campaign name as set in the URL.
`utm_term`	string \| omitted	Paid keyword, when supplied.
`utm_content`	string \| omitted	Ad / creative variant, when supplied.
`ref`	string \| omitted	Free-form referral code. Usetix’s own shop footer links append `ref=shop:<subdomain>` when a buyer clicks through to the marketing site, so signups originating from a specific shop carry that source.

Only fields that were actually captured are included. Buyers who arrive with no tracking parameters get "attribution": {}.