Skip to content

Custom API

Discounts and coupons

Reference only. Not a decision unless cited in product/DECISIONS.md.

Discounts and coupons

Organizers set up two kinds of discount. AXYN owns creation, management and redemption; distributing a code (social posts, emails, printed cards) is yours.

  • Automatic discounts have no code. They apply by quantity of one ticket type, for example "2 for $6,000" on a series pass or "4+ save 10% each".
  • Discount codes are entered by the buyer at checkout.

Either kind belongs to one show (venue_event_id) or to a whole series (production_id). A series discount covers the series' passes and the ticket types of every show in it. A show discount never covers a pass.

Automatic discounts

SettingValues
NameShown to buyers, up to 60 characters (display_name)
Applies toListed ticket types (tier_ids), or all in scope when empty
Triggerper_group: every complete group of N of one ticket type is discounted and leftovers pay full price. threshold: once the order has N or more of one type, all of them are discounted
Nmin_quantity, 2 to 50
Discountpercent_bps (1 to 9500) off each, amount_cents off each (less than the price), or group_price_cents for one group (per_group only; less than N × the price)
WindowOptional starts_at / ends_at
LimitOptional max_redemptions (orders). Empty means unlimited

How they apply:

  • Per ticket type. Different ticket types never form a group, and $0 tickets never count. Reserved seats count across their lines.
  • Series first. If a series discount on a ticket type fires, the best one applies and show discounts are not considered for it. A series discount that doesn't fire (the quantity is under its N) never blocks a show one.
  • Set price. With "2 for $6,000" on a $3,300 pass, 1, 2 and 3 passes cost $3,300, $6,000 and $9,300. Each ticket's paid amount is its share of its group, so a refund of one of a pair returns $3,000.
  • Code or automatic, never both. When a buyer enters a code on a cart an automatic discount already covers, the one that saves more is charged (a tie goes to the automatic one). A code that loses is accepted but not redeemed, and the preview says code_not_applied_reason: "automatic_better".
  • Never an error. If the order floor or a used-up limit stops an automatic discount, the order simply prices without it (or with less).
  • Automatic discounts apply on hosted checkout, the web-sdk embed, Partner /v1 orders and the box office, and to waitlist offers. They never apply to comps or allocation links.

Discount codes

  • Value: percent off (max 95%) or a fixed amount off ticket face value. Add-ons are never discounted.
  • Apply mode (fixed amount): cart_ticket_subtotal (default) takes the amount off the combined ticket face once; per_ticket multiplies amount_cents by ticket quantity.
  • Coverage: a show code with no tier_ids covers the whole cart, exactly as before. A code with tier_ids, or any series code, covers only those lines. If a series code and a show code cover the same line, the series code takes it.
  • Unique across a series. A code active on a series can't also be active on one of its shows, and the other way round (409 coupon_code_in_use, with detail naming where it's used). Attaching a show to a series is refused while their codes clash.
  • Limit: a total number of uses (max_redemptions, required) and an optional start/end window. Stacking stays per-tier opt-in (ticket_tiers.allow_multiple_coupons, default off).

Money rules (both kinds)

  • The discount is computed inside the same atomic order engine as everything else. The AXYN platform fee stays on the face ticket price; card processing and sales tax follow the discounted amount.
  • Floor: a buyer always pays at least 5% of the ticket value and at least $5 of it. The discount clamps to min(95% of ticket subtotal, ticket subtotal − $5). For codes, carts at or under $5 of ticket value reject with coupon_not_applicable. Free tickets are comps, never discounts.
  • Price is locked at order create. Switching a discount off never re-prices a held or paid order.

Organizer admin

Event → Setup → Discounts, and Series → Setup → Make it sell → Discounts. Each has an Automatic discounts list and a Discount codes list. A show that a series discount already covers shows a notice naming it.

Deleting a ticket type removes it from any discount's list. A discount left with no ticket types is switched off, never widened to everything.

Values never change after saving. A code can only be switched off, and that is permanent. An automatic discount can be switched off and on again. Delete is possible only while nothing has used it.

Sales Control Center: event Sales promo_mix[] lists each discount by name or code with orders, tickets, discount and You keep.

API

Organizer CRUD (staff JWT with event.write, or a catalog:write API key — reads too; codes never leak through buyer-facing read keys):

MethodPath
GET/v1/events/{eventId}/coupons
POST/v1/events/{eventId}/coupons
GET/v1/productions/{productionId}/coupons
POST/v1/productions/{productionId}/coupons
PATCH/v1/events/coupons/{couponId}
DELETE/v1/events/coupons/{couponId}

Create an automatic discount with redemption_mode: "automatic", display_name, quantity_mode, min_quantity and one of percent_bps, amount_cents or group_price_cents. Refusals are 400 with field naming the input. A 201 may carry warnings: ["below_order_floor"] when a price would push an order under the $5 floor. PATCH accepts only {"is_active": false} for codes and true or false for automatic discounts.

Buyers:

  • Catalog ticket types (GET /v1/events/{eventId}/tiers and the production catalog) carry offers[], so a ticket card can say "Buy 2 for $6,000 (save $600)" before a quantity is picked.
  • POST /v1/orders/preview-total and POST /v1/orders take an optional coupon_codes array (max 5, distinct) and apply automatic discounts with no input. The preview returns discount_cents, discount_lines[] (one per source per ticket type), offer_hints[] ("add 1 more to save $600"), code_not_applied_reason and codes_not_applied.
  • GET /v1/orders/{orderId} returns discounts[], one per applied discount.

Redemption counters increment atomically inside order create for codes and limited automatic discounts, and return to the pool when a reservation expires or is cancelled before payment. Unlimited automatic discounts are never counted. Paid orders keep their redemptions; refunds do not restore them.

Typed 400 error codes (codes only): coupon_not_found, coupon_inactive, coupon_not_started, coupon_exhausted, coupon_not_applicable, coupon_below_minimum_charge, coupon_duplicate, coupon_stacking_not_allowed. An expired code answers coupon_not_found, the same as a code that does not exist.

In the SDK

@axyn/web-sdk shows offers on ticket cards, one discount line per source in the pay summary (announced to screen readers), "add N more" hints, and the code input on the review step (embed drawer and hosted checkout). Headless integrations send coupon_codes themselves and read the fields above — see How headless works.

Confirm every field against $AXYN_BASE_URL/openapi.json.