Skip to guide
Podyx Developers Studio API v2

STUDIO API / CAPABILITY GUIDES

Read Markdown ↗

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 to learn when an order changes and the lists to reconcile its current state.

Choose a collection

Use List studio bookings for booking records from your studio, including package redemptions and expired reservations. It requires sessions:read and payments:read.

Use List studio purchases 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.