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,
      "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: integer 1–100. For fixed: amount in your account’s currency.
event_id	no	Restrict to a single event. Omit (or null) for account-wide.
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.

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.

Promo code fields

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.
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.