Booking Flow

Orders

An Order is the record of a completed purchase — items, guests, payments, vouchers, refunds. Orders normally arrive here by being submitted through a Basket, which runs the booking-engine validation suite (availability, reservation policies, deposits, intake forms) and reserves the bookings server-side.

The endpoints in this section behave like the basket endpoints in shape but are designed for internal callers producing or adjusting orders directly, bypassing the booking-engine validation. Use them to backfill a historical sale, record an off-platform booking, fix up a customer's order after the fact, or refund / re-charge against a previously-submitted order.

The basket id (when there was one) is preserved on the order as basket_id so you can trace either way. See Basket vs Order in the basket-and-checkout guide for the contrast end-to-end.

The Order object

Attributes

{
  "id": "64a9f3b2c3d8e1f4a5b6c7d8",
  "applied_promo_code": "string",
  "applied_promo_code_discount_total": 1,
  "applied_promo_code_id": "64a9f3b2c3d8e1f4a5b6c7d8",
  "booking_items": [
    {
      "id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "added_by_customer": false,
      "base_price": 1,
      "booking_reserved_until": "2026-01-15T09:30:00+00:00",
      "booking_summary": "string",
      "date": "2026-01-15",
      "discount_amount": 1,
      "discounts": [
        "string"
      ],
      "exclusive_tax_amount": 1,
      "guest": "string",
      "guests": [
        "string"
      ],
      "inclusive_tax_amount": 1,
      "is_modifiable": true,
      "item_type": "appointment",
      "net_total": 1,
      "order_discount_amount": 1,
      "price": 1,
      "sold_by": {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "Alex Morgan",
        "type": "practitioner"
      },
      "status": "cancelled",
      "total_cost": 1,
      "type_id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "type_name": "string",
      "type_product_code": "string",
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "booking_items_end_date": "2026-01-15",
  "booking_items_start_date": "2026-01-15",
  "booking_items_span_multiple_days": false,
  "coupon_codes": [
    {
      "id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "code": "FIVEOFF",
      "customer_credit_id": "00000000-0000-0000-0000-000000000000",
      "description": "Get 10% off all treatments booked in April.",
      "issued_by_id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "issued_by_type": "credit",
      "name": "April special"
    }
  ],
  "currency": "GBP",
  "customer_id": "00000000-0000-0000-0000-000000000000",
  "customer_tax_details": {
    "legal_name": "Jane Jones",
    "tax_id": "GB1234567",
    "address_line_1": "1 Davey Street",
    "address_line_2": "Clapham",
    "city": "London",
    "postcode": "SW4 1AA",
    "country": "United Kingdom"
  },
  "discount_total": 100,
  "discounts": [
    {
      "id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "amount_type": "monetary",
      "applicable_for": "app_and_booking_engine",
      "applied_at": "2026-01-15T09:30:00+00:00",
      "applied_by": {},
      "calculated_amount": 150,
      "coupon": "string",
      "coupon_code_id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "currency": "GBP",
      "discount_amount": 15,
      "discount_type_code": "SUMMER23",
      "reason_code": "general",
      "site_id": "00000000-0000-0000-0000-000000000000"
    }
  ],
  "email": "janedoe@example.com",
  "external_ids": [
    {
      "key": "pms_id",
      "name": "PMS ID",
      "value": "pms_1234"
    }
  ],
  "external_ref": "ABC-123",
  "external_visit_ref": "RES1234",
  "first_name": "Jane",
  "guests": [
    "string"
  ],
  "intake_form_required": true,
  "intake_form_url": "https://demo.try.be/intake-form",
  "intake_forms_complete": true,
  "integration_config_id": "5f344d756e7f2e7d3f2e4b82",
  "is_customer_required": true,
  "is_locked": false,
  "is_promo_code_discount_applied": true,
  "items": [
    {
      "id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "added_by_customer": false,
      "base_price": 595,
      "basket_id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "booking_summary": {
        "id": "64a9f3b2c3d8e1f4a5b6c7d8",
        "area_ids": [
          "64a9f3b2c3d8e1f4a5b6c7d8"
        ],
        "areas": [
          "string"
        ],
        "duration": 1,
        "end_time": "2026-01-15T09:30:00+00:00",
        "offering": "string",
        "start_time": "2026-01-15T09:30:00+00:00",
        "status": "string",
        "created_at": "string",
        "updated_at": "string"
      },
      "discount_amount": 595,
      "discounts": [
        "string"
      ],
      "exclusive_tax_amount": 0,
      "guests": [
        {
          "id": "64a9f3b2c3d8e1f4a5b6c7d8",
          "customer_id": "64a9f3b2c3d8e1f4a5b6c7d8",
          "name": "Jane Smith",
          "checked_in_at": "2025-10-01T12:00:00+00:00"
        }
      ],
      "has_posted": true,
      "inclusive_tax_amount": 49,
      "item_configuration": "string",
      "last_post_attempt": "2026-01-15T09:30:00+00:00",
      "offering": {
        "id": "64a9f3b2c3d8e1f4a5b6c7d8",
        "name": "30 Minute Massage",
        "type": "string",
        "product_code": "string"
      },
      "option_budgets": [
        "string"
      ],
      "order_discount_amount": 1,
      "package_items": [
        "string"
      ],
      "posted_at": "2026-01-15T09:30:00+00:00",
      "price": 595,
      "purchasable_details": {
        "id": "64a9f3b2c3d8e1f4a5b6c7d8",
        "time_from": "2026-01-15T09:30:00+00:00",
        "time_to": "2026-01-15T09:30:00+00:00"
      },
      "quantity": 1,
      "reserved_until": "2026-01-15T09:30:00+00:00",
      "sold_by": "string",
      "status": "cancelled",
      "total_cost": 595,
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "items_status": "confirmed",
  "labels": [
    {
      "id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "color": "#FF0000",
      "name": "VIP",
      "order_id": "64a9f3b2c3d8e1f4a5b6c7d8"
    }
  ],
  "last_name": "Doe",
  "locked_at": "2019-01-15T12:00:00+01:00",
  "net_total": 8000,
  "order_ref": "TRY00",
  "organisation_id": "00000000-0000-0000-0000-000000000000",
  "outstanding_payment_amount": 1,
  "package_items": [
    {
      "id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "added_by_customer": false,
      "base_price": 1,
      "date": "2026-01-15",
      "discount_amount": 1,
      "discounts": [
        "string"
      ],
      "exclusive_tax_amount": 1,
      "guest": "string",
      "guests": [
        "string"
      ],
      "inclusive_tax_amount": 1,
      "integration_booking_engine": "Guestline",
      "is_modifiable": true,
      "item_type": "package",
      "net_total": 1,
      "option_budgets": [
        "string"
      ],
      "order_discount_amount": 1,
      "package_items": [
        {
          "id": "64a9f3b2c3d8e1f4a5b6c7d8",
          "booking_summary": "string",
          "choice_id": "64a9f3b2c3d8e1f4a5b6c7d8",
          "duration": 1,
          "guests": [
            "string"
          ],
          "item_configuration": "string",
          "offering_id": "64a9f3b2c3d8e1f4a5b6c7d8",
          "offering_name": "string",
          "offering_type": "string",
          "option_id": "64a9f3b2c3d8e1f4a5b6c7d8",
          "price_change": 1,
          "reserved_until": "2026-01-15T09:30:00+00:00",
          "shared_basket_item_id": "64a9f3b2c3d8e1f4a5b6c7d8",
          "status": "string",
          "time": "14:00"
        }
      ],
      "price": 1,
      "sold_by": "string",
      "status": "cancelled",
      "total_cost": 1,
      "type_id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "type_name": "string",
      "type_product_code": "string",
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "payment_totals": {
    "chargeable": 500,
    "missing": 1000,
    "paid": 750,
    "pending": 250,
    "provided": 1500,
    "unpaid": 1000
  },
  "payments": [
    "string"
  ],
  "phone": "+447727123456",
  "post_to_room_config": "string",
  "promo_code_applied_at": "2026-01-15T09:30:00+00:00",
  "promo_code_applied_by": "string",
  "purchase_items": [
    {
      "id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "added_by_customer": false,
      "base_price": 1,
      "discount_amount": 1,
      "discounts": [
        "string"
      ],
      "exclusive_tax_amount": 1,
      "guests": [
        "string"
      ],
      "inclusive_tax_amount": 1,
      "is_modifiable": true,
      "item_configuration": "string",
      "item_type": "product",
      "net_total": 1,
      "order_discount_amount": 1,
      "purchasable_details": {
        "id": "64a9f3b2c3d8e1f4a5b6c7d8"
      },
      "quantity": 1,
      "reserved_until": "2026-01-15T09:30:00+00:00",
      "sold_by": "string",
      "status": "cancelled",
      "total_cost": 1,
      "type_id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "type_name": "string",
      "type_product_code": "string",
      "unit_price": 1,
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "sales_channel": {
    "id": "64a9f3b2c3d8e1f4a5b6c7d8",
    "name": "Web",
    "organisation_id": "00000000-0000-0000-0000-000000000000"
  },
  "service_charge": {
    "amount": 1000,
    "item_amounts": [
      {
        "amount": 1000,
        "item_id": "64a9f3b2c3d8e1f4a5b6c7d8",
        "percentage": 10
      }
    ],
    "percentage": 10
  },
  "site_id": "00000000-0000-0000-0000-000000000000",
  "special_requests": "I would like the Blue Room please",
  "stage": "not_arrived",
  "status": "submitted",
  "submit_auth_amount": 1,
  "submit_payment_amount": 1,
  "submitted_at": "2020-02-24T12:00:00+01:00",
  "submitted_by": "string",
  "taxes": [
    {
      "amount": 1290,
      "inclusive": false,
      "name": "VAT",
      "percentage": 20
    }
  ],
  "tip_amount": 1050,
  "tips": [
    {
      "id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "amount": 1050,
      "declined": false,
      "updated_at": "2026-01-15T09:30:00+00:00",
      "can_remove": false
    }
  ],
  "total_cost": 1,
  "total_paid_or_authed": 1,
  "total_tax": 2000,
  "totals": {
    "exclusive_tax": 0,
    "inclusive_tax": 250,
    "order_discount": 11000,
    "subtotal": 12000,
    "subtotal_without_exclusive_tax": 12000,
    "total": 10000
  },
  "visit": {
    "id": "64a9f3b2c3d8e1f4a5b6c7d8",
    "visit_ref": "EXT-12345",
    "visit_type": {
      "id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "name": "Stay"
    },
    "status": "string",
    "arrival_date": "2026-01-15T09:30:00+00:00",
    "departure_date": "2026-01-15T09:30:00+00:00",
    "first_name": "Alex",
    "last_name": "Morgan"
  },
  "voucher_codes": [
    "string"
  ],
  "created_at": "2020-02-24T12:00:00+01:00",
  "updated_at": "2020-02-24T12:00:00+01:00"
}
get/shop/orders

Retrieve all orders matching the given parameters

listOrders

Use this endpoint to retrieve orders

Query parameters

  • querystringoptional

    The query to filter orders on.

  • customer_iduuidoptional

    The customer ID to filter orders on.

  • statusstringoptional

    The status to filter orders on.

  • labelsstringoptional

    The labels to filter orders on.

  • item_offering_idstringoptional

    A comma separated string of offering ids to fetch orders for

  • item_offering_typestringoptional

    Filter orders by the type of offering for their items.

    Possible values:appointmentappointment_enquiryarea_bookingcoursehotel_room_reservationmembershippackageproductsessiontable_reservationvoucher
  • submitted_by_idstringoptional

    A comma separated string of user ids to fetch orders for

  • revenue_date_fromdateoptional

    Filter on orders with a revenue date on or after this date.

  • revenue_date_todateoptional

    Filter on orders with a revenue date on or before this date.

  • item_datedateoptional

    Filter on orders with an items on this date.

  • item_date_fromdate-timeoptional

    Filter on orders with an item date on or after this date.

  • item_date_todate-timeoptional

    Filter on orders with an item date on or before this date.

  • item_statusstringoptional

    Filter on orders with an item status of one of these comma-separated values.

  • submitted_at_fromdate-timeoptional

    Filter on orders with a submitted date on or after this time.

  • submitted_at_todate-timeoptional

    Filter on orders with a submitted date before this date.

  • updated_at_fromdate-timeoptional

    Filter on orders with a updated date on or after this date.

  • updated_at_todate-timeoptional

    Filter on orders with a updated date before this date.

  • is_membershipbooleanoptional

    Filter on orders that contain a membership purchase

  • has_outstanding_balancebooleanoptional

    Filters on orders that have an outstanding balance

  • sales_channelobject-idoptional

    Filter on orders that have the given sales channel ID

  • external_idstringoptional

    Filter on an external ID, in the format {key}:{value}

  • generic_items_arraybooleanoptional

    Pass true to return a single 'items' array rather than separate arrays for each item type

  • site_idstringoptional

    Filter results by the site they belong to

  • pageintegeroptional

    The page to retrieve results from

  • per_pageintegeroptional

    The number of results to return per page

Responses

  • 200

    The Orders were successfully retrieved

  • 401

    The user is unauthenticated

post/shop/orders

Create a new order

createOrder

Create a new order in the new or in_progress state. An order is the server-side representation of a basket — items, guests, discounts, payments and so on hang off it via the sub-resources documented under /shop/orders/{orderId}/*. The freshly created order is empty: callers typically follow this call with one or more POST /shop/orders/{orderId}/items requests and finally POST /shop/orders/{orderId}/submit to convert the order from a basket into a confirmed sale.

The site_id is required and must be a site the caller has permission to create orders for. If customer_id is provided, the customer is attached to the order immediately — equivalent to a follow-up call to POST /shop/orders/{orderId}/customer. external_ref and external_ids capture identifiers from the calling system (e.g. a PMS reservation reference) so the order can be reconciled later.

Request body

  • site_iduuidrequired

    The site the order belongs to. Must be a site the calling user has permission to manage reservations for.

  • statusstringoptional

    The initial status of the order. new is the default; use in_progress to flag the order as actively being worked on by a member of staff (this distinction is useful for live dashboards and concurrency reporting).

    Possible values:newin_progress
  • customer_idstringoptionalnullable

    Optional ID of the customer to attach to the order at creation time. If omitted, the order starts unassociated and a customer can be attached later via POST /shop/orders/{orderId}/customer.

  • external_refstringoptional

    A free-form reference from the calling system — for example a PMS reservation code. Stored verbatim on the order; not interpreted by Trybe.

  • external_idsobject[]optional

    Structured external identifiers to attach to the order. Each entry maps an ExternalIdType (looked up by key) to a value. The key must reference an external ID type that exists for the site (or applies to all sites) and is scoped to the Basket model.

  • partner_idstringoptionalnullable

    Registered partner that originated this order. Used for reporting and revenue allocation when orders arrive via a third-party booking partner; must match one of the configured PartnerConfig IDs on this organisation.

  • sales_channel_idstringoptionalnullable

    The sales channel to attribute the order to. Must reference a sales channel that belongs to the order's organisation.

Responses

  • 201

    The Order was successfully retrieved

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 422

    The request didn't pass validation

get/shop/orders/queue

Queue an export of the orders list

actionQueueOrdersList

Queue a request to export the orders list

Query parameters

  • querystringoptional

    The query to filter orders on.

  • customer_iduuidoptional

    The customer ID to filter orders on.

  • statusstringoptional

    The status to filter orders on.

  • labelsstringoptional

    The labels to filter orders on.

  • item_offering_idstringoptional

    A comma separated string of offering ids to fetch orders for

  • submitted_by_idstringoptional

    A comma separated string of user ids to fetch orders for

  • revenue_date_fromdateoptional

    Filter on orders with a revenue date on or after this date.

  • revenue_date_todateoptional

    Filter on orders with a revenue date on or before this date.

  • item_datedateoptional

    Filter on orders with an items on this date.

  • item_date_fromdate-timeoptional

    Filter on orders with an item date on or after this date.

  • item_date_todate-timeoptional

    Filter on orders with an item date on or before this date.

  • item_statusstringoptional

    Filter on orders with an item status of one of these comma-separated values.

  • submitted_at_fromdate-timeoptional

    Filter on orders with a submitted date on or after this time.

  • submitted_at_todate-timeoptional

    Filter on orders with a submitted date before this date.

  • updated_at_fromdate-timeoptional

    Filter on orders with a updated date on or after this date.

  • updated_at_todate-timeoptional

    Filter on orders with a updated date before this date.

  • is_membershipbooleanoptional

    Filter on orders that contain a membership purchase

  • has_outstanding_balancebooleanoptional

    Filters on orders that have an outstanding balance

  • sales_channelobject-idoptional

    Filter on orders that have the given sales channel ID

  • external_idstringoptional

    Filter on an external ID, in the format {key}:{value}

  • site_idstringoptional

    Filter results by the site they belong to

Responses

  • 200

    The job was successfully queued

  • 401

    The user is unauthenticated

get/shop/orders/{orderId}

Retrieve a single order

getOrder

Use this endpoint to retrieve a single orders

Path parameters

  • orderIduuidrequired

    The ID of the order

Query parameters

  • generic_items_arraybooleanoptional

    Pass true to return a single 'items' array rather than separate arrays for each item type

Responses

  • 200

    The Order was successfully retrieved

  • 401

    The user is unauthenticated

  • 404

    The resource couldn't be found

put/shop/orders/{orderId}

Update an order

updateOrder

Update mutable fields on an existing order. Used for in-progress edits — attaching or swapping a customer, recording contact details against the order, advancing the basket stage, and so on.

customer_id is interpreted specially. Passing a string ID attaches that customer to the order (subject to availability and brand checks); passing null removes the current customer.

If stage is the only field supplied, the order takes a fast path that just records the new stage and returns — useful for keeping live dashboards in sync without re-running the full update pipeline.

metadata uses merge semantics: existing keys not mentioned in the request stay in place, keys passed with a value are upserted, and keys passed with null are removed.

special_requests is writable only by users that hold the SETTINGS_MANAGE permission; for everyone else the field is silently dropped before validation.

Path parameters

  • orderIduuidrequired

    The ID of the order

Request body

  • customer_idstringoptionalnullable

    Attach or detach a customer. Pass a customer ID to set the order's customer; pass null to remove the current customer. The customer must belong to the same brand as the order's site.

  • sales_channel_idstringoptionalnullable

    The sales channel to attribute the order to.

  • first_namestringoptional

    First name to record against the order. When set, this also copies through to the lead-booker guest (if one exists) so the order header and the lead guest stay in sync.

  • last_namestringoptional

    Last name to record against the order.

  • emailemailoptional

    Email address to record against the order. Must be a syntactically valid address.

  • phonestringoptionalnullable

    International phone number for the order. Validated and normalised against the site's country code; stored in E.164 format.

  • integration_config_idstringoptionalnullable

    Optional reference to an IntegrationConfig that scopes this order to a specific integration on the site (for example a PMS connector). Must reference a config that belongs to the same site.

  • stagestringoptional

    The current basket/order stage. Stages model the user-facing checkout flow (e.g. customer_details, payment, confirmation) and are surfaced to operators. When the only field supplied is stage, the order is updated as a lightweight stage transition without running the full update pipeline.

  • external_refstringoptional

    Free-form reference from the calling system. Stored verbatim on the order.

  • metadataobjectoptional

    Arbitrary string-to-string metadata to merge into the order. Keys map to string values up to 1,000 characters; passing null for a value removes that key. Existing metadata not mentioned in the request is left in place (merge semantics, not replace).

  • special_requestsstringoptionalnullable

    Operator-facing notes captured against the order. Only writable by users with the SETTINGS_MANAGE permission; omitted from the request body for everyone else.

Responses

  • 200

    The Order was successfully retrieved

  • 400

    The request failed.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

delete/shop/orders/{orderId}

Cancel an order

deleteOrder

Cancels the order. Each line item is cancelled in turn — bookings (appointments, area bookings, sessions, table reservations) are cancelled and any held resources released; purchases (vouchers, memberships, retail products) are voided; and any package items follow the cancellation rules of their underlying components. Payments remain attached to the order so they can be refunded separately via POST /shop/orders/{orderId}/payments/{paymentId} or absorbed into a credit note.

The cancellation is reversible for a short window via POST /shop/orders/{orderId}/restore; once the order has aged past that window or been settled, the only path back is to create a fresh order.

Path parameters

  • orderIduuidrequired

    The ID of the order

Responses

  • 204

    The order was cancelled successfully.

  • 400

    The request failed.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

post/shop/orders/{orderId}/restore

Restore a cancelled order

restoreOrder

Un-cancels a previously cancelled Order. The order returns to its pre-cancellation state — its items become live again, line-item payments and discounts persist, and any associated visits/bookings are re-activated. Permissions: requires the caller to have the cancel ability on the order (the same permission used to cancel in the first place).

Use case: cancellation-by-mistake, customer change of mind shortly after cancellation, or a billing system mis-cancel that needs to be undone before the customer notices. For long-cancelled orders use the OrderService directly — restore expects a recent cancellation.

Path parameters

  • orderIduuidrequired

    The ID of the order

Responses

  • 200

    The order was restored successfully.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

post/shop/orders/{orderId}/print-pos-receipt

Print POS receipt

actionPrintPosReceiptForOrder

Use this endpoint to print a summary of the given order to an Esc/Pos printer connected to Trybe via a EscPosConnector.

Path parameters

  • orderIduuidrequired

    The ID of the order

Request body

  • esc_pos_connector_iduuidrequired

    Identifier of the EscPosConnector (receipt printer) to send the rendered receipt to. The connector must belong to the same site as the order.

  • guest_input_fieldsobjectoptional

    The fields to include on the receipt for the guest to fill out.

  • previewbooleanoptional

    Whether to return a preview of the printed receipt in the response.

Responses

  • 200

    Response schema for printing a POS receipt for an order

  • 404

    The resource couldn't be found

get/shop/orders/{orderId}/payments

Get all payments for an order

listOrderPayments

Use this endpoint to retrieve all the payments made for an order.

Path parameters

  • orderIduuidrequired

    The ID of the order

Responses

  • 200

    A list of payments made for an order

  • 401

    The user is unauthenticated

  • 404

    The resource couldn't be found

post/shop/orders/{orderId}/payments

Add a payment to an order

createOrderPayment

Record a payment against an order. Use this endpoint to attach a manual payment — for example a cash payment taken at the front desk, a bank transfer that has cleared, or a card transaction taken via a terminal that is not integrated with Trybe.

The amount must be greater than zero, expressed in the lowest denomination of the order's currency (pennies for GBP, cents for USD, and so on). The created payment is returned in the data envelope along with its assigned id, status, and refundable amount.

Returns 400 Bad Request if the payment can't be added — for example because the amount exceeds the outstanding balance, or the order is in a state that no longer accepts new payments.

Path parameters

  • orderIduuidrequired

    The ID of the order

Request body

  • amountintegerrequired

    The amount of the payment, expressed in the lowest denomination of the order's currency (e.g. pennies for GBP, cents for USD). Must be greater than zero unless capture_method is on_demand and the request is being used to store a payment method for later charging — in which case 0 is also accepted.

  • capture_methodstringoptionalnullable

    When the payment amount should be captured. Use automatic for an immediate capture (the default for most manual entries) or on_demand when storing a payment method to be charged later.

  • details_sourcestringoptionalnullable

    How the payment method will be supplied — for example pay_by_link for a hosted checkout link, or terminal for an in-person card terminal.

  • processor_dataobjectoptional

    An optional dictionary of processor-specific data. For on_demand payments this can include save_payment_method: true to persist the payment method against the customer for future use.

Responses

  • 201

    A single payment recorded against an order.

  • 400

    The request failed.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

get/shop/orders/{orderId}/payments/{paymentId}

Retrieve a payment for an order

getOrderPayment

Use this endpoint to retrieve a single payment recorded against an order. The response includes the payment's current status, refundable amount, and any associated refunds or chargebacks — useful for reconciling the order's outstanding balance or surfacing payment details in a back-office view.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • paymentIdobject-idrequired

    The ID of the payment.

Responses

  • 200

    A single payment recorded against an order.

  • 404

    The resource couldn't be found

delete/shop/orders/{orderId}/payments/{paymentId}

Remove a payment from an order

deleteOrderPayment

Remove a payment that has not yet been completed. Only payments that are still pending or that exist solely to store a payment method (payment_method_stored) can be removed — completed, captured, or refunded payments must be reversed via a refund instead.

Returns 400 Bad Request if the payment is in a state that cannot be removed. On success the updated Order is returned with the payment no longer attached.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • paymentIdobject-idrequired

    The ID of the payment.

Responses

  • 200

    The Order was successfully retrieved

  • 400

    The request failed.

  • 404

    The resource couldn't be found

post/shop/orders/{orderId}/posting-room

Attach a posting room from an order

actionAttachPostingRoomToOrder

Use this endpoint to attach a posting room to an order.

Path parameters

  • orderIduuidrequired

    The ID of the order

Request body

  • posting_room_dataobjectrequired

    Free-form key/value bag identifying the PMS folio that charges from this order should be posted to. The exact shape depends on the PMS in use (e.g. Opera, Cloudbeds); Trybe forwards the data verbatim to the integration. Use null to detach a previously-attached posting room.

Responses

  • 200

    The PostingRoom was successfully associated to the Order

  • 404

    The resource couldn't be found

delete/shop/orders/{orderId}/posting-room

Detach a posting room from an order

actionDetachPostingRoomToOrder

Use this endpoint to detach a posting room to an order.

Path parameters

  • orderIduuidrequired

    The ID of the order

Responses

  • 204

    The posting room was successfully detached from the order.

  • 404

    The resource couldn't be found

post/shop/orders/{orderId}/discounts

Apply a discount to an order

createDiscountForOrder

Use this endpoint to apply the discount from a DiscountType to an order.

Path parameters

  • orderIduuidrequired

    The ID of the order

Request body

  • discount_type_codestringrequired

    The code for the DiscountType. If the code exists, the discount will be applied. If not, an error will be returned.

  • discount_amountintegerrequired

    The value of the discount to be applied when a DiscountType is applied. If this is for a customisable in-app discount type, this will be able to be changed before being applied.

  • amount_typestringoptional

    The type of discount. For a promo code, this will always be a percentage.

    Possible values:monetarypercentage
  • reason_codestringoptional

    The code for the reason the discount was applied.

    Possible values:coupongeneralpredefinedvoucher_difference

Responses

  • 201

    The OrderDiscount was successfully applied.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

delete/shop/orders/{orderId}/discounts/{discountId}

Remove a discount from an order

deleteOrderDiscount

This endpoint deletes a Discount by ID from an order.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • discountIduuidrequired

    The ID of the order discount

Responses

  • 204

    The order discount was successfully deleted.

  • 404

    The resource couldn't be found

get/shop/orders/{orderId}/emails

List the emails sent for an order

listOrderEmails

Retrieve a paginated list of every email message that has been sent in relation to an order. Each entry includes delivery, open and bounce status; use Retrieve an order email to fetch the rendered HTML body for an individual message.

Path parameters

  • orderIduuidrequired

    The ID of the order

Query parameters

  • pageintegeroptional

    The page to retrieve results from

  • per_pageintegeroptional

    The number of results to return per page

Responses

  • 200

    The email messages for the order were successfully retrieved.

  • 404

    The resource couldn't be found

post/shop/orders/{orderId}/emails

Send an email for an order

createOrderEmail

Send an email to the customer for an order. The type field selects which templated mailable is rendered — for example BookingConfirmation or BookingReminder. The list of available types is determined by the mailables configured in the application.

To render the email without actually sending it, use the Preview an order email endpoint instead.

Path parameters

  • orderIduuidrequired

    The ID of the order

Request body

  • typestringrequired

    The mailable type to send. This selects the underlying template; available types depend on the organisation's configured mailables.

  • contentstringoptional

    Optional custom message body to inject into the template. HTML is not permitted — submit plain text only.

  • paramsobjectoptional

    Additional template parameters to pass through to the mailable — the available keys depend on the chosen type.

Responses

  • 201

    The email message was successfully sent.

  • 400

    The request failed.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

post/shop/orders/{orderId}/emails/preview

Preview an order email

createOrderEmailPreview

Render an email for an order without actually sending it. Useful for showing users a preview of the message that will be sent — for example in the order detail UI before confirming a manual send.

Path parameters

  • orderIduuidrequired

    The ID of the order

Request body

  • typestringrequired

    The mailable type to preview.

  • contentstringoptional

    Optional custom message body to inject into the template. HTML is not permitted — submit plain text only.

  • paramsobjectoptional

    Additional template parameters to pass through to the mailable — the available keys depend on the chosen type.

Responses

  • 200

    The email message was successfully retrieved.

  • 400

    The request failed.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

get/shop/orders/{orderId}/emails/{emailId}

Retrieve an order email

getOrderEmail

Retrieve the full rendered email message — including its HTML body — that was sent for an order. To get just the summary metadata for every email on the order, use List the emails sent for an order instead.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • emailIdobject-idrequired

    The ID of the email message.

Responses

  • 200

    The email message was successfully retrieved.

  • 404

    The resource couldn't be found

delete/shop/orders/{orderId}/emails/{emailId}

Delete an order email

deleteOrderEmail

Remove the local record of an email message from the order. This does not recall the underlying email from the customer's inbox.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • emailIdobject-idrequired

    The ID of the email message.

Responses

  • 204

    The email message record was successfully deleted.

  • 404

    The resource couldn't be found

put/shop/orders/{orderId}/external-ids

Update an order's external IDs

updateOrderExternalIds

Use this endpoint to update one or more of an order's external IDs

Path parameters

  • orderIduuidrequired

    The ID of the order

Request body

Responses

  • 200

    Contains details of the external IDs applied to an order.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

get/shop/orders/{orderId}/fiscal-receipts

Retrieve all fiscal receipts attached to an order.

listOrderFiscalReceipts

Retrieve all fiscal receipts attached to an order.

Path parameters

  • orderIduuidrequired

    The ID of the order

Responses

  • 200

    Contains an array of fiscal receipts relating to the order.

  • 401

    The user is unauthenticated

  • 404

    The resource couldn't be found

get/shop/orders/{orderId}/guests

List the guests on an order

listOrderGuests

Retrieve every guest attached to an order. The lead booker is the guest with is_lead_booker set to true — there is at most one lead booker per order.

Path parameters

  • orderIduuidrequired

    The ID of the order

Responses

  • 200

    The guests on the order were successfully retrieved.

  • 404

    The resource couldn't be found

post/shop/orders/{orderId}/guests

Add a guest to an order

createOrderGuest

Add a new guest to an order. If this is the first guest on the order, all existing items will be reassigned to the new guest and they will be marked as the lead booker by default.

If the order doesn't yet have a customer_id and the new guest is linked to a customer via customer_id, that customer is also set as the order's customer.

Path parameters

  • orderIduuidrequired

    The ID of the order

Request body

  • namestringoptional

    The guest's full name. Used when the site does not enforce separate first/last name fields. Optional if first_name/last_name are provided, if the guest is the lead booker, or if customer_id is set.

  • first_namestringoptional

    The guest's first name. Required when the site enforces separate first/last name fields.

  • last_namestringoptional

    The guest's last name. Required when the site enforces separate first/last name fields.

  • customer_iduuidoptional

    Identifier of an existing Customer to link this guest to. When provided, the guest's name and email are inherited from the customer record. Omit to create a guest-only entry without a linked customer account.

  • is_lead_bookerbooleanoptional

    Whether this guest is the lead booker for the order. Defaults to true when this is the first guest on the order, otherwise false.

Responses

  • 201

    The guest was successfully created or updated.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

put/shop/orders/{orderId}/guests/{guestId}

Update a guest on an order

updateOrderGuest

Update the details of a guest already attached to an order. Linking the guest to a customer via customer_id overwrites the guest's first_name, last_name, name and email with the customer's profile values, and transfers any existing visit intake form submission to that customer.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • guestIdobject-idrequired

    The ID of the guest on the order.

Request body

  • namestringoptional

    The guest's full name. Required if first_name and last_name are not provided.

  • first_namestringoptional

    The guest's first name. Required when the site enforces separate first/last name fields; otherwise required if name is not provided.

  • last_namestringoptional

    The guest's last name. Required when the site enforces separate first/last name fields; otherwise required if name is not provided.

  • customer_iduuidoptional

    Identifier of an existing Customer to link this guest to. The customer must belong to the same brand as the order's site; cross-brand links are rejected with 422.

Responses

  • 200

    The guest was successfully created or updated.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

delete/shop/orders/{orderId}/guests/{guestId}

Remove a guest from an order

deleteOrderGuest

Remove a guest from an order. Any items currently assigned to this guest are unassigned, and the order totals are recalculated.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • guestIdobject-idrequired

    The ID of the guest on the order.

Responses

  • 204

    The guest was successfully removed from the order.

  • 404

    The resource couldn't be found

post/shop/orders/{orderId}/items

Add an item to an order

createOrderItem

Use this endpoint to add an item to an existing order.

Path parameters

  • orderIduuidrequired

    The ID of the order

Request body

  • offering_typestringrequired

    Discriminator describing what kind of sellable item an Offering represents. The value determines which downstream schema (Appointment, Session, Package, etc.) the offering's offering_id resolves against, and which checkout/booking flow applies.

    Possible values:appointmentappointment_enquiryarea_bookingcoursehotel_room_reservationmembershippackageproductsessiontable_reservationvoucher
  • offering_idstringrequired

    Identifier of the offering to add as a line item, paired with offering_type to disambiguate which collection the ID belongs to (e.g. appointment, course, retail product). The offering must be sellable at the order's site and currently within its on-sale window.

  • sold_byobjectoptional

    The entity selling the offering.

  • quantityintegeroptional

    The quantity of the offering to add to the order.

  • guest_idsstring[]optional

    A list of guest IDs must be passed if you are not passing guests.

  • guestsobject[]optional

    A list of guest objects must be passed if you are not passing guest_ids.

    One of
  • practitioner_idsstring[]optionalDeprecated

    This field is deprecated and only maintained for legacy reasons, use item_configuration.practitioner_ids instead.

  • room_idsstring[]optionalDeprecated

    This field is deprecated and only maintained for legacy reasons, use item_configuration.room_ids instead.

  • equipment_idsstring[]optionalDeprecated

    This field is deprecated and only maintained for legacy reasons, use item_configuration.equipment_ids instead.

  • area_idsstring[]optionalDeprecated

    This field is deprecated and only maintained for legacy reasons, use item_configuration.area_ids instead.

  • skip_availability_checksbooleanoptionalDeprecated

    This field is deprecated and only maintained for legacy reasons, use item_configuration.skip_availability_checks instead.

  • timedate-timeoptionalDeprecated

    This field is deprecated and only maintained for legacy reasons, use item_configuration.time instead.

  • durationintegeroptionalDeprecated

    This field is deprecated and only maintained for legacy reasons, use item_configuration.duration instead.

  • item_configurationobjectoptional

Responses

  • 200

    Describes a line item within an order.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

put/shop/orders/{orderId}/items/{itemId}

Update an order item

updateOrderItem

Use this endpoint to update an item on an existing order. The fields you can update depend on the item's item_type — for bookings you can change the date, time, duration and resources (practitioner, room, equipment, area); for purchases you can change the quantity and any item-type specific configuration on item_configuration; for packages you can swap out package choices via package_items.

Most fields are optional — only the values you include in the payload are changed. If the requested change would breach availability rules a 400 response is returned unless the authenticated user has the reservations:override_rules permission and you pass skip_availability_checks=true.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • itemIduuidrequired

    The ID of the order item

Request body

  • datedateoptional

    The date the booking should be moved to, formatted as YYYY-MM-DD. Applicable to bookings (appointments, area bookings, sessions, table reservations) and to packages.

  • timestringoptionalnullable

    The local time the booking should start at, formatted as HH:MM. Pass null to clear the time for items whose booking is time-agnostic. Applicable to bookings and packages.

  • durationintegeroptional

    The new duration of the booking in minutes. Applicable to area bookings (and to appointments if the offering allows variable durations).

  • quantityintegeroptional

    The number of units of this item to include in the order. Most commonly used for retail products and vouchers; bookings are typically always 1.

  • room_idstringoptionalnullable

    Override the room the booking is held in. Pass null to clear an existing assignment and let the availability engine pick one on confirmation. Use item_configuration.room_id for new integrations; this top-level field is retained for backwards compatibility.

  • practitioner_idsstring[]optionalnullable

    The IDs of practitioners that should be assigned to this booking. Use item_configuration.practitioner_ids for new integrations; this top-level field is retained for backwards compatibility.

  • area_idsstring[]optionalnullable

    The IDs of areas that should be reserved for this booking. Required for area bookings, ignored for other item types. Use item_configuration.area_ids for new integrations; this top-level field is retained for backwards compatibility.

  • equipment_idsstring[]optionalnullable

    The IDs of equipment items that should be held for this booking. Use item_configuration.equipment_ids for new integrations; this top-level field is retained for backwards compatibility.

  • discount_amountintegeroptionalnullable

    A manual discount amount in minor units (e.g. pence, cents) to apply to this item. Only honoured when the authenticated user has the discounts:apply_manual permission on the order.

  • offering_typestringoptional

    Discriminator describing what kind of sellable item an Offering represents. The value determines which downstream schema (Appointment, Session, Package, etc.) the offering's offering_id resolves against, and which checkout/booking flow applies.

    Possible values:appointmentappointment_enquiryarea_bookingcoursehotel_room_reservationmembershippackageproductsessiontable_reservationvoucher
  • offering_idstringoptional

    The identifier of the offering to swap this item to. Combined with offering_type to disambiguate which collection the ID belongs to. Most commonly used to switch an appointment to a different appointment type or upgrade a session.

  • package_itemsobject[]optional

    The full list of choices for a package item. Pass the complete new set on every update — items omitted from this array are removed from the package.

  • item_configurationobjectoptional

    The new configuration for the item. This is the preferred place to set time, duration, resources and other item-type specific fields. The accepted keys mirror those documented for createOrderItem's item_configuration.

  • guest_idsstring[]optionalnullable

    The full list of guest IDs that should be associated with this item.

  • sold_byobjectoptionalnullable

    The staff member who should receive commission credit for this item. Pass null to clear the existing sold by attribution.

  • skip_availability_checksbooleanoptional

    When true, bypasses availability rules during the update. Requires the reservations:override_rules permission. Useful for back-office corrections where an item must be moved into a slot that would otherwise be unavailable.

Responses

  • 200

    Describes a line item within an order.

  • 400

    The request failed.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

delete/shop/orders/{orderId}/items/{itemId}

Remove an item from an order

deleteOrderItem

Use this endpoint to remove a line item from an order. If the item is a booking (appointment, area booking, session, table reservation) the underlying booking is cancelled and any held resources are released. The order's totals are recalculated immediately.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • itemIduuidrequired

    The ID of the order item

Responses

  • 204

    The item was successfully removed from the order.

  • 400

    The request failed.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

post/shop/orders/{orderId}/items/{itemId}/discounts

Apply a discount to an order item

createDiscountForOrderItem

Use this endpoint to apply the discount from a DiscountType to an order item.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • itemIduuidrequired

    The ID of the order item

Request body

  • discount_type_codestringrequired

    The code for the discount type. If the code exists, the discount will be applied.

  • applicable_forstringoptional

    Where this discount type is able to be applied.

    Possible values:app_onlyapp_and_booking_engine
  • discount_amountintegerrequired

    The value of the discount to be applied when a discount type is used. This can be used as a monetary or percentage value for an in-app discount type and is set to percentage for a promo code.

  • amount_typestringoptional

    The type of discount. For a promo code, this will always be a percentage.

    Possible values:monetarypercentage

Responses

  • 201

    The OrderItemDiscount was successfully applied.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

delete/shop/orders/{orderId}/items/{itemId}/discounts/{discountId}

Remove a discount from an order item

deleteItemDiscount

This endpoint deletes a Discount by ID from an order item.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • itemIduuidrequired

    The ID of the order item

  • discountIduuidrequired

    The ID of the order item discount

Responses

  • 204

    The item discount was successfully deleted.

  • 404

    The resource couldn't be found

put/shop/orders/{orderId}/items/{itemId}/sold-by

Update the 'sold by' staff member for an item

updateItemSoldBy

Use this endpoint to update the 'sold by' (commission) attribute for an order item.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • itemIduuidrequired

    The ID of the order item

Request body

  • sold_bymongo-idrequired

    The code for the discount type. If the code exists, the discount will be applied.

Responses

  • 201

    Describes a line item within an order.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

post/shop/orders/{orderId}/labels

Update the labels on an order

updateOrderLabels

Use this endpoint to replace all labels on an order with the given values.

Path parameters

  • orderIduuidrequired

    The ID of the order

Request body

  • labelsobject[]required

Responses

  • 201

    The Order was successfully retrieved

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

put/shop/orders/{orderId}/labels/{labelId}

Add a single label to an order

updateOrderLabel

Attaches the given Label to the order. If the label is already attached the request is a no-op and the endpoint still returns 201. The label must belong to the same site as the order — a 422 is returned otherwise. Use this endpoint when you want to incrementally add a label without replacing the order's full label set (use POST /shop/orders/{orderId}/labels for the replace-all behaviour).

Path parameters

  • orderIduuidrequired

    The ID of the order

  • labelIdobject-idrequired

    The ID of the label to add to or remove from the order.

Responses

  • 201

    The label that was attached to the order.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

delete/shop/orders/{orderId}/labels/{labelId}

Remove a single label from an order

deleteOrderLabel

Detaches the given Label from the order. If the label was not attached the request is a no-op. The label itself is not deleted — only its association with the order is removed.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • labelIdobject-idrequired

    The ID of the label to add to or remove from the order.

Responses

  • 204

    The label was successfully removed from the order.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

get/shop/orders/{orderId}/notes

List the notes on an order

listOrderNotes

Retrieve every internal note attached to an order, ordered oldest-first. Notes are typically used by front-of-house and operations staff to capture requests or context that doesn't belong on the order itself — for example "guest is celebrating an anniversary" or "double room requested".

Path parameters

  • orderIduuidrequired

    The ID of the order

Responses

  • 200

    The order notes were successfully retrieved.

  • 404

    The resource couldn't be found

post/shop/orders/{orderId}/notes

Add a note to an order

createOrderNote

Add a new note to an order. The note will be attributed to the authenticated user, who is recorded as the created_by user on the resulting OrderNote.

Path parameters

  • orderIduuidrequired

    The ID of the order

Request body

  • contentstringrequired

    The contents of the note. HTML is not permitted — submit plain text only. Use notes to capture operational context for the order (for example, special requests from the guest, or an internal note for the front desk).

Responses

  • 201

    The order note was successfully retrieved.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

get/shop/orders/{orderId}/notes/{noteId}

Retrieve an order note

getOrderNote

Retrieve a single note attached to an order.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • noteIdobject-idrequired

    The ID of the order note.

Responses

  • 200

    The order note was successfully retrieved.

  • 404

    The resource couldn't be found

put/shop/orders/{orderId}/notes/{noteId}

Update an order note

updateOrderNote

Replace the contents of an existing order note. The created_by user and created_at timestamp are preserved — only the body is updated.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • noteIdobject-idrequired

    The ID of the order note.

Request body

  • contentstringrequired

    The new contents of the note. HTML is not permitted — submit plain text only.

Responses

  • 200

    The order note was successfully retrieved.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

delete/shop/orders/{orderId}/notes/{noteId}

Delete an order note

deleteOrderNote

Permanently remove a note from an order. This action cannot be undone.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • noteIdobject-idrequired

    The ID of the order note.

Responses

  • 204

    The order note was successfully deleted.

  • 404

    The resource couldn't be found

delete/shop/orders/{orderId}/remove-promo-code/{discountTypeId}

Remove promo code

deletePromoCodeFromOrder

Use this endpoint to remove the applied DiscountType, when it is a promo code, from an order, as well as its associated discounts.

Path parameters

Responses

  • 204

    The applied promo code was successfully removed

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

put/shop/orders/{orderId}/service-charge

Update the service charge on an order

updateOrderServiceCharge

Use this endpoint to update the service charge applied to an order.

Path parameters

  • orderIduuidrequired

    The ID of the order

Request body

  • amountintegeroptional

    The amount of service charge, in minor units. Required if item_amounts isn't specified.

  • item_amountsobject[]optional

Responses

  • 201

    The Order was successfully retrieved

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

put/shop/orders/{orderId}/tip

Update the tip on an order

updateOrderTip

Use this endpoint to update the tip applied to an order.

Path parameters

  • orderIduuidrequired

    The ID of the order

Request body

  • amountintegerrequired

    The amount of tip, in minor units.

  • basket_item_idsstring[]optionalnullable

    An array of basket item IDs to which the tip should be applied. If not provided, the tip will be applied to all applicable items in the order.

Responses

  • 201

    The Order was successfully retrieved

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

delete/shop/orders/{orderId}/tip/{tipId}

Remove a tip from an order

deleteOrderTip

Use this endpoint to remove a specific tip from an order.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • tipIdobject-idrequired

    The ID of the tip to remove

Responses

  • 200

    The Order was successfully retrieved

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

get/shop/orders/{orderId}/order-messages

List order messages

listOrderMessages

This endpoint retrieves all the SMS messages and emails relating to an order.

Path parameters

  • orderIduuidrequired

    The ID of the order

Query parameters

  • pageintegeroptional

    The page to retrieve results from

  • per_pageintegeroptional

    The number of results to return per page

Responses

  • 200

    The order messages were successfully retrieved

  • 401

    The user is unauthenticated

  • 404

    The resource couldn't be found

get/shop/orders/{orderId}/automated-order-messages

Retrieve the date which the next automated order message will be sent at

getNextAutomatedOrderMessage

This endpoint retrieves the date for when the next automated order message will be sent. This includes reminder and follow-up messages.

Path parameters

  • orderIduuidrequired

    The ID of the order

Responses

  • 200

    The date and time for when the next automated order message will be sent.

  • 401

    The user is unauthenticated

  • 404

    The resource couldn't be found

get/shop/orders/{orderId}/sms

List SMS messages

listSmsMessages

This endpoint retrieves all the SMS messages relating to an order.

Path parameters

  • orderIduuidrequired

    The ID of the order

Query parameters

  • pageintegeroptional

    The page to retrieve results from

  • per_pageintegeroptional

    The number of results to return per page

Responses

  • 200

    The SMS messages were successfully retrieved

  • 401

    The user is unauthenticated

  • 404

    The resource couldn't be found

post/shop/orders/{orderId}/sms

Send an SMS message

createSmsMessage

This endpoint sends an SMS message to a customer.

Path parameters

  • orderIduuidrequired

    The ID of the order

Request body

  • message_typestringrequired

    The type of message the SMS message is.

    Possible values:basket_confirmedbasket_cancelled_with_chargebasket_cancelled_without_chargebasket_reminderbasket_follow_uppay_by_link_request
  • paramsobjectoptional

    The parameters to be used in the SMS message.

Responses

  • 201

    The SMS message was successfully sent

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

get/shop/orders/{orderId}/sms/{smsId}

Get a single SMS message

getSmsMessage

This endpoint retrieves a single SMS message relating to an order.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • smsIdobject-idrequired

    The ID of the SMS Fragment

Responses

  • 200

    The SMS message was successfully sent

  • 404

    The resource couldn't be found

delete/shop/orders/{orderId}/sms/{smsId}

Delete an SMS message

deleteSmsMessage

This endpoint deletes an SMS message relating to an order.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • smsIdobject-idrequired

    The ID of the SMS Fragment

Responses

  • 204

    The SMS message was successfully deleted

  • 404

    The resource couldn't be found

post/shop/orders/{orderId}/sms/preview

Preview an SMS message for an order

createSmsMessagePreview

This endpoint previews an SMS message for an order.

Path parameters

  • orderIduuidrequired

    The ID of the order

Request body

  • message_typestringrequired

    The type of the SMS message.

    Possible values:basket_confirmedbasket_cancelled_with_chargebasket_cancelled_without_chargebasket_reminderbasket_follow_uppay_by_link_request
  • paramsobjectoptional

    The parameters to be used in the SMS message.

Responses

  • 201

    The preview of the SMS message was successfully retrieved

  • 404

    The resource couldn't be found

get/shop/orders/{orderId}/sms/suppress

Retrieve the suppression status of an SMS message for an order

getSmsMessageSuppressionStatus

This endpoint retrieves the suppression status of a scheduled follow-up or reminder SMS message for an order.

Path parameters

  • orderIduuidrequired

    The ID of the order

Responses

  • 200

    The suppression status of the SMS message was successfully retrieved

  • 401

    The user is unauthenticated

  • 404

    The resource couldn't be found

put/shop/orders/{orderId}/sms/suppress

Manage SMS suppression for an order

createSmsMessageSuppression

This endpoint allows you to stop or start a scheduled follow-up or reminder SMS message from being sent for an order.

Path parameters

  • orderIduuidrequired

    The ID of the order

Request body

  • message_typestringrequired

    The type of message the SMS message is.

    Possible values:basket_reminderbasket_follow_up
  • suppressbooleanrequired

    Whether the SMS message should be suppressed.

Responses

  • 201

    The SMS message was successfully suppressed

  • 404

    The resource couldn't be found

post/shop/orders/{orderId}/customer

Add customer to an order

actionAddCustomerToOrder

Use this endpoint to add a customer to an order.

Path parameters

  • orderIduuidrequired

    The ID of the order

Request body

  • idstringrequired

    Identifier of the customer to attach as the lead booker on this order. Where source is trybe this is the Trybe customer UUID; for third-party sources it's the external customer reference from the PMS or CRM.

  • sourcestringoptional

    The source of the customer addition

Responses

  • 201

    A summary of a customer

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

post/shop/orders/{orderId}/customer-credits

Apply a customer credit to an order

createOrderCustomerCredit

Apply a customer credit balance to an order — for example, redeeming a refund credit or a gift balance held against the customer's profile. The updated Order is returned so the caller can see the new outstanding balance after the credit is deducted.

Returns 400 Bad Request if the credit can't be applied — for example because it has already been fully redeemed, belongs to a different customer, or is expired.

Path parameters

  • orderIduuidrequired

    The ID of the order

Request body

  • idstringrequired

    Identifier of the CustomerCredit to apply to this order. Customer credits are managed under the Customers API and must belong to a customer linked (directly or via a guest) to this order.

Responses

  • 201

    The Order was successfully retrieved

  • 400

    The request failed.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

delete/shop/orders/{orderId}/customer-credits/{customerCreditId}

Remove a customer credit from an order

deleteOrderCustomerCredit

Remove a previously-applied customer credit from an order. The credit's balance is refunded back to the customer's profile and the order totals are recalculated.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • customerCreditIdstringrequired

    The ID of the customer credit applied to the order.

Responses

  • 204

    The customer credit was successfully removed from the order.

  • 404

    The resource couldn't be found

put/shop/orders/{orderId}/items/{itemId}/package-items/{packageItemId}

Update a package item on a package order item

updateOrderItemPackageItem

Updates the scheduling configuration of a single child item within a parent package order item — for example moving the massage slot of a spa day to a different practitioner, time, or room.

The payload accepts the same scheduling fields used when adding a package item via POST /shop/orders/{orderId}/items/{itemId}/package-items. Set fields you want to change; omitted fields are left as-is.

The update is routed through the availability layer, so room, practitioner and equipment conflicts are validated. The order totals are recalculated and the refreshed parent item is returned.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • itemIduuidrequired

    The ID of the order item

  • packageItemIduuidrequired

    The ID of the package item — i.e. one of the child line items inside a parent package order item (a treatment slot inside a spa-day package, a class booking inside a series, etc.).

Request body

  • idstringrequired

    Identifier of the offering this option points at — an AppointmentType, SessionType or retail Product, depending on item_type. The guest sees the offering's name and image when picking this option in the storefront.

  • item_typestringrequired

    The type of item this option represents.

  • offeringobjectrequirednullable
  • price_changeintegerrequirednullable

    A currency amount that this option would increase the package price by.

Responses

  • 200

    Describes a line item within an order.

  • 400

    The request failed.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

delete/shop/orders/{orderId}/items/{itemId}/package-items/{packageItemId}

Remove a package item from a package order item

deleteOrderItemPackageItem

Removes a single child item from a parent package line item — for example dropping the massage out of a spa day, or removing one class booking from a multi-class package. If the child item is a booking the underlying booking is cancelled and any held resources (practitioner, room, equipment) are released; if it is a purchase it is voided.

The parent package item is left in place — even if every child is removed — so that the package can later be re-populated by adding new package items via POST /shop/orders/{orderId}/items/{itemId}/package-items. The order's totals are recalculated immediately.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • itemIduuidrequired

    The ID of the order item

  • packageItemIduuidrequired

    The ID of the package item — i.e. one of the child line items inside a parent package order item (a treatment slot inside a spa-day package, a class booking inside a series, etc.).

Responses

  • 204

    The package item was successfully removed.

  • 400

    The request failed.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

put/shop/orders/{orderId}/items/{itemId}/price

Override an order item's price

updateOrderItemPrice

Sets a manual price override on a line item. The supplied price becomes the line's selling price, replacing the computed value derived from price rules, package allocations and promotional discounts. The new price must be higher than the item's original computed price — to lower the price, apply an OrderDiscount instead.

The order's totals are recalculated synchronously and the refreshed item is returned. Use DELETE on the same URL to clear the override and revert to the computed price.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • itemIduuidrequired

    The ID of the order item

Request body

  • priceintegerrequired

    The new price of the item, in the smallest denomination of the order's currency (e.g. pence, cents). Must be strictly greater than the item's currently computed price.

Responses

  • 200

    Describes a line item within an order.

  • 400

    The request failed.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

delete/shop/orders/{orderId}/items/{itemId}/price

Reset an order item's price override

deleteOrderItemPrice

Clears any manual price override applied to the line item and reverts it to its computed price — i.e. the price that would have been charged based on the underlying offering's price rules, any promo codes, and any package allocation. Use this to undo an earlier override (set via PUT /shop/orders/{orderId}/items/{itemId}/price) when the customer changes their mind, the override was applied to the wrong line, or a discount has rendered the override moot.

The order's totals are recalculated synchronously and the refreshed item is returned.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • itemIduuidrequired

    The ID of the order item

Responses

  • 200

    Describes a line item within an order.

  • 400

    The request failed.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

delete/shop/orders/{orderId}/vouchers/{voucherCode}

Remove a voucher from an order

deleteOrderVoucher

Detaches the given voucher from the order and refunds the redemption back onto the voucher's remaining balance. Use this when a voucher has been mistakenly applied — typically immediately after the customer says "actually, can you take that off?" — or when a refund flow needs to release the voucher value so it can be applied to a different order. The voucher itself is not cancelled; only its association with this order is removed.

The order's totals are recalculated synchronously. If the voucher was the sole source of payment, the order will fall back to an outstanding balance equal to the voucher's previous contribution.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • voucherCodestringrequired

    The redeemable code printed on the voucher (e.g. XJ4P-RT8M). The code uniquely identifies the voucher within the site — there is no separate numeric ID.

Responses

  • 200

    The Order was successfully retrieved

  • 400

    The request failed.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

post/shop/orders/{orderId}/cancel

Cancel an order (action variant)

actionCancelOrder

Cancel a submitted order. Functionally equivalent to DELETE /shop/orders/{orderId} but exposed as a POST action so it can sit alongside the other lifecycle transitions (reserve, submit, settle, no-show) under a consistent POST .../{verb} shape.

Each line item is cancelled in turn — bookings (appointments, area bookings, sessions, table reservations) are cancelled and any held resources released; purchases (vouchers, memberships, retail products) are voided; and any package items follow the cancellation rules of their underlying components. Payments remain attached to the order so they can be refunded separately via POST /shop/orders/{orderId}/payments/{paymentId}/refunds or absorbed into a credit note.

Fires the internal BasketCancelled event, which downstream integrations subscribe to for PMS/CRM sync.

Path parameters

  • orderIduuidrequired

    The ID of the order

Responses

  • 200

    The Order was successfully retrieved

  • 400

    The request failed.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

post/shop/orders/{orderId}/discounts/{discountId}/recalculate

Recalculate an order-level discount

actionRecalculateOrderDiscount

Recompute the value of an existing order-level discount against the current state of the order. Used after the operator has changed the order's contents — added or removed items, applied a coupon, attached a voucher — to make sure the discount still reflects the correct calculated amount.

The discount keeps its original discount_type_code, amount_type and discount_amount; only the derived fields (calculated_amount, line-level allocations) are refreshed. Returns the updated discount.

A no-op if nothing has changed — safe to call defensively.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • discountIduuidrequired

    The ID of the order discount

Responses

  • 200

    The discount was successfully recalculated.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

post/shop/orders/{orderId}/items/{itemId}/package-items

Add a package item to a package order item

createOrderItemPackageItem

Add a single child item to a parent package order item. Used after creating the package line via POST /shop/orders/{orderId}/items to fulfil each of the package's choices — for example picking which treatment to take as the "massage" slot in a spa day package, and which group class to attend as the "fitness" slot.

choice_id names the slot being filled and option_id names the specific offering being chosen. The combination must match the parent package's configured choices and options.

item_configuration carries the per-item scheduling — time, duration, room, practitioners, areas — and is the preferred place to set those fields. The top-level time, duration, practitioner_ids, room_id and area_ids fields remain for backward compatibility but are deprecated and will be removed in a future major version.

On success the parent item is reloaded with the new child item nested in its package_items array.

Returns 400 Bad Request if the choice/option pair is invalid, the resources aren't available, or the parent package is in a state that no longer accepts new package items.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • itemIduuidrequired

    The ID of the order item

Request body

  • choice_idstringrequired

    Identifier of the package choice the new item satisfies. Choices are configured on the parent package and group together the eligible options (e.g. "pick one of these treatments"). Must match one of the parent package's configured choice IDs.

  • option_idstringrequired

    Identifier of the option within the chosen choice to book — this is the actual offering being scheduled (e.g. a specific appointment type). Must be one of the options the choice exposes.

  • item_configurationobjectoptional

    Per-item scheduling configuration: time, duration, room, practitioners, areas, etc. Use this in preference to the top-level scheduling fields (which remain for backward compatibility but will be removed in a future major version).

  • guest_idsstring[]optional

    The guests this package item is for. Each ID must belong to a Guest already attached to the order.

  • timestringoptionalDeprecated

    Deprecated — use item_configuration.time. Time of day for the booking in HH:mm format.

  • durationintegeroptionalDeprecated

    Deprecated — use item_configuration.duration. Duration in minutes.

  • room_idstringoptionalnullableDeprecated

    Deprecated — use item_configuration.room_id.

  • practitioner_idsstring[]optionalnullableDeprecated

    Deprecated — use item_configuration.practitioner_ids.

  • area_idsstring[]optionalnullableDeprecated

    Deprecated — use item_configuration.area_ids.

Responses

  • 201

    Describes a line item within an order.

  • 400

    The request failed.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

get/shop/orders/{orderId}/itinerary

Retrieve an itinerary grouped by guest

getOrderItinerary

Retrieve the order's itinerary — the list of bookings on the order, grouped first by which guest they're for and then by date. Used by the operator-facing day-of-arrival view to print or display a per-guest schedule.

Each guest bucket lists the guest's name(s) plus one entry per date the guest has a booking on. Each date entry lists the bookings (name, start_time, end_time) sorted by start time.

Purchases (vouchers, products, memberships) are not included — only items that produce a scheduled booking.

Path parameters

  • orderIduuidrequired

    The ID of the order

Responses

  • 200

    The order's itinerary grouped by guest and date.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

get/shop/orders/{orderId}/itinerary/doc

Generate a downloadable itinerary document

getOrderItineraryDoc

Generate a Word document version of the order's itinerary and return a signed download URL. The document is rendered in the site's default locale (not the caller's) so that operators printing for guests get the version the guest will read.

The download URL is short-lived; treat it as single-use and fetch a fresh one for each download. The document content matches the JSON itinerary returned by GET /shop/orders/{orderId}/itinerary.

Path parameters

  • orderIduuidrequired

    The ID of the order

Responses

  • 200

    A short-lived download URL for the itinerary document.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

post/shop/orders/{orderId}/lead-booker

Update the order's lead booker

actionUpdateOrderLeadBooker

Update the lead-booker details on an order. Stores the customer contact and tax information against the order header and, when a lead-booker Guest exists on the order, copies the same first and last name through to it so the operator-facing guest list and the order header stay aligned.

phone is validated against the site's country code and stored in E.164 format. Pass tax_address_id to copy one of the customer's saved addresses into the order's tax address; pass legal_name / tax_id / tax_id_type to record a tax identifier against the order for downstream invoicing.

When tax_id is provided, tax_id_type is recorded alongside it (or left null if not supplied). When tax_id is absent the type is ignored.

Path parameters

  • orderIduuidrequired

    The ID of the order

Request body

  • first_namestringoptional

    First name of the lead booker. Copied onto the order's lead-booker Guest so the operator-facing guest list and the order header stay aligned.

  • last_namestringoptional

    Last name of the lead booker.

  • emailemailoptionalnullable

    Lead booker's email address.

  • phonestringoptionalnullable

    Lead booker's phone number, validated against the site's country code and stored in E.164 format.

  • tax_address_idstringoptionalnullable

    ID of one of the customer's existing addresses to copy into the order's tax address. Useful for B2B sales where the invoice needs to carry a specific billing address.

  • tax_idstringoptionalnullable

    The tax identifier (VAT number, ABN, etc.) to record on the order for downstream invoicing.

  • tax_id_typestringoptionalnullable

    The kind of tax identifier supplied — only meaningful when tax_id is also provided.

    Possible values:tax_numberpassportother

Responses

  • 200

    The Order was successfully retrieved

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

get/shop/orders/{orderId}/ledger-lines

List the ledger lines posted against an order

listOrderLedgerLines

List every ledger line posted against an order, sorted by ledger_date ascending. Ledger lines are Trybe's financial record of an order — one entry per revenue posting, per payment, per refund and per redemption — and form the audit trail used by the reporting suite to compute revenue, payment and tax totals.

Each line carries a revenue_centre code (and a human-friendly revenue_centre_name), an amount split into gross_amount and net_amount in the order's currency, plus references to the payable (the thing being charged — usually an order or a payment) and the causer (the user or system process that triggered the posting).

The response is not paginated; orders typically have tens of ledger lines and rarely hundreds.

Path parameters

  • orderIduuidrequired

    The ID of the order

Responses

  • 200

    The ledger lines for the order.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

post/shop/orders/{orderId}/lock

Lock an order

actionLockOrder

Lock the order to prevent further edits. Once locked, the order's items, payments and other sub-resources reject mutation attempts with 403 Forbidden. Used to freeze an order during a settlement, audit or close-of-day process; pair with POST /shop/orders/{orderId}/unlock to release the lock.

The action is idempotent — locking an already-locked order returns the same response without error. Records a locked audit-log entry against the order.

Path parameters

  • orderIduuidrequired

    The ID of the order

Responses

  • 200

    The Order was successfully retrieved

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

post/shop/orders/{orderId}/no-show

Mark an order as no-show

actionMarkOrderNoShow

Mark the order as a no-show — used when the customer didn't turn up for a scheduled booking and the operator wants to track the miss for revenue and reporting purposes without going through the standard cancellation flow. The order remains valid (payments stay attached, items aren't released) but is flagged as no_show for reporting.

Fires the internal BasketNoShowed event, which downstream integrations subscribe to for PMS/CRM sync.

Path parameters

  • orderIduuidrequired

    The ID of the order

Responses

  • 200

    The Order was successfully retrieved

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

post/shop/orders/{orderId}/overpayment-to-voucher

Transfer order overpayment to a new voucher

actionTransferOrderOverpaymentToVoucher

Move an order's overpayment balance into a freshly-issued voucher. Used when a customer has paid more than the order's total — for example after a partial refund or a price adjustment — and the operator wants to push the surplus into a gift voucher rather than refunding it back to the original payment method.

Specify the voucher_type_id to choose which VoucherType the new voucher should inherit its expiry, terms and presentation from. The voucher type must belong to the order's site.

On success the new VoucherCode is returned. The order's payment ledger picks up a redemption line so the overpayment no longer appears in the outstanding balance.

Common failure modes:

  • 400 Bad Request — the order has no overpayment, the voucher type doesn't exist on this site, or the underlying voucher issuance failed (typically a configuration problem on the voucher type).

Path parameters

  • orderIduuidrequired

    The ID of the order

Request body

  • voucher_type_idstringrequired

    The VoucherType to issue the new voucher under. Must belong to the order's site. The voucher inherits the type's expiry, terms and presentation defaults.

  • notesstringoptionalnullable

    Free-form notes recorded against the new voucher. Plain text only; HTML markup is rejected.

Responses

  • 201

    A new voucher was issued for the order's overpayment.

  • 400

    The request failed.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

post/shop/orders/{orderId}/payments/{paymentId}/charge

Charge a payment

actionChargeOrderPayment

Trigger a charge against a payment that has been recorded but not yet captured. Used for on_demand capture-method payments that have a stored payment method attached (e.g. saved card on file): this endpoint instructs the processor to attempt the capture immediately.

Returns the updated Payment with its new status — typically paid when the capture succeeds, or failed with a failure_reason when it doesn't.

Returns 400 Bad Request if the payment can't be charged in its current state (e.g. already paid, expired, or no stored payment method).

Path parameters

  • orderIduuidrequired

    The ID of the order

  • paymentIdobject-idrequired

    The ID of the payment.

Responses

  • 200

    A single payment recorded against an order.

  • 400

    The request failed.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

post/shop/orders/{orderId}/payments/{paymentId}/refunds

Refund a payment

createOrderPaymentRefund

Issue a refund against a payment. The amount is taken from the payment's refundable_amount and routed through the payment's processor (Stripe, Adyen, etc.) — the refund only succeeds if the processor confirms it. Successful refunds reduce the payment's refundable_amount and surface in the order's refunds list and ledger.

For settled orders, pass allocations to declare which items the refund should be attributed to and in what amounts. Without allocations on a settled order the refund is allocated proportionally across all line items. On unsettled orders allocations is ignored — the refund is simply taken off the outstanding balance.

Payments whose processor is pms_folio or external_voucher accept an optional processor override of manual: this lets an operator record the refund inside Trybe without round-tripping the external system (used when the refund is being recorded retroactively or the external system is unavailable).

notes is plain text only — HTML markup is rejected.

Common failure modes:

  • 400 Bad Request — the refund amount exceeds the payment's refundable balance, the processor rejected the refund, or the payment is in a state that doesn't accept refunds.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • paymentIdobject-idrequired

    The ID of the payment.

Request body

  • amountintegerrequired

    The amount to refund, expressed in the lowest denomination of the order's currency (pennies for GBP, cents for USD, etc.). Must not exceed the payment's refundable_amount. The processor records a RefundLimitExceededException on the order if it does; the request is rejected with a 400.

  • notesstringoptionalnullable

    Free-form notes recorded against the refund — for example the reason or the operator who authorised it. Plain text only; HTML markup is rejected.

  • allocationsobject[]optional

    For settled orders, an optional breakdown of which line items the refund should be allocated against. Each entry names a basket item ID and the amount of the refund that should be attributed to it. When omitted on a settled order, the refund is allocated proportionally across the order's items.

  • processorstringoptional

    For pms_folio and external_voucher payments, optionally override the processor used to record the refund. Defaults to the payment's original processor; passing manual lets the operator record the refund without round-tripping the external system. Ignored for other processor types.

    Possible values:manualpms_folioexternal_voucher

Responses

  • 201

    The refund was successfully created.

  • 400

    The request failed.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

get/shop/orders/{orderId}/postings

List the PMS postings for an order

listOrderPostings

List the ledger-line postings that have been forwarded to the site's PMS (Property Management System) integration. Each posting is a record of a charge or payment that Trybe pushed out to the PMS — used by reconciliation workflows to verify that Trybe's view of revenue matches the PMS's.

Results are scoped to the site's currently-configured PMS integration. Sorted by created_at ascending. Not paginated.

Returns an empty list for sites without a PMS integration configured.

Path parameters

  • orderIduuidrequired

    The ID of the order

Responses

  • 200

    The PMS postings recorded against the order.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

get/shop/orders/{orderId}/qr-code

Retrieve a QR code for an order

getOrderQrCode

Returns a PNG image encoding TRYBE_ORDER_{orderId} as a QR code. The Trybe-prefixed payload lets the Trybe operator app distinguish order codes from other QR payloads it scans, and avoids decoding ambiguity with raw IDs.

The response is cached for one hour (Cache-Control: public, max-age=3600) — the encoded payload doesn't change for the lifetime of the order.

No authentication is required for this endpoint, matching the behaviour of print-pos-receipt and the other operator-facing print routes; the order ID is the secret.

Path parameters

  • orderIduuidrequired

    The ID of the order

Responses

  • 200

    A PNG-encoded QR code for the order.

  • 404

    The resource couldn't be found

get/shop/orders/{orderId}/receipt

Generate a receipt document for an order

getOrderReceipt

Generate a fiscal receipt document for the order. The document is built from the order's non-deposit, non-redemption ledger lines and rendered by the site's configured fiscal-receipt generator. The actual document type depends on the site's integration — most sites return a JSON resource describing the receipt's contents, but a few PMS integrations return an HTML document directly.

Pass an Accept: text/html request header to receive an HTML body in the response when the generator produces one. Without the header, callers always receive the structured JSON form.

Returns 404 Not Found when the site doesn't have a fiscal receipt integration configured.

Path parameters

  • orderIduuidrequired

    The ID of the order

Responses

  • 200

    The generated receipt document. Either JSON (default) or HTML when the site's integration produces it and the request opted in via Accept: text/html.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

get/shop/orders/{orderId}/refundable-items

List the refundable items on an order

listOrderRefundableItems

List the items that can currently be refunded against the order, alongside any service-charge and tip components when they carry a positive balance. Used by the refund flow to render the operator-facing "what can I refund?" picker.

Each entry surfaces the line item's identifier, type, refundable amount and an allocation_hint the refund processor uses when splitting a refund across multiple items. The endpoint never issues a refund itself — POST /shop/orders/{orderId}/payments/{paymentId}/refunds is the write side.

Path parameters

  • orderIduuidrequired

    The ID of the order

Responses

  • 200

    The items on the order that can currently be refunded, together with service-charge and tip lines when they carry a positive balance.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

get/shop/orders/{orderId}/refunds

List the refunds against an order

listOrderRefunds

List every refund that has been recorded against the order, across every payment. Refunds carry the amount, status, the payment they were issued against, and any operator notes captured at the time. The response is not paginated; most orders have a handful of refunds at most.

To create a new refund, use POST /shop/orders/{orderId}/payments/{paymentId}/refunds.

Path parameters

  • orderIduuidrequired

    The ID of the order

Responses

  • 200

    The refunds recorded against the order.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

get/shop/orders/{orderId}/refunds/{refundId}

Retrieve a single refund

getOrderRefund

Retrieve a single refund recorded against the order. The response carries the refund's amount, status, the payment it was issued against and the processor-specific data (chargeback IDs, PMS sync state, etc.) used downstream by reconciliation jobs.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • refundIdobject-idrequired

    The ID of the refund.

Responses

  • 200

    A single refund recorded against an order.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

post/shop/orders/{orderId}/reserve

Reserve an order's resources

actionReserveOrder

Place a short-lived hold on the underlying resources for every booking item in the order — practitioners, rooms, equipment, areas — so that another caller can't grab the same slot while the order is being finalised. Reservations are cooperative: they block other bookings only when the system explicitly checks (via the availability service), and they expire automatically after reserve_mins minutes.

Pass reserve_mins to override the site's default hold time; omit it to use the default. The value must be greater than zero.

Returns 400 Bad Request when one or more items can no longer be held (the underlying availability has slipped since the order was built).

Path parameters

  • orderIduuidrequired

    The ID of the order

Request body

  • reserve_minsintegeroptional

    How long the underlying resources should be reserved for, in minutes. Must be greater than zero. If omitted, the site's default hold time is used. Reservations are cooperative — they prevent another caller from booking the same slot while the order is being finalised, but expire automatically once the window elapses.

Responses

  • 200

    The Order was successfully retrieved

  • 400

    The request failed.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

get/shop/orders/{orderId}/revenues

List the revenue breakdown for an order

listOrderRevenues

Return the order's revenue rolled up by revenue centre. Each entry carries the revenue centre code, the gross and net amounts (in the lowest denomination of the order's currency) and the tax components that contributed to the gross figure. Used by the operator-facing revenue panel and by the reporting suite to drill down into a single order's contribution to a daily or monthly total.

The response's meta.currency mirrors the order's currency so that callers don't have to look it up on the parent order.

Not paginated.

Path parameters

  • orderIduuidrequired

    The ID of the order

Responses

  • 200

    The revenue breakdown for the order, grouped by revenue centre.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

post/shop/orders/{orderId}/settle

Settle an order

actionSettleOrder

Settle the order — the final lifecycle transition that locks the order's revenue into the ledger and closes it for further edits. Used by automated close-of-day jobs as well as manually by operators when an order has been fully paid for and serviced.

The action is idempotent — settling an already-settled order is a no-op and returns the same order.

Returns 400 Bad Request when the order can't be settled — for example because it has outstanding balance or contains items that haven't been fulfilled. The error message describes the specific reason.

Path parameters

  • orderIduuidrequired

    The ID of the order

Responses

  • 200

    The Order was successfully retrieved

  • 400

    The request failed.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

post/shop/orders/{orderId}/submit

Submit an order

actionSubmitOrder

Convert a basket into a confirmed order. The endpoint runs the final validation pass — checking item availability, payment coverage, intake form completion and any site-specific rules — and then commits the basket: bookings are confirmed, payments are moved out of pending where required, and the order's status advances out of the basket states.

The {orderId} placeholder is interchangeably called basket in legacy clients; the route accepts either an order or a basket ID pointing at the same record.

Pass skip_availability_checks=true to bypass the second-pass availability recheck normally run at submission time. The flag is honoured only for users that hold the RESERVATIONS_OVERRIDE_RULES permission; operators without it have the flag silently ignored.

Failure modes:

  • 400 Bad Request — the basket isn't valid for submission (e.g. insufficient payment, expired availability, integration rule violation). The error message describes the specific reason.
  • 400 Bad Request with the message "One or more items are now unavailable" — availability changed between basket build and submission.
  • 400 Bad Request with the message "The basket was unable to be submitted. Please try again." — a transient lock-timeout occurred and the caller should retry.

On success the freshly submitted order is returned with an intake_form_url field hydrated when one or more items require a pre-arrival intake form to be completed.

Path parameters

  • orderIduuidrequired

    The ID of the order

Request body

  • skip_availability_checksbooleanoptional

    When true, bypasses the second-pass availability recheck normally run at submission time. Only takes effect for users that hold the RESERVATIONS_OVERRIDE_RULES permission — operators without it have the flag silently ignored. Useful when an operator has manually confirmed availability outside the system and wants to push a borderline booking through.

Responses

  • 200

    The Order was successfully retrieved

  • 400

    The request failed.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

post/shop/orders/{orderId}/unlock

Unlock an order

actionUnlockOrder

Release a lock previously placed on the order via POST /shop/orders/{orderId}/lock. Once unlocked the order accepts edits again. Requires the RESERVATIONS_UNLOCK permission, which is typically held by a smaller set of operators than the day-to- day lock action.

The action is idempotent — unlocking an already-unlocked order returns the same response without error. Records an unlocked audit-log entry against the order.

Path parameters

  • orderIduuidrequired

    The ID of the order

Responses

  • 200

    The Order was successfully retrieved

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

post/shop/orders/{orderId}/vouchers

Add a voucher payment to an order

createOrderVoucher

Redeem a voucher code against the order. The voucher's remaining balance is applied as a payment against the order — either settling the outstanding balance in full or contributing toward it depending on the voucher's value. The order is returned with the new payment listed in its payments array.

The voucher code must reference a valid, unredeemed VoucherCode on the order's site. Common failure modes:

  • 400 Bad Request — the voucher is expired, fully redeemed, belongs to a different site, or is in a state that doesn't accept new redemptions. The error message describes the specific reason.

Remove a previously-redeemed voucher with DELETE /shop/orders/{orderId}/vouchers/{voucherCode}.

Path parameters

  • orderIduuidrequired

    The ID of the order

Request body

  • codestringrequired

    The voucher code to redeem against this order. Must reference a valid, unredeemed VoucherCode on the order's site. On success, the voucher is recorded as a payment against the order and its remaining balance is decremented.

Responses

  • 200

    The Order was successfully retrieved

  • 400

    The request failed.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

get/shop/order-by-ref/{orderRef}

Get an order by reference

getOrderByRef

Looks up an Order by the short customer-facing reference Trybe issues (e.g. TRY1234). Equivalent to GET /shop/orders/{orderId} but keyed by the human-readable reference printed on receipts and emails — useful when an operator has the reference but not the order ID.

The lookup is scoped to the sites the calling user belongs to. Pass site_id to narrow further. Returns 404 if the reference doesn't match any in-scope order.

Requires the RESERVATIONS_VIEW permission on the matching order's site.

Path parameters

  • orderRefstringrequired

    The short customer-facing order reference (e.g. TRY1234). The lookup is case-insensitive: Trybe upper-cases the value before matching against stored references.

Query parameters

  • site_iduuidoptional

    Optional UUID filter to scope the lookup to a single site. By default the search runs across every site the calling user belongs to and returns the first match.

  • generic_items_arraybooleanoptional

    When true, the order's line items are returned as a single polymorphic items array rather than the typed appointment_items, area_booking_items etc. groupings. Easier to iterate from the storefront; less convenient for type-aware operator tooling.

Responses

  • 200

    The Order was successfully retrieved

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

get/shop/order-intake-forms/{orderIntakeFormId}

List intake forms for an order

listOrderIntakeForms

Returns one row per (guest, intake form) on the order — completed forms, pending ones the guest still needs to fill, and previously completed mandatory waivers that roll forward from an earlier order. Use this to render an intake-form checklist on the operator console or to link a guest to their form via intake_form_url.

Mandatory-waiver behaviour: when a guest on the order has already signed a mandatory waiver against this site on a previous order (and no new waiver has been issued for the current order), that previous waiver is included with mandatory_waiver=true and requires_intake_form=false, so the operator UI shows it as satisfied without prompting for a fresh signature.

Requires the RESERVATIONS_VIEW permission on the order's site.

Path parameters

  • orderIntakeFormIdobject-idrequired

    The unique identifier of the Order whose intake forms are being listed. (The route parameter is named for the resource it surfaces; the underlying lookup keys on order/basket ID.)

Responses

  • 200

    Per-guest intake-form status entries for the order. One entry per guest + form combination — see OrderIntakeForm for the full shape semantics.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

put/shop/orders/{orderId}/guests/{guestId}/complete-check-in

Complete a guest's check-in for an order

actionCompleteOrderGuestCheckIn

Marks the guest identified by guestId as checked in against the parent Order and checks the guest in to every session booking on the order in one call. Idempotent: re-running on an already-checked-in guest is a no-op.

Side effects performed atomically:

  • The order guest's checked_in_at timestamp is set to the server's current time (if not already set).
  • Every session booking the guest holds on the order is moved to the arrived stage.
  • A kiosk_check_in event is dispatched to the Check-Ins API so downstream integrations (e.g. PMS, fiscalisation) are notified.

Requires the RESERVATIONS_MANAGE permission on the order's site. No request body.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • guestIdobject-idrequired

    The ID of the guest on the order.

Responses

  • 200

    The guest was successfully created or updated.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

put/shop/orders/{orderId}/items/{itemId}/delivery_date

Update the delivery date of a voucher purchase order item

updateOrderItemDeliveryDate

Sets the planned delivery date on a voucher-purchase line item. Only meaningful for line items whose underlying offering is a voucher purchase with delivery_method_type: physical — i.e. physical voucher dispatches that need scheduling.

The path uses delivery_date (underscore) for historical reasons and is preserved here to keep parity with the legacy Trybe API URL contract.

Path parameters

  • orderIduuidrequired

    The ID of the order

  • itemIduuidrequired

    The ID of the order item

Request body

  • delivery_datedaterequired

    The new dispatch date for the voucher, as an ISO 8601 date (no time component). The site's mail-out workflow will schedule the print/post job for this date.

Responses

  • 200

    Describes a line item within an order.

  • 400

    The request failed.

  • 404

    The resource couldn't be found