Coupons

Create a new coupon

Changed on
post/coupons

Request

  • Base URL: https://api.session.services
  • URL: https://api.session.services/coupons
  • Auth: API key in header x-tenant-id

Request body

couponIdstring

Duplicate of id field for GSI queries.

namestring required

Internal label for the coupon, visible to event organisers.

activeboolean

Whether this coupon is currently active.

showHiddenboolean

Whether this coupon reveals hidden admissions and sections within its scope.

kind'AMOUNT' | 'PERCENT' required

Type of discount this coupon gives: a fixed amount or a percentage.

filter'TEAM' | 'PROMOTER' | 'EVENTS' | 'SECTIONS' | 'ADMISSIONS' required

Scope of the coupon. TEAM applies to all events in the team. PROMOTER applies to all events by specified promoters. EVENTS/SECTIONS/ADMISSIONS apply to specific items.

currency'AED' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BZD' | 'CAD' | 'CHF' | 'CLP' | 'CNY' | 'COP' | 'CRC' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MNT' | 'MOP' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MYR' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SEK' | 'SGD' | 'SHP' | 'SLE' | 'SRD' | 'SVC' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'UYU' | 'UZS' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XCD' | 'XOF' | 'XPF' | 'ZAR' | 'ZMW' | 'ZWL'

Three-letter ISO 4217 currency code. Required for AMOUNT coupons. Optional for PERCENT coupons - when omitted, applies to all currencies.

discountnumber required

The discount value. If kind is 'amount', this is a currency amount. If kind is 'percent', this is a percentage.

limitnumber required

Maximum number of times the coupon can be redeemed across all customers.

usesnumber

Number of times this coupon has been redeemed so far.

orderLimitinteger

Maximum number of admission units this coupon can discount within a single order. Omit to discount every eligible unit.

membersOnlyboolean

Whether this coupon can only be redeemed by a signed-in user holding an active membership pass for the coupon's team.

saleStartsAtstring required

Wall clock time when this coupon becomes valid (no timezone, ISO 8601 format: YYYY-MM-DDTHH:mm:ss)

saleEndsAtstring

Wall clock time when this coupon expires (no timezone, ISO 8601 format: YYYY-MM-DDTHH:mm:ss)

teamIdstring required

Team that created this coupon.

Example request

{
  "couponId": "cpn_01jps5cgsfzs1ksqaet5hba8ac",
  "name": "Half Price",
  "active": true,
  "kind": "PERCENT",
  "filter": "EVENTS",
  "currency": "AUD",
  "discount": 50,
  "limit": -1,
  "orderLimit": 2,
  "saleStartsAt": "2025-02-10T03:00:00"
}

Response

OK

Example response

{
  "coupon": {
    "id": "cpn_01jps5cgsfzs1ksqaet5hba8ac",
    "couponId": "cpn_01jps5cgsfzs1ksqaet5hba8ac",
    "createdAt": "2026-10-17T08:46:46.697Z",
    "updatedAt": "2026-10-17T08:46:46.697Z",
    "name": "Half Price",
    "active": true,
    "kind": "PERCENT",
    "filter": "EVENTS",
    "currency": "AUD",
    "discount": 50,
    "limit": -1,
    "orderLimit": 2,
    "saleStartsAt": "2025-02-10T03:00:00"
  }
}

Changes

  • 6369738f4d43Revision changes
    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

  • 84f157e4443aRevision changes
    • info

      added the non-success response with the status