# Read orders and reconcile referrals

Use the order lists to backfill sales, identify applied promo codes and check what was collected or refunded.

Use [signed order webhooks](/api/docs/guides/v2/webhooks#order-events) to learn when an order changes and the lists to reconcile its current state.

## Choose a collection

Use [List studio bookings](/api/docs#/Studio%20orders/v2ListBookings) for booking records from your studio, including package redemptions and expired reservations. It requires `sessions:read` and `payments:read`.

Use [List studio purchases](/api/docs#/Studio%20orders/v2ListPurchases) for sales. This includes individual bookings, bundles, subscriptions and separately purchased add-ons. A booking that uses an already-purchased package represents usage of that package. It creates no additional package sale. The purchases list requires `purchases:read` and `payments:read`.

The purchases list excludes expired reservations with no completed collection from both its entries and total count before pagination. An expired booking with a collected charge remains a purchase after that charge is refunded.

Each row has a durable record `id`, a `kind`, and the displayed `order_id` where recorded. A headless checkout or purchase attempt has its own ID. Save that attempt ID from the response when your integration needs to fetch its checkout state later.

## Filter by order date

Both lists accept inclusive `date_from` and `date_to` in `YYYY-MM-DD` format. The API interprets midnight in the studio's timezone, including clock changes. `ordered_at` returns the matching timestamp in UTC.

Booking dates use record creation. Purchase dates use the sold record's purchase time. A later add-on uses the recorded request or charge time shown in Purchases. If that timestamp is unavailable, it uses the add-on record's creation time. Refunds update the existing order representation. Read the order's date range again to reconcile a change.

Use `sort=asc` or `sort=desc`. The default is `desc`. Equal timestamps are ordered by kind and ID. Use `page` and `per_page` to page through `data.entries`. The default page size is 20, and the maximum is 100.

## Read referral and settlement facts

- Match `promo_code_id` to a partner. Both discount fields are decimal strings in major units of `currency`.
- `promo_discount_amount` is the recorded applied discount. It includes tax when the discount was applied against tax-inclusive prices or a committed gross subscription price. When applied against tax-exclusive prices, the recorded amount already excludes tax.
- `promo_discount_amount_ex_tax` is the discount excluding tax. For tax-inclusive bookings, the API removes tax at the saved rate using the currency's display precision and caps the result at the recorded discount. Tax-exclusive bookings already record the net amount. For bundles and subscriptions, the API uses the difference between the saved net subtotal before the discount and the saved total minus tax after the discount. A recorded zero returns `"0"`. The field is null when the recorded amount, currency, or pricing facts do not establish the net discount.
- `promo_code_source=recorded` means the API returns the text saved when the promo was applied. New bookings retain that text after a rename or deactivation. For older orders without a saved label, `current` means the API looked up the code's current text, which can change after a rename. A key with a promo-code create, update or delete permission can see the text. Missing text and its source are returned as null.
- Use `client_id` to identify the client. The order lists omit contact details.
- `payment_status` describes whether the order is `paid`, `partially_paid`, `pending`, `unpaid`, `outside_podyx`, `not_required` or `unknown`. `outside_podyx` indicates that at least part of collection is handled outside Podyx and the API cannot verify the entire amount. `not_required` means there was no collection due. `unknown` indicates insufficient evidence.
- `refund_status` is `none`, `pending`, `partially_refunded`, `refunded` or `unknown`. Pending includes an accepted provider refund that has yet to complete. `refunded_amount` includes completed returns only. A booking's applicable transactions include its current checkout payment, attached session amendments and completed refunds on earlier collected checkout attempts. When an earlier attempt is included, its collection is also included in `collected_amount`. A separately sold add-on has its own row. A subscription purchase covers the initial purchase period.
- `collected_amount` and `refunded_amount` are decimal strings in `currency`. The API returns null for aggregates when it lacks evidence or the recorded transactions use incompatible currencies.
- A wallet hold on an expired reservation and its release are excluded from both monetary amounts. An expired reservation with no completed collection has `payment_status=unpaid` and `refund_status=none` when its currency is known.
- A recorded wallet return can contribute to `refunded_amount` even when an outside payment leaves the overall refund status unknown. Wallet amounts for a separately purchased add-on belong to the first settled attempt that finalized the line.

Request `include=order` on an existing checkout, purchase or Member Bundle detail to see the associated order projection when available. The request also needs the corresponding list scopes. An attempt with no associated sold package returns `order: null`.

## Example

```sh
curl --get 'https://app.podyx.com/api/v2/purchases' \
  -H "Authorization: Bearer $PODYX_API_KEY" \
  --data-urlencode 'date_from=2026-11-01' \
  --data-urlencode 'date_to=2026-11-07' \
  --data-urlencode 'sort=asc' \
  --data-urlencode 'per_page=50'
```

An order in USD with tax-inclusive prices and a saved 5% tax rate can return the following fields.

```json
{
  "currency": "USD",
  "promo_discount_amount": "37.50",
  "promo_discount_amount_ex_tax": "35.71"
}
```
