API · Promo codes

Promo codes are discount codes that buyers enter at checkout (or pre-apply via ?promo=ABC on any shop URL). Each code is account-scoped, and you choose whether it discounts by percentage or a fixed amount, whether it’s restricted to a single event, and how many total or per-customer redemptions are allowed.

`GET /admin/promo_codes`

Lists all promo codes on your account, newest first.

curl -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  https://app.usetix.io/admin/promo_codes

Response:

{
  "promo_codes": [
    {
      "id": 17,
      "code": "NEWS10",
      "discount_type": "percentage",
      "discount_amount": "10.0",
      "event_id": null,
      "event_title": null,
      "expires_at": null,
      "usage_limit": null,
      "max_per_customer": 1,
      "redemptions_count": 42,
      "active": true,
      "promoter_membership_id": null,
      "share_url": "https://example.usetix.io?promo=NEWS10",
      "created_at": "2026-04-01T10:15:00Z",
      "updated_at": "2026-05-10T18:42:00Z"
    }
  ]
}

`GET /admin/promo_codes/:id`

Returns a single promo code.

curl -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  https://app.usetix.io/admin/promo_codes/17

Response: 200 OK with the promo code JSON.

`POST /admin/promo_codes`

Creates a new promo code.

curl -X POST \
  -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"promo_code": {"code": "FALL2026", "discount_type": "percentage", "discount_amount": 15, "max_per_customer": 1}}' \
  https://app.usetix.io/admin/promo_codes

Body parameters:

Field	Required	Notes
`code`	yes	3, 32 characters, A, Z / 0, 9 / dash. Case-insensitive; stored and returned uppercased. Unique within your account.
`discount_type`	yes	`percentage` or `fixed`.
`discount_amount`	yes	For `percentage`: 0–100. For `fixed`: nonnegative amount in your account’s currency. Zero records the code without reducing the price.
`event_id`	no	Restrict to a single event, including within mixed-event carts. Omit (or `null`) for account-wide.
`promoter_membership_id`	no	Promoter membership on this account; `null` clears an unused assignment. Venue owner/manager or organizer account token only.
`expires_at`	no	ISO 8601 datetime. After this, the code stops applying.
`usage_limit`	no	Total redemption cap across all buyers. Soft-limit: high-concurrency near-cap orders may slip past by a small margin.
`max_per_customer`	no	Cap per buyer (matched by email). Refunded orders free up a use.
`active`	no	Defaults to `true`. Set `false` to disable a code without deleting it.

Response: 201 Created with the promo code JSON and a Location header. 422 Unprocessable Entity with { "errors": { "field": ["..."] } } on validation failure.

`PATCH /admin/promo_codes/:id`

Updates a promo code. Send only the fields you want to change. Once a code has a checkout reservation or paid sale, changing its event or promoter returns 422. Use a new code for a new assignment. Deactivating a promoter membership also blocks new uses of its codes. See Promoters.

curl -X PATCH \
  -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"promo_code": {"discount_amount": 20}}' \
  https://app.usetix.io/admin/promo_codes/17

Response: 200 OK with the updated promo code JSON.

`DELETE /admin/promo_codes/:id`

Deletes a promo code. If the code has redemptions on paid orders, we soft-deactivate it (so order history keeps its association) and return the updated JSON. Codes with zero redemptions are hard-deleted.

curl -X DELETE \
  -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  https://app.usetix.io/admin/promo_codes/17

Response:

204 No Content if hard-deleted.
200 OK with the updated promo code JSON (and "active": false) if soft-deactivated.

Field	Type	Notes
`id`	integer
`code`	string	Always uppercased.
`discount_type`	string	`percentage` or `fixed`.
`discount_amount`	string	Decimal string. For percentage, `"10.0"` means 10 %. For fixed, the value is in your account currency.
`event_id`	integer / null
`event_title`	string / null	Convenience copy of the event’s title for display.
`promoter_membership_id`	integer / null	Assigned promoter membership.
`share_url`	string	Shop or event URL with `?promo=CODE`.
`expires_at`	string / null	ISO 8601 UTC.
`usage_limit`	integer / null
`max_per_customer`	integer / null
`redemptions_count`	integer	Incremented on each paid order. Not decremented on refund.
`active`	boolean
`created_at` / `updated_at`	string	ISO 8601 UTC.

How buyers redeem a code

Buyers can type the code in the checkout form, or you can give them a link with ?promo=CODE appended, Usetix captures it into their session so the discount is pre-applied at checkout. Codes are silently ignored on the public shop if invalid; buyers only see an error if they explicitly type one that doesn’t match.

Program-managed codes

Promoter programs assign organizer-chosen personal codes. Their responses include promoter_program_id and event_ids. Use these fields for scope: a null legacy event_id does not imply shop-wide eligibility for a program code. Rename personal codes here, but edit their shared discount, limits, expiry and event selection on the program. Independent changes to those fields return 422. Removing a program code deactivates it even before the first sale, so reassigning the person reuses the same code.

Creation supports an optional Idempotency-Key header. See Idempotent creates for replay, retention and conflict behavior.

GET /admin/promo_codes

GET /admin/promo_codes/:id

POST /admin/promo_codes

PATCH /admin/promo_codes/:id

DELETE /admin/promo_codes/:id

Promo code fields