---
title: "Apply Basket Promocode"
method: PUT
path: "/api/basket/promocode"
tags: ["Basket"]
---

# Apply Basket Promocode

`PUT /api/basket/promocode`

Applies a promotional code to a basket.

## Query parameters

- `basket_id` string, required
- `promocode` string, required
- `currency` string — Currency to display event prices.
- `user_id` string
- `domain` string — Domain to validate promocode against. If not included then profile domains will be used
- `profile_name` string — Profile name
- `hostname` string — Associated hostname

## Headers

- `origin` string
- `X-Correlation-ID` string

## Response `200`

Successful Response

- Basket
  - `_id` string, required
  - `external_reference` string — Distributor reference for this basket
  - `checkout_status` 'not_checked_out' | 'checkout_pending' | 'payment_failed' | 'checked_out' | 'checked_out_with_errors' — - not_checked_out: the basket has neither been, nor is being checked out - checkout_pending: the basket is currently in the process of checking out - payment_failed: the basket payment failed, and thus wasn't checked out - checked_out: the basket has already been checked out - checked_out_with_errors: the basket has been checked out but 1 or more items errored
  - `created_on` string, date-time
  - `distributor_id` string — User ID of the event distributor which created this basket
  - `profile_external_user_id` string — External user ID used in handle_profile_post_checkout
  - `items` BasketItem[]
    - `cancellation_policy_information` string[] — Cancellation and refund policy for the item itself.
    - `cancellation_policy` string — (DEPRECATED) Cancellation policy for the item itself.
    - `id` string, required
    - `created_on` string, date-time
    - `booked_at` string, date-time — When this item was booked, if it was booked successfully.
    - `external_reference` string — Distributor reference for this basket item
    - `event_id` string, required
    - `event_slug` string
    - `availability_id` string
    - `product_id` string, required
    - `band_id` string
    - `event_name` string, required
    - `cancellation_allowed` boolean
    - `important_information` string[]
    - `notes` Notes
      - `ticket_notes` string
      - `description` string
      - `short_description` string
    - `ticket_instructions` string[]
    - `billing_information` string
    - `from_date` EventDateTime, required — Represents a date and time relating to an event.
      - `local` string, date-time, required — The date and time in the event's local timezone.
      - `utc` string, date-time, required — The date and time in UTC.
    - `to_date` EventDateTime, required — Represents a date and time relating to an event.
      - `local` string, date-time, required — The date and time in the event's local timezone.
      - `utc` string, date-time, required — The date and time in UTC.
    - `reservations` Reservation[] — The specific reservations associated with this item, or tickets if the item has been checked out.
      - `supplier_reference` string
      - `external_reference` string
      - `product_selection` string, required — Name of the ticket pool this reservation belongs to.
      - `concession_id` string
      - `concession_name` string — Name of the concession applied to this reservation.
      - `seat_selection` string — Identifier for the seat booked for this reservation, if applicable.
      - `price` Price, required — Represents an absolute monetary value in a particular currency. Cannot be negative.
        - `amount` number, required — Monetary value of this price in the given currency, with decimal point i.e. not integer format
        - `currency` string, required — ISO 4217 code for the currency in which the item's prices are sent
      - `commission` Price — Represents an absolute monetary value in a particular currency. Cannot be negative.
        - `amount` number, required — Monetary value of this price in the given currency, with decimal point i.e. not integer format
        - `currency` string, required — ISO 4217 code for the currency in which the item's prices are sent
      - `ticket` Ticket
        - `barcodes` Barcode[] — Barcodes for this ticket, if applicable (i.e. not collection etc).
          - `format` 'ean8' | 'ean13' | 'ean14' | 'itf' | 'upca' | 'upce' | 'code39' | 'code128' | 'gs1_128' | 'qr-code' | 'data-matrix' | 'pdf-417' | 'aztec' | 'image', required — Supported barcode formats.
          - `data` string, required — Textual data represented by this barcode.
          - `raw_code` string — The raw barcode code where it's not obtainable from `data`.
          - `image` string, required — URL of this barcode; generally but not necessarily a data URL containing base64-encoded data.
        - `delivery_methods` DeliveryMethod[], required — List of supported delivery methods.
      - `voucher_url` string — URL of the ticket voucher for the reservation.
    - `price` Price, required — Represents an absolute monetary value in a particular currency. Cannot be negative.
      - `amount` number, required — Monetary value of this price in the given currency, with decimal point i.e. not integer format
      - `currency` string, required — ISO 4217 code for the currency in which the item's prices are sent
    - `booking_fee` Price — Represents an absolute monetary value in a particular currency. Cannot be negative.
      - `amount` number, required — Monetary value of this price in the given currency, with decimal point i.e. not integer format
      - `currency` string, required — ISO 4217 code for the currency in which the item's prices are sent
    - `adjustments` Adjustment[] — Specific named surcharges/discounts (NOTE: already included in the `price` field) e.g. transfers or addons
      - `name` string, required
      - `type` 'charge_transfer' | 'charge_addon' | 'charge_other' | 'discount_other', required
      - `price` PriceDelta, required — Represents the difference between two monetary values. May be negative.
        - `amount` number, required — Monetary value of this price in the given currency, with decimal point i.e. not integer format
        - `currency` string, required — ISO 4217 code for the currency in which the item's prices are sent
    - `supplier_adjustment` PriceDelta — Represents the difference between two monetary values. May be negative.
      - `amount` number, required — Monetary value of this price in the given currency, with decimal point i.e. not integer format
      - `currency` string, required — ISO 4217 code for the currency in which the item's prices are sent
    - `organiser` Organiser — Describes an event/activity organiser.
      - `name` string — Company name.
      - `email` string, email — Email address to contact in case of post-booking issues.
      - `phone_number` string — Number to call in case of post-booking issues.
    - `pickup` Pickup
      - `latitude` number, required — Latitude in degrees
      - `longitude` number, required — Longitude in degrees
      - `id` string — Machine identifier for this place
      - `pickup_point_name` string, required — Friendly pickup point name, in English
      - `pickup_point_address` string, required — Street address of the pickup point
      - `time` EventDateTime, required — Represents a date and time relating to an event.
        - `local` string, date-time, required — The date and time in the event's local timezone.
        - `utc` string, date-time, required — The date and time in UTC.
    - `dropoff` Dropoff
      - `latitude` number, required — Latitude in degrees
      - `longitude` number, required — Longitude in degrees
      - `id` string — Machine identifier for this place
      - `dropoff_point_name` string, required — Friendly dropoff point name, in English
      - `dropoff_point_address` string, required — Street address of the pickup point
      - `time` EventDateTime, required — Represents a date and time relating to an event.
        - `local` string, date-time, required — The date and time in the event's local timezone.
        - `utc` string, date-time, required — The date and time in UTC.
    - `location` EventVenue
      - `latitude` number, required — Latitude in degrees
      - `longitude` number, required — Longitude in degrees
      - `id` string — Machine identifier for this place
      - `venue_brand_id` string — The brand ID that operates the venue
      - `venue_address` string, required — Street address of the venue
      - `seatplan_images` Image[] — Images of the venue's seatplan.
        - `desktop` string — URL to use on desktop devices
        - `mobile` string — URL to use on mobile devices
        - `thumbnail` string — URL of a square version of this image
      - `configuration` object
      - `venue_name` string, required — Friendly venue name, in English
      - `venue_brand` string — The brand name that operates the venue
      - `venue_city` string — The city of the venue
      - `venue_country` string — The country of the venue
    - `event_image` Image
      - `desktop` string — URL to use on desktop devices
      - `mobile` string — URL to use on mobile devices
      - `thumbnail` string — URL of a square version of this image
    - `ttl` string, date-time, required — Item reservation expiry time.
    - `booked_successfully` boolean — After checkout, whether this item has been successfully booked.
    - `status` 'unreserved' | 'reservation_pending' | 'reserving' | 'reserved' | 'booking' | 'fulfilment_pending' | 'fulfilment_errored' | 'booked' | 'errored' | 'seller_rejected' | 'cancelling' | 'cancelled' | 'saved' | 'errored_and_refunded', required — - unreserved: rereservation failed or hit max attempts and item will not attempt checkout - reservation_pending: item is pending re-reservation due to ttl expiry - reserving: item is currently locked for pending re-reservation due to ttl expiry - reserved: item availability is locked and being held until checkout - saved: item availability is not locked and item will attempt to book at checkout - booking: item is currently locked for pending checkout due to /basket/checkout or Stripe webhook - fulfilment_pending: item is waiting for fulfilment - fulfilment_errored: item booked but details not successfully retrieved - booked: item booked successfully - errored: item booking error - cancelled: item cancelled
    - `display_data` object
    - `reservation_attempts` integer — Number of re-reservation attempts made for this item.
    - `voucher_url` string — URL of merged ticket vouchers.
    - `resources` string[] — Additional resources for the ticket buyer's use, such as itineraries.
    - `event` BasketItemEventData, required
      - `delivery_methods` DeliveryMethod[] — List of supported delivery methods.
      - `admission_type` 'open_entry' | 'date_entry' | 'slot_entry' | 'timed_entry', required
      - `is_tbd` IsTbd
        - `time` boolean — Whether the event time is to be determined
        - `date` boolean — Whether the event date is to be determined
  - `total_items_price` Price — Represents an absolute monetary value in a particular currency. Cannot be negative.
    - `amount` number, required — Monetary value of this price in the given currency, with decimal point i.e. not integer format
    - `currency` string, required — ISO 4217 code for the currency in which the item's prices are sent
  - `total_booking_fee` Price — Represents an absolute monetary value in a particular currency. Cannot be negative.
    - `amount` number, required — Monetary value of this price in the given currency, with decimal point i.e. not integer format
    - `currency` string, required — ISO 4217 code for the currency in which the item's prices are sent
  - `total_discount` Price — Represents an absolute monetary value in a particular currency. Cannot be negative.
    - `amount` number, required — Monetary value of this price in the given currency, with decimal point i.e. not integer format
    - `currency` string, required — ISO 4217 code for the currency in which the item's prices are sent
  - `total_price` Price — Represents an absolute monetary value in a particular currency. Cannot be negative.
    - `amount` number, required — Monetary value of this price in the given currency, with decimal point i.e. not integer format
    - `currency` string, required — ISO 4217 code for the currency in which the item's prices are sent
  - `total_local_price` Price — Represents an absolute monetary value in a particular currency. Cannot be negative.
    - `amount` number, required — Monetary value of this price in the given currency, with decimal point i.e. not integer format
    - `currency` string, required — ISO 4217 code for the currency in which the item's prices are sent
  - `total_local_price_ttl` string, date-time — Expiry datetime for the total_local_price_currency value/exchange rate, set by Stripe.
  - `total_local_price_exchange_rate` number — Exchange rate used to convert the total price to the local currency, set by Stripe. An average of exchange rates for all items in the basket. This only differs from total_local_price_base_exchange_rate when the basket contains items with their own exchange rate, such as vivid USD
  - `total_local_price_base_exchange_rate` number — Exchange rate set by Stripe.
  - `promocodes` ApiPromocode[]
    - `code` string, required
    - `title` string, required
    - `description` string, required
    - `image` Image
      - `desktop` string — URL to use on desktop devices
      - `mobile` string — URL to use on mobile devices
      - `thumbnail` string — URL of a square version of this image
    - `applicable` boolean, required
    - `expired` boolean, required
    - `discount` Price, required — Represents an absolute monetary value in a particular currency. Cannot be negative.
      - `amount` number, required — Monetary value of this price in the given currency, with decimal point i.e. not integer format
      - `currency` string, required — ISO 4217 code for the currency in which the item's prices are sent

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `402` — Payment Required
- `404` — Not Found
- `409` — Conflict
- `410` — Gone
- `422` — Unprocessable Entity
- `500` — Internal Server Error

---

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