---
title: "Create a coupon"
method: POST
path: "/shop/coupons"
tags: ["Coupons"]
---

# Create a coupon

`POST /shop/coupons`

This endpoint creates a new coupon for an organisation.

## Request body

- object
  - `site_id` string, uuid, required — Identifier of the site this coupon is valid at. Coupons are scoped per site so each location can issue and redeem its own promotional codes. The caller's API key must have access to this site.
  - `name` string, required — Internal label for the coupon, shown to staff in the admin UI and on reports. Not customer-facing; codes issued from this coupon use a separate redemption code. 1-120 characters.
  - `description` string, nullable — A string to describe the coupon
  - `valid_weekdays` string[] — An array of weekdays which this coupon is available for use
  - `invalid_date_set_ids` string[] — An array of IDs of `DateSet`s describing when this coupon is _not_ valid. The DateSet must belong to the same organisation as the coupon.
  - `default_validity_interval` string, nullable — The default duration this coupon is valid for, as an ISO8601 string. See https://en.wikipedia.org/wiki/ISO_8601#Durations
  - `default_multi_use` boolean — The default for whether a code created from this coupon may be used multiple times
  - `for_lead_booker_only` boolean — Whether this coupon can only be used by the lead booker of a booking
  - `max_uses` integer, nullable — The maximum number of times this coupon can be used within the specified max uses period
  - `max_uses_period` 'P1D' | 'P1W' | 'P1M' | 'P1Y', nullable — The time period for usage limits when max_uses is set. The duration is specified as an ISO8601 duration string. See https://en.wikipedia.org/wiki/ISO_8601#Durations P1D = daily limit, P1W = weekly limit, P1M = monthly limit, P1Y = yearly limit
  - `redemption_type` 'manual' | 'programmatic' — The method that this coupon may be redeemed.

## Response `201`

The coupon was successfully created

- object — Single-item envelope mixin. `allOf` this into any show response that wraps its `data` payload in an outer object; the concrete schema (e.g. `ShowUser`) adds its own `data` property with the appropriate `$ref` and keeps its own title so the SDK surface is unchanged.
  - `data` Coupon, required
    - `id` string, object-id, required — The ID of the coupon
    - `name` string, required — The name of the coupon
    - `description` string, required — A string to describe the coupon
    - `locale_strings` object, nullable, required — Translations of the coupon's name and description, keyed by locale code. Managed via the coupon locale strings endpoints.
    - `offering_discounts` OfferingDiscount[], required — An array of offering_discounts belonging to this coupon. Each offering_discount describes what offerings the coupon is valid for.
      - `id` string, object-id, required — ID of the offering discount
      - `offerings` OfferingDiscountItem[], required
        - `offering_type` 'appointment' | 'package' | 'product' | 'session' | 'area_booking', required — The type of offering
        - `offering_id` string, object-id, required — The ID of the offering
        - `offering_name` string, required — The name of the offering
      - `discount_type` 'fixed_amount' | 'percentage', required — The type of discount to be applied
      - `fixed_amount` integer, required — The amount of discount to apply as an integer of the smallest unit of currency.
      - `percentage` integer, required — The percentage of discount to apply
    - `currency` string, required — The currency of any amounts to be applied.
    - `valid_weekdays` string[], required — An array of weekdays which this coupon is available for use
    - `invalid_date_set_ids` string[], required — An array of IDs of `DateSet`s describing when this coupon is _not_ valid. The DateSet must belong to the same organisation as the coupon.
    - `default_validity_interval` string, required — The default duration this coupon is valid for, as an ISO8601 string. See https://en.wikipedia.org/wiki/ISO_8601#Durations
    - `default_multi_use` boolean, required — The default for whether a code created from this coupon may be used multiple times
    - `for_lead_booker_only` boolean, required — If true, only the lead booker of an order will be able to use this coupon. If false, any guest on the order will be able to use the coupon, including non-members.
    - `max_uses` integer, nullable, required — The maximum number of times this coupon can be used within the specified max uses period
    - `max_uses_period` 'P1D' | 'P1W' | 'P1M' | 'P1Y', nullable, required — The time period for usage limits when max_uses is set. The duration is specified as an ISO8601 duration string. See https://en.wikipedia.org/wiki/ISO_8601#Durations P1D = daily limit, P1W = weekly limit, P1M = monthly limit, P1Y = yearly limit
    - `redemption_type` 'manual' | 'programmatic', required — The redemption type of the coupon.
    - `site_id` string, uuid, nullable, required — The ID of the site this coupon belongs to.
    - `created_at` string, date-time, required — The time and date that the coupon was created.
    - `updated_at` string, date-time, required — The time and date that the coupon was last updated.
    - `deleted_at` string, date-time, nullable, required — The time and date that the coupon was soft-deleted.

## Other responses

- `401` — The user is unauthenticated
- `403` — The authenticated user does not have permission.
- `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)