---
title: "Add an item to a Basket"
method: POST
path: "/shop/basket/{basketId}/items"
tags: ["Baskets"]
---

# Add an item to a Basket

`POST /shop/basket/{basketId}/items`

Use this endpoint to add an item to a `Basket`.

## Request body

- object
  - `discount_amount` integer, nullable — Manual discount to apply to this line item, in the smallest currency unit (e.g. pence, cents). Subtracted from the line subtotal before tax. Defaults to 0 / null (no discount).
  - `guest_ids` string[]
  - `guests` object[]
    - `customer_id` string, uuid
    - `is_lead_booker` boolean
    - `name` string, required
  - `offering_id` string, object-id — ID of the offering being added to the basket. Required for every `offering_type` other than free-form vouchers. The format depends on the offering type — practitioner-scheduled offerings use Mongo ObjectIDs.
  - `offering_type` 'appointment' | 'appointment_enquiry' | 'area_booking' | 'course' | 'hotel_room_reservation' | 'membership' | 'package' | 'product' | 'session' | 'table_reservation' | 'voucher', required — 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.
  - `price` integer — Override price for this line item in the smallest currency unit (e.g. pence, cents). Omit to let the server compute the price from the offering's current price rules.
  - `quantity` integer — Number of units to add to the basket. Defaults to 1.

## Response `200`

Successfully added an item to a `Basket`.

- object
  - `data` Basket, required
    - `id` string, object-id, required
    - `applied_promo_code` AppliedPromoCode
      - `id` string, object-id, required — The ID of the promo code.
      - `applied_at` string, date-time — The date and time the promo code was applied.
      - `applied_by` UserSummary
        - `id` string, mongo-id, required — The ID of the user.
        - `avatar` Media
          - `id` string, uuid, required — Unique identifier of the uploaded media item, returned from `createMedia`. Pass this ID into any field that accepts a media reference (logos, hero images, product images, etc.).
          - `file_name` string, required — Original filename of the uploaded asset, preserved as provided at upload time. Used for display in the media library and as a hint when serving downloads.
          - `mime_type` string, required — The mime type of the media item.
          - `original_url` string, required — The url of the media resource.
          - `size` integer, required — The size of the media item in bytes.
          - `url` string, required — The url of the converted media resource.
        - `email` string, email, required
        - `first_name` string, required
        - `full_name` string, required
        - `last_name` string, required
      - `code` string, required — The code of the promo code.
      - `discount_total` integer, required — The total discount from the applied promo code on the order.
      - `is_discount_applied` boolean, required — Whether the discount from the promo code has been applied to the order.
      - `percentage` integer, required — The percentage discount from the promo code.
    - `applied_promo_code_discount_total` integer, required
    - `applied_promo_code_id` string, nullable, required
    - `coupon_codes` BasketCouponSummary[], required
      - `id` string, object-id, required — The ID of the coupon.
      - `code` string, required — The code of the coupon.
      - `name` string, required — The name of the coupon.
      - `description` string, required — A description of the coupon.
      - `customer_credit_id` string, uuid, required — The customer credit this coupon relates to, if applicable.
    - `currency` string, required — The ISO-4217 currency code.
    - `customer_id` string, uuid, required
    - `discount_total` integer, required
    - `email` string, required
    - `guests` Guest[], required
      - `id` string, object-id, required — Stable identifier for the guest slot on an order. Used to attach intake-form answers, check the guest in or out, and link the slot to a `Customer` once one is resolved.
      - `checked_in_at` string, date-time, nullable, required — ISO-8601 timestamp at which the guest checked in for their visit. `null` until check-in happens.
      - `checked_out_at` string, date-time, nullable, required — ISO-8601 timestamp at which the guest checked out / finished their visit. `null` while the visit is still in progress.
      - `customer_id` string, uuid, nullable, required — The `Customer` the guest slot has been linked to, if any. `null` for walk-ins or anonymous guests that haven't been matched to a customer record yet.
      - `email` string, email, nullable — Email address captured for this guest, used to send the pre-visit intake form and post-visit follow-ups. `null` when no email has been supplied for the slot.
      - `first_name` string, required — The first name of the guest.
      - `intake_form_submission_id` string, object-id — Identifier of the most recent intake-form submission for this guest, if one exists. Use this to fetch the submitted answers from the guest-intake API.
      - `intake_form_complete` boolean, required — Whether the intake form for the guest is complete.
      - `is_lead_booker` boolean, required — Whether the guest is the lead booker.
      - `last_name` string, required — The last name of the guest.
      - `name` string, required — Full display name for the guest — typically `first_name` plus `last_name`, but kept as a separate field so the platform can render it consistently across receipts, intake forms and check-in screens.
    - `first_name` string, required
    - `is_promo_code_discount_applied` boolean, required
    - `items` Item[], required
      - `id` string, object-id, required
      - `currency` string, required — The ISO-4217 currency code.
      - `date` string, date, required
      - `discounts` Discount[], required
        - `id` string, object-id, required — The ID of the order discount
        - `amount_type` 'monetary' | 'percentage', required — The type of the amount this discount describes.
        - `applicable_for` 'app_and_booking_engine' | 'app_only', nullable, required — Where this discount type is able to be applied.
        - `applied_at` string, date-time, required — The date and time that the discount was applied.
        - `applied_by` UserSummary, required
          - `id` string, mongo-id, required — The ID of the user.
          - `avatar` Media
            - `id` string, uuid, required — Unique identifier of the uploaded media item, returned from `createMedia`. Pass this ID into any field that accepts a media reference (logos, hero images, product images, etc.).
            - `file_name` string, required — Original filename of the uploaded asset, preserved as provided at upload time. Used for display in the media library and as a hint when serving downloads.
            - `mime_type` string, required — The mime type of the media item.
            - `original_url` string, required — The url of the media resource.
            - `size` integer, required — The size of the media item in bytes.
            - `url` string, required — The url of the converted media resource.
          - `email` string, email, required
          - `first_name` string, required
          - `full_name` string, required
          - `last_name` string, required
        - `calculated_amount` integer, required — The total calculated amount of this discount.
        - `coupon` BasketCouponSummary, required
          - `id` string, object-id, required — The ID of the coupon.
          - `code` string, required — The code of the coupon.
          - `name` string, required — The name of the coupon.
          - `description` string, required — A description of the coupon.
          - `customer_credit_id` string, uuid, required — The customer credit this coupon relates to, if applicable.
        - `coupon_code_id` string, object-id, nullable, required — The ID of the coupon code used to add this discount, if applicable.
        - `currency` string, required — The ISO-4217 currency code.
        - `discount_amount` integer, required — 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.
        - `discount_type_code` string, required — The code for the discount type.
        - `reason_code` string, required — A code to describe the reason for the discount.
        - `site_id` string, uuid, required — The ID of the site the discount is associated with.
      - `duration` integer, required
      - `guest` Guest
        - `id` string, object-id, required — Stable identifier for the guest slot on an order. Used to attach intake-form answers, check the guest in or out, and link the slot to a `Customer` once one is resolved.
        - `checked_in_at` string, date-time, nullable, required — ISO-8601 timestamp at which the guest checked in for their visit. `null` until check-in happens.
        - `checked_out_at` string, date-time, nullable, required — ISO-8601 timestamp at which the guest checked out / finished their visit. `null` while the visit is still in progress.
        - `customer_id` string, uuid, nullable, required — The `Customer` the guest slot has been linked to, if any. `null` for walk-ins or anonymous guests that haven't been matched to a customer record yet.
        - `email` string, email, nullable — Email address captured for this guest, used to send the pre-visit intake form and post-visit follow-ups. `null` when no email has been supplied for the slot.
        - `first_name` string, required — The first name of the guest.
        - `intake_form_submission_id` string, object-id — Identifier of the most recent intake-form submission for this guest, if one exists. Use this to fetch the submitted answers from the guest-intake API.
        - `intake_form_complete` boolean, required — Whether the intake form for the guest is complete.
        - `is_lead_booker` boolean, required — Whether the guest is the lead booker.
        - `last_name` string, required — The last name of the guest.
        - `name` string, required — Full display name for the guest — typically `first_name` plus `last_name`, but kept as a separate field so the platform can render it consistently across receipts, intake forms and check-in screens.
      - `guests` Guest[], required
        - `id` string, object-id, required — Stable identifier for the guest slot on an order. Used to attach intake-form answers, check the guest in or out, and link the slot to a `Customer` once one is resolved.
        - `checked_in_at` string, date-time, nullable, required — ISO-8601 timestamp at which the guest checked in for their visit. `null` until check-in happens.
        - `checked_out_at` string, date-time, nullable, required — ISO-8601 timestamp at which the guest checked out / finished their visit. `null` while the visit is still in progress.
        - `customer_id` string, uuid, nullable, required — The `Customer` the guest slot has been linked to, if any. `null` for walk-ins or anonymous guests that haven't been matched to a customer record yet.
        - `email` string, email, nullable — Email address captured for this guest, used to send the pre-visit intake form and post-visit follow-ups. `null` when no email has been supplied for the slot.
        - `first_name` string, required — The first name of the guest.
        - `intake_form_submission_id` string, object-id — Identifier of the most recent intake-form submission for this guest, if one exists. Use this to fetch the submitted answers from the guest-intake API.
        - `intake_form_complete` boolean, required — Whether the intake form for the guest is complete.
        - `is_lead_booker` boolean, required — Whether the guest is the lead booker.
        - `last_name` string, required — The last name of the guest.
        - `name` string, required — Full display name for the guest — typically `first_name` plus `last_name`, but kept as a separate field so the platform can render it consistently across receipts, intake forms and check-in screens.
      - `image` Media
        - `id` string, uuid, required — Unique identifier of the uploaded media item, returned from `createMedia`. Pass this ID into any field that accepts a media reference (logos, hero images, product images, etc.).
        - `file_name` string, required — Original filename of the uploaded asset, preserved as provided at upload time. Used for display in the media library and as a hint when serving downloads.
        - `mime_type` string, required — The mime type of the media item.
        - `original_url` string, required — The url of the media resource.
        - `size` integer, required — The size of the media item in bytes.
        - `url` string, required — The url of the converted media resource.
      - `item_configuration` ItemConfiguration — Type-specific properties to configure an order item.
      - `net_total` integer, required
      - `offering_categories` object[], required
        - `id` string, object-id, required
        - `name` string, required
      - `offering_id` string, object-id, required
      - `offering_name` string, required
      - `offering_type` 'appointment' | 'appointment_enquiry' | 'area_booking' | 'course' | 'hotel_room_reservation' | 'membership' | 'package' | 'product' | 'session' | 'table_reservation' | 'voucher', required — 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.
      - `option_budgets` OptionBudget[]
        - `budget` string, nullable, required — The amount of the budget, in the smallest denomination.
        - `choice_id` string, required — The ID of the choice this option budget belongs to.
        - `remaining` string, nullable, required — The amount of the budget remaining to be spent, in the smallest denomination.
        - `spent` string, nullable, required — The amount spent towards the budget, in the smallest denomination.
      - `package_items` OrderItemPackageItem[], required
        - `id` string, mongo-id, required — The ID of the package item.
        - `booking_summary` union
          - AreaBookingSummary
            - `id` string, object-id, required
            - `area_ids` string[], required
            - `areas` BookableAreaSummary[], required
              - …
            - `duration` integer, required
            - `end_time` string, date-time, required
            - `offering` OfferingSummary, required — Summary details of an offering.
              - …
            - `start_time` string, date-time, required
            - `status` 'cancelled' | 'confirmed' | 'pending_confirmation' | 'reserved' | 'waitlisted', required
            - `created_at` string, date-time, required — When then resource was created.
            - `updated_at` string, date-time, required — When then resource was last updated.
          - BookingSummaryBookingSummary
            - `id` string, object-id, required
            - `duration` integer, required
            - `end_time` string, date-time, required
            - `equipment` EquipmentSummary[], required
              - …
            - `equipment_ids` string[], required
            - `offering` OfferingSummary, required — Summary details of an offering.
              - …
            - `practitioners` PractitionerSummary[], required
              - …
            - `practitioner_ids` string[], required
            - `practitioner_was_requested` boolean
            - `room` RoomSummary, required — The summary of a `Room` object
              - …
            - `room_id` string, object-id, required
            - `room_was_requested` boolean
            - `session_id` string, object-id
            - `start_time` string, date-time, required
            - `status` 'cancelled' | 'confirmed' | 'pending_confirmation' | 'reserved' | 'waitlisted', required
            - `created_at` string, date-time, required — When then resource was created.
            - `updated_at` string, date-time, required — When then resource was last updated.
          - TableReservationSummary
            - `id` string, object-id, required
            - `duration` integer, required
            - `end_time` string, date-time, required
            - `offering` OfferingSummary, required — Summary details of an offering.
              - …
            - `start_time` string, date-time, required
            - `status` 'cancelled' | 'confirmed' | 'pending_confirmation' | 'reserved' | 'waitlisted', required
            - `created_at` string, date-time, required — When then resource was created.
            - `updated_at` string, date-time, required — When then resource was last updated.
        - `choice_id` string, mongo-id, required — The ID of the package choice this item relates to.
        - `duration` integer, nullable, required — The duration of the item in minutes.
        - `guests` GuestSummary[]
          - `id` string, mongo-id, required — The ID of the guest.
          - `customer_id` string, mongo-id, nullable — The ID of the customer this guest relates to.
          - `name` string, required — The guest's full name.
          - `checked_in_at` string, date-time, nullable, required — The date and time the guest checked in.
        - `item_configuration` ItemConfiguration, required — Type-specific properties to configure an order item.
        - `offering_id` string, mongo-id, required — The ID of the offering.
        - `offering_name` string, required — The name of the offering.
        - `offering_type` string, required — The offering type of this package item.
        - `option_id` string, mongo-id, required — The ID of the choice option that this item relates to.
        - `price_change` integer, required — The amount by which this option changes the overall package price.
        - `reserved_until` string, date-time, required
        - `shared_basket_item_id` string, object-id
        - `status` 'cancelled' | 'in_progress' | 'new' | 'no_show' | 'settled' | 'submitted'
        - `time` string, date-time, nullable, required — The start time of the item.
      - `price` integer, nullable, required
      - `purchasable_details` union
        - PurchasableDetailsVoucher
          - `delivery_date` string, date-time
        - object
          - `membership_rate_id` string, object-id
          - `membership_type_id` string, object-id
          - `membership_type_name` string
          - `purchasable_id` string, object-id, nullable
          - `rate` object
            - `billing_frequency` string, required
            - `currency` string, required — The ISO-4217 currency code.
            - `default_duration` integer, required
            - `amount` string, required
          - `joining_fee` object
            - `amount` integer, required
            - `currency` string, required — The ISO-4217 currency code.
      - `quantity` integer, required
      - `reserved_until` string, date-time, nullable, required
      - `tax_amount` integer, required
      - `tax_percent` integer, required
      - `time` string, date-time, required
      - `total_cost` integer, nullable, required
      - `validity` object
        - `errors` object[], required
          - `message` string
        - `valid` boolean, required
      - `will_be_waitlisted` boolean
    - `items_reserved_until` string, date-time, nullable, required
    - `last_name` string, required
    - `net_total` integer, required
    - `order_ref` string, nullable, required
    - `organisation_id` string, uuid, required
    - `outstanding_payment_amount` integer, required
    - `payments` Payment[], required
      - `id` string, object-id, required — The ID of the item to be added.
      - `amount` integer, required — The amount of the payment, in the lowest denomination
      - `capture_method` string, nullable, required — At what point the payment amount will be captured
      - `chargebacks` Chargeback[]
        - `id` string, object-id, required
        - `amount` string, required
        - `currency` string, required — The ISO-4217 currency code.
        - `payment_id` string, object-id, required — The ID of the payment that was charged back.
        - `processor_data` object, required
        - `reason` string, required — The reason for the chargeback.
        - `status` 'confirmed' | 'pending' | 'processed' | 'reversed', required
        - `created_at` string, date-time, required — When then resource was created.
      - `currency` string, required — The ISO-4217 currency code.
      - `details_source` string, nullable, required — How the payment method will be provided
      - `failure_reason` string, nullable — If present, provides a human-readable explanation for the failure.
      - `item_revenues` PaymentItemRevenue[], nullable, required — How the payment amount is allocated across the order's items and revenue centres. Null for payments taken before item revenue allocation was enabled — such payments cannot support item-level operations like partial charge to room.
        - `basket_item_id` string, object-id, required — The ID of the order item that this allocation covers.
        - `revenue_centre` string, required — The revenue centre of the order item's revenue line that this allocation covers.
        - `gross_amount` integer, required — The gross amount of the payment allocated to this revenue line, in the lowest denomination.
        - `net_amount` integer, required — The net amount of the payment allocated to this revenue line, in the lowest denomination.
        - `refunded_amount` integer, required — The amount of this allocation that has been refunded, in the lowest denomination.
        - `currency` string, required — The ISO-4217 currency code.
      - `order_ref` string, nullable
      - `paid_at` string, date-time, nullable, required — The time and date that the payment was paid.
      - `payable_id` string, object-id, required
      - `payable_type` string, required
      - `processor` string, required — The payment processor to be used for the payment
      - `processor_data` object, required — A dictionary of processor-specific data
      - `processor_id` string, object-id, required
      - `processor_type` string, nullable, required
      - `refundable_amount` number, required — The amount of the payment that may be refunded.
      - `refunds` Refund[], required
        - `id` string, object-id, required — The ID of the refund.
        - `payment_id` string, object-id, required — The ID of the payment that was refunded.
        - `amount` integer, required — The amount of the refund.
        - `currency` string, required — The ISO-4217 currency code.
        - `notes` string, nullable — Notes that were added against the refund.
        - `status` 'pending' | 'complete' | 'failed', required — The current status of the refund.
        - `processor_data` object, required — A dictionary of processor-specific data.
        - `created_at` string, date-time, required — The date and time that the refund was created.
      - `status` 'cancelled' | 'expired' | 'failed' | 'paid' | 'payment_method_charged' | 'payment_method_stored' | 'pending' | 'ready_for_capture' | 'requires_action', required — The current status of the payment
      - `created_at` string, date-time, required — When then resource was created.
    - `phone` string, required
    - `promo_code_applied_at` string, date-time
    - `promo_code_applied_by` UserSummary
      - `id` string, mongo-id, required — The ID of the user.
      - `avatar` Media
        - `id` string, uuid, required — Unique identifier of the uploaded media item, returned from `createMedia`. Pass this ID into any field that accepts a media reference (logos, hero images, product images, etc.).
        - `file_name` string, required — Original filename of the uploaded asset, preserved as provided at upload time. Used for display in the media library and as a hint when serving downloads.
        - `mime_type` string, required — The mime type of the media item.
        - `original_url` string, required — The url of the media resource.
        - `size` integer, required — The size of the media item in bytes.
        - `url` string, required — The url of the converted media resource.
      - `email` string, email, required
      - `first_name` string, required
      - `full_name` string, required
      - `last_name` string, required
    - `site_id` string, uuid, required
    - `special_requests` string, nullable, required
    - `status` 'cancelled' | 'in_progress' | 'new' | 'no_show' | 'settled' | 'submitted', required
    - `submit_auth_amount` integer, nullable, required
    - `submit_errors` object[]
      - `error` string, required
      - `message` string, required
      - `time` integer, required
    - `submit_payment_amount` integer, nullable, required
    - `submitted_at` string, date-time, nullable, required
    - `total_cost` integer, required
    - `total_paid_or_authed` integer, required
    - `total_tax` integer, required
    - `totals` object, required
      - `applied_vouchers` integer, required
      - `auth_required` integer, required
      - `discounts` integer, required
      - `gross_total` integer, required
      - `net_total` integer, required
      - `payment_required` integer, required
      - `tax` integer, required
    - `voucher_codes` VoucherSummary[], required
      - `id` string, uuid, required — The ID of the voucher.
      - `amount_type` string, required — The amount type of the voucher.
      - `calculated_amount` integer — The calculated amount of the voucher.
      - `code` string, required — The code of the voucher.
      - `coupon_code_id` string, object-id — The ID of the coupon that created the voucher, if applicable.
      - `description` string, nullable, required — The description of the voucher.
      - `is_redeemed` boolean — Whether the voucher has been redeemed.
      - `name` string, required — The name of the voucher.
      - `voucher_type_id` string, object-id, required — The ID of the voucher type.
    - `created_at` string, date-time, required — When then resource was created.
    - `updated_at` string, date-time, required — When then resource was last updated.

## Other responses

- `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

---

[API](https://skmtc.dev/try/apis/trybe-api.md) · [All operations](https://skmtc.dev/try/apis/trybe-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/try/trybe-api/revisions/f37f92702da5/schema)