Baskets

Use this endpoint to add an item to a Basket.

Creates a new Basket at a Site. The basket is the central object in Trybe's checkout flow — it accumulates items (appointments, area bookings, products, vouchers, memberships, etc.), customer details, coupons, vouchers, and payments before being submitted to create an Order.

If the request is authenticated as a Customer (e.g. via a customer access token), that customer is linked to the basket automatically. Otherwise pass customer_id to associate an existing customer, or omit it and call POST /shop/basket/{basketId}/customer later in the flow.

A "Website" SalesChannel is provisioned for the site's organisation on first use and reused thereafter.

Returns the full state of a Basket — its items, guests, payments, applied coupons and vouchers, totals, and submit state. This is the canonical endpoint frontends call after any mutating action to reconcile their local view of the cart.

Baskets that were submitted more than an hour ago and aren't attached to a visit return 404 so that completed checkouts can't be re-rendered by stale links.

Updates a small set of basket-level metadata. Use this to record special requests captured during checkout (e.g. dietary requirements, accessibility notes).

Returns 400 Bad Request if the basket has already been submitted or otherwise locked.

Returns the legal and clinical pre-flight data a shop frontend needs to render the final checkout step:

• terms — the booking terms & conditions the customer must accept, assembled from site, offering, and basket-level sources.
• contraindications — clinical contraindications attached to any appointment offerings in the basket (filtered to entries the customer must positively confirm).
• voucher_payment_enabled — whether external voucher redemption is configured for the basket's site.

Validates and applies a CouponCode to the basket. Coupons can grant percentage or fixed-amount discounts, automatic free items, or unlock pricing tiers — the basket totals are recalculated on success.

Customer-facing flows can only add coupons while the basket is in_progress. Staff (authenticated as a User) bypass that restriction provided they have the reservations.manage permission for the site.

Returns 400 Bad Request with a human-readable reason when the coupon is invalid, expired, fully redeemed, or incompatible with the basket's items.

Detaches a previously-applied CouponCode from the basket. Any discount the coupon was contributing is reversed and the totals are recalculated.

As with POST /shop/basket/{basketId}/coupons, customer-facing flows can only remove coupons while the basket is in_progress; staff (authenticated as a User) need the reservations.manage permission for the site.

Attaches a Customer to the basket so the resulting Order is correctly attributed and surfaced in the customer's history. There are three modes:

1. Authenticated customer — the request is authenticated as a Customer for the basket's brand. The authenticated customer is linked directly. If they don't have a phone number on file, supply one with phone (and optionally phone_country).
2. Existing customer by email — pass email, first_name, last_name, and optionally phone. If a customer with that email already exists for the brand they are linked; otherwise a new Customer is created using these details.
3. Guest checkout — the same payload as mode 2 is used; the newly-created customer is linked to the basket and saved against any marketing preferences supplied.

Phone numbers are normalised to E.164 using phone_country (or the site's country code) as the default region.

Applies one of the customer's outstanding CustomerCredit balances against the basket. Customer credits are issued by operators as compensation, refunds-to-store-credit, or loyalty rewards; once applied to a basket they reduce the outstanding payment amount immediately.

Returns 400 Bad Request if the credit can't be redeemed — for example because it's been fully spent, has expired, or doesn't belong to the basket's customer.

Detaches a previously-applied CustomerCredit from the basket. The credit's balance is restored to the customer and the basket's outstanding payment amount is recalculated.

This endpoint returns the link which the customer should go to in order to fill out the intake form for the basket.

Updates the schedule and/or quantity of an existing BasketItem. Passing quantity: 0 removes the item from the basket — useful for quantity steppers in cart UIs.

The item_configuration field accepts an arbitrary object of offering-specific options (e.g. session_id for a fitness session, room_id for a treatment, flavour for a product). Availability is re-checked on every update; if the new date/time isn't bookable the response is 400 Bad Request.

Removes a BasketItem from the basket. Any package items, guest assignments, and option budgets attached to the line are discarded. Reserved availability for the item is released immediately.

Adds a child item to a package line item. Packages bundle several offerings together (e.g. a "Spa Day" comprising a treatment, lunch, and pool access). The choice_id selects which slot within the package is being filled and option_id selects which offering fills it.

For scheduled package slots, pass item_configuration with time, duration, and (where relevant) session_id so the underlying availability check has the data it needs. Top-level time and duration parameters are accepted as a legacy alternative and will be merged into the configuration server-side.

Updates the choice/option selection or schedule of a package's child item. Useful when a customer changes their mind about which treatment to take in a "Choose your own" package slot, or needs to shift the slot's start time.

Availability is re-checked on every update.

Removes a child item from a package line. Any subsequent package items that depended on this slot (e.g. a follow-on treatment scheduled relative to it) may be removed too.

Attaches a payment intent or completed payment to the basket. Most commonly used to register a voucher or external-voucher payment alongside (or instead of) a card payment.

Behaviour depends on processor:

• voucher / external_voucher — redeems the supplied voucher against the basket immediately. The amount defaults to the outstanding submit amount when omitted; supplying a smaller amount lets a customer split-pay across multiple methods.
• stripe — accepted for compatibility but treated as a no-op: Stripe payments are added automatically after the customer returns from the Stripe Checkout flow.

Returns 400 Bad Request when the amount exceeds what's outstanding, when the chosen processor is misconfigured, or when the payment can't be created (e.g. voucher already spent).

Detaches a Payment from the basket. Any voucher balance the payment was consuming is released back to the voucher, and the basket's outstanding submit amount is recalculated.

Only valid while the basket is updatable — submitted baskets return 400 Bad Request.

Runs the same validation suite that POST /shop/basket/{basketId}/submit runs — checking availability, customer details, payment requirements, and integration pre-conditions — without committing the basket. The response is the latest basket payload, with any validation failures surfaced via the submit_errors collection.

Call this immediately before the customer enters payment details so you can fail fast and avoid taking money for a basket that's going to be rejected on submit.

Returns 400 Bad Request if the basket can't even reach the payment step (e.g. an item is unavailable or a payment processor error occurred during pre-flight).

Soft-holds availability for every item in the basket so the customer can complete payment without losing their slot. Reserved items expire after a short window (the response's items_reserved_until indicates the deadline) and are automatically released if the basket isn't submitted in time.

A customer must be attached to the basket (POST /shop/basket/{basketId}/customer) before items can be reserved — call this immediately before sending the customer to the payment step.

Returns 400 Bad Request if one or more items have become unavailable since they were added; the response message identifies the conflict.

Finalises the basket and turns it into an Order. On success the basket transitions to submitted, an Order is created, appointments and area bookings are confirmed (or queued as enquiries depending on configuration), payments are captured or authorised, and confirmation email + SMS are sent to the customer.

The endpoint is idempotent within a one-hour window for already submitted baskets — a re-submit returns the existing basket with the intake-form URL attached. Beyond the window, submitted baskets respond 404 Not Found.

You can optionally include customer_id or email (and the other guest-checkout fields) directly in the submit payload to set the customer in the same request — this delegates to the same logic as POST /shop/basket/{basketId}/customer.

Returns 400 Bad Request for any submit-time failure: unavailable items, validation errors, payment failures, or a lock timeout when another concurrent submit is in progress.

Replaces or upserts the basket's guest list in one call. Each entry can carry an id to update an existing guest in-place, or omit id to create a new guest. Pre-existing guests not referenced in the payload are left untouched.

Use this after collecting guest details on a multi-guest booking journey — it's cheaper than issuing one mutation per guest and keeps the basket's totals consistent.

Redeems a VoucherCode against the basket as a payment method. Trybe-issued vouchers carry a remaining balance and are partially or fully applied to the basket total; external vouchers (from a third-party voucher integration) are validated with the provider and held against the basket until submit.

Returns 400 Bad Request if the voucher can't be redeemed (e.g. wrong site, expired, already fully spent, or the third-party provider returned an error).

Detaches a previously-applied VoucherCode from the basket. Any balance the voucher was contributing is released back to the voucher and basket totals are recalculated.

Returns a curated list of retail Products to offer to the customer during checkout. Selection is driven by the current basket contents: a product appears here if it is configured as a cross-sell on any of the basket's existing line items.

The intended consumer is the storefront's "you may also like" panel on the checkout screen. The list is unpaginated and site-scoped to the basket's site.

Creates a new basket for the membership purchase and produces the Membership against the given customer. Use this when the storefront has already collected the membership type, rate and target customer and you want to skip straight to a payment-ready basket.

The returned Membership will be in reserved state — call the customer-side confirmMembership endpoint once the basket is paid to activate it.