Promo Codes

Promo code CRUD — discount for ticket classes, org/event scoped, write needs confirm via MCP

get

List promo codes for an event — paginated, filterable by codeName substring and isActive. Requires organizer_api_token read, org or event scoped. Excludes soft-deleted rows.

Authorizations

AuthorizationstringRequired

Organizer API token — Authorization: Bearer evtx_live_… (Org/Event scoped, read/write).

Path parameters

eventIdstring · uuidRequiredExample: aaff0556-85b5-4ac4-a484-486c7f319c08

Query parameters

limitinteger · min: 1 · max: 100OptionalDefault: 50Example: 50

offsetinteger · nullableOptionalDefault: 0Example: 0

qstringOptional

Filter by codeName substring (case-insensitive)

Example: SUMMER

isActiveboolean · nullableOptionalExample: true

Responses

200

Paginated promo codes

application/json

totalnumberRequiredExample: 10

limitnumberRequiredExample: 50

offsetnumberRequiredExample: 0

401

Unauthorized

application/json

403

Forbidden

application/json

404

Event not found

application/json

get/v2/events/{eventId}/promo-codes

GET /v2/events/{eventId}/promo-codes HTTP/1.1
Host: api.eventx.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "id": "b2e7c3a1-4f5e-4b2a-9c1d-1234567890ab",
      "eventId": "aaff0556-85b5-4ac4-a484-486c7f319c08",
      "codeName": "SUMMER2026",
      "remarks": "Early bird",
      "discountType": "subtractByPercentage",
      "discount": "100.00",
      "discountRate": "20.00",
      "quota": 100,
      "isActive": true,
      "isAppliedToAllTicketClasses": true,
      "ticketClassIds": [
        "550e8400-e29b-41d4-a716-446655440011"
      ],
      "startDate": "2026-03-01T00:00:00.000Z",
      "endDate": "2026-04-01T00:00:00.000Z",
      "timezone": "Asia/Hong_Kong",
      "createdAt": "2026-01-15T02:00:00.000Z",
      "updatedAt": "2026-01-15T02:00:00.000Z"
    }
  ],
  "total": 10,
  "limit": 50,
  "offset": 0
}

post

Create promo code — event-create allowed for event-scoped token (token.eventId must match). Validates discount range, price, and ticketClass ownership. Requires write.

Authorizations

AuthorizationstringRequired

Organizer API token — Authorization: Bearer evtx_live_… (Org/Event scoped, read/write).

Path parameters

eventIdstring · uuidRequiredExample: aaff0556-85b5-4ac4-a484-486c7f319c08

Body

Create promo code — requires organizer_api_token write, org or event scoped (event-create allowed). Validates discount range and ticket class scope.

codeNamestring · min: 1 · max: 100Required

Unique per event, required

Example: SUMMER2026

remarksstring · max: 500 · nullableOptionalExample: Early bird

discountTypestring · enumRequired

Discount type, required

Example: subtractByPercentagePossible values:

discountstring · nullableOptional

Fixed amount string; required for subtractByFixedAmount/chargeByFixedAmount

Example: 50.00

discountRatestring · nullableOptional

Percentage 0-100 string; for subtractByPercentage

Example: 20.00

quotainteger · min: 1 · nullableOptional

Max redemptions; null = unlimited

Example: 100

isActivebooleanOptional

Active flag, defaults to true

Example: true

isAppliedToAllTicketClassesbooleanRequired

If true, ticketClassIds is ignored

Example: true

ticketClassIdsstring · uuid[]Optional

Ticket class IDs when isAppliedToAllTicketClasses=false

Example: ["550e8400-e29b-41d4-a716-446655440011"]

startDatestringRequired

ISO start, required

Example: 2026-03-01T00:00:00.000Z

endDatestring · nullableOptional

ISO end, null = no expiry

Example: 2026-04-01T00:00:00.000Z

timezonestring · min: 1Required

IANA timezone, required

Example: Asia/Hong_Kong

Responses

201

Created

application/json

Promo code row — scoped by organizer_api_token (Org or Event, not user). Discount affects ticket pricing; PATCH is human-confirmed via MCP.

idstring · uuidRequired

Promo code ID, UUID

Example: b2e7c3a1-4f5e-4b2a-9c1d-1234567890ab

eventIdstring · nullableRequired

Event ID

Example: aaff0556-85b5-4ac4-a484-486c7f319c08

codeNamestring · nullableRequired

Human-readable code name, unique per event

Example: SUMMER2026

remarksstring · nullableRequired

Internal remarks

Example: Early bird

discountTypestring · nullableRequired

subtractByPercentage | subtractByFixedAmount | chargeByFixedAmount

Example: subtractByPercentage

discountstring · nullableRequired

Fixed amount string, for subtractByFixedAmount/chargeByFixedAmount

Example: 100.00

discountRatestring · nullableRequired

Percentage string 0-100, for subtractByPercentage

Example: 20.00

quotanumber · nullableRequired

Max redemptions, null = unlimited

Example: 100

isActiveboolean · nullableRequired

Whether code is currently active

Example: true

isAppliedToAllTicketClassesboolean · nullableRequired

If true, applies to all ticket classes; otherwise ticketClassIds lists scope

Example: true

ticketClassIdsstring · uuid[]Required

Ticket class IDs this code applies to (empty when isAppliedToAllTicketClasses=true)

Example: ["550e8400-e29b-41d4-a716-446655440011"]

startDatestring · nullableRequired

Start time ISO

Example: 2026-03-01T00:00:00.000Z

endDatestring · nullableRequired

End time ISO, null = no expiry

Example: 2026-04-01T00:00:00.000Z

timezonestring · nullableRequired

IANA timezone for start/end display

Example: Asia/Hong_Kong

createdAtstring · nullableRequiredExample: 2026-01-15T02:00:00.000Z

updatedAtstring · nullableRequiredExample: 2026-01-15T02:00:00.000Z

400

Validation error

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Event or ticket class not found

application/json

post/v2/events/{eventId}/promo-codes

POST /v2/events/{eventId}/promo-codes HTTP/1.1
Host: api.eventx.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 237

{
  "codeName": "SUMMER2026",
  "discountType": "subtractByPercentage",
  "discountRate": "20.00",
  "quota": 100,
  "isAppliedToAllTicketClasses": true,
  "startDate": "2026-03-01T00:00:00.000Z",
  "endDate": "2026-04-01T00:00:00.000Z",
  "timezone": "Asia/Hong_Kong"
}

{
  "id": "b2e7c3a1-4f5e-4b2a-9c1d-1234567890ab",
  "eventId": "aaff0556-85b5-4ac4-a484-486c7f319c08",
  "codeName": "SUMMER2026",
  "remarks": "Early bird",
  "discountType": "subtractByPercentage",
  "discount": "100.00",
  "discountRate": "20.00",
  "quota": 100,
  "isActive": true,
  "isAppliedToAllTicketClasses": true,
  "ticketClassIds": [
    "550e8400-e29b-41d4-a716-446655440011"
  ],
  "startDate": "2026-03-01T00:00:00.000Z",
  "endDate": "2026-04-01T00:00:00.000Z",
  "timezone": "Asia/Hong_Kong",
  "createdAt": "2026-01-15T02:00:00.000Z",
  "updatedAt": "2026-01-15T02:00:00.000Z"
}

get

Get single promo code by ID, scoped to event. Requires read.

Authorizations

AuthorizationstringRequired

Organizer API token — Authorization: Bearer evtx_live_… (Org/Event scoped, read/write).

Path parameters

eventIdstring · uuidRequiredExample: aaff0556-85b5-4ac4-a484-486c7f319c08

promoCodeIdstring · uuidRequiredExample: b2e7c3a1-4f5e-4b2a-9c1d-1234567890ab

Responses

200

Promo code

application/json

Promo code row — scoped by organizer_api_token (Org or Event, not user). Discount affects ticket pricing; PATCH is human-confirmed via MCP.

idstring · uuidRequired

Promo code ID, UUID

Example: b2e7c3a1-4f5e-4b2a-9c1d-1234567890ab

eventIdstring · nullableRequired

Event ID

Example: aaff0556-85b5-4ac4-a484-486c7f319c08

codeNamestring · nullableRequired

Human-readable code name, unique per event

Example: SUMMER2026

remarksstring · nullableRequired

Internal remarks

Example: Early bird

discountTypestring · nullableRequired

subtractByPercentage | subtractByFixedAmount | chargeByFixedAmount

Example: subtractByPercentage

discountstring · nullableRequired

Fixed amount string, for subtractByFixedAmount/chargeByFixedAmount

Example: 100.00

discountRatestring · nullableRequired

Percentage string 0-100, for subtractByPercentage

Example: 20.00

quotanumber · nullableRequired

Max redemptions, null = unlimited

Example: 100

isActiveboolean · nullableRequired

Whether code is currently active

Example: true

isAppliedToAllTicketClassesboolean · nullableRequired

If true, applies to all ticket classes; otherwise ticketClassIds lists scope

Example: true

ticketClassIdsstring · uuid[]Required

Ticket class IDs this code applies to (empty when isAppliedToAllTicketClasses=true)

Example: ["550e8400-e29b-41d4-a716-446655440011"]

startDatestring · nullableRequired

Start time ISO

Example: 2026-03-01T00:00:00.000Z

endDatestring · nullableRequired

End time ISO, null = no expiry

Example: 2026-04-01T00:00:00.000Z

timezonestring · nullableRequired

IANA timezone for start/end display

Example: Asia/Hong_Kong

createdAtstring · nullableRequiredExample: 2026-01-15T02:00:00.000Z

updatedAtstring · nullableRequiredExample: 2026-01-15T02:00:00.000Z

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

get/v2/events/{eventId}/promo-codes/{promoCodeId}

GET /v2/events/{eventId}/promo-codes/{promoCodeId} HTTP/1.1
Host: api.eventx.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "b2e7c3a1-4f5e-4b2a-9c1d-1234567890ab",
  "eventId": "aaff0556-85b5-4ac4-a484-486c7f319c08",
  "codeName": "SUMMER2026",
  "remarks": "Early bird",
  "discountType": "subtractByPercentage",
  "discount": "100.00",
  "discountRate": "20.00",
  "quota": 100,
  "isActive": true,
  "isAppliedToAllTicketClasses": true,
  "ticketClassIds": [
    "550e8400-e29b-41d4-a716-446655440011"
  ],
  "startDate": "2026-03-01T00:00:00.000Z",
  "endDate": "2026-04-01T00:00:00.000Z",
  "timezone": "Asia/Hong_Kong",
  "createdAt": "2026-01-15T02:00:00.000Z",
  "updatedAt": "2026-01-15T02:00:00.000Z"
}

delete

Soft delete — sets deletedAt, keeps assignment rows. Requires write.

Authorizations

AuthorizationstringRequired

Organizer API token — Authorization: Bearer evtx_live_… (Org/Event scoped, read/write).

Path parameters

eventIdstring · uuidRequiredExample: aaff0556-85b5-4ac4-a484-486c7f319c08

promoCodeIdstring · uuidRequiredExample: b2e7c3a1-4f5e-4b2a-9c1d-1234567890ab

Responses

204

Deleted

No content

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

delete/v2/events/{eventId}/promo-codes/{promoCodeId}

DELETE /v2/events/{eventId}/promo-codes/{promoCodeId} HTTP/1.1
Host: api.eventx.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

patch

Partial update — at least one field. codeName rename checks duplicate per event. Validates discount/price/ticket scope. Requires write and human confirmation when via MCP (confirm:true). Best-effort duplicate race.

Authorizations

AuthorizationstringRequired

Organizer API token — Authorization: Bearer evtx_live_… (Org/Event scoped, read/write).

Path parameters

eventIdstring · uuidRequiredExample: aaff0556-85b5-4ac4-a484-486c7f319c08

promoCodeIdstring · uuidRequiredExample: b2e7c3a1-4f5e-4b2a-9c1d-1234567890ab

Body

Partial update — at least one field required. codeName rename checks duplicate. Requires human confirmation via MCP confirm:true.

codeNamestring · min: 1 · max: 100OptionalExample: SUMMER2026-V2

remarksstring · max: 500 · nullableOptionalExample: Updated remarks

discountTypestring · enumOptionalExample: subtractByFixedAmountPossible values:

discountstring · nullableOptionalExample: 50.00

discountRatestring · nullableOptionalExample: 15.00

quotainteger · min: 1 · nullableOptionalExample: 200

isActivebooleanOptionalExample: false

isAppliedToAllTicketClassesbooleanOptionalExample: false

ticketClassIdsstring · uuid[]OptionalExample: ["550e8400-e29b-41d4-a716-446655440011"]

startDatestringOptionalExample: 2026-03-02T00:00:00.000Z

endDatestring · nullableOptionalExample: 2026-04-01T00:00:00.000Z

timezonestringOptionalExample: Asia/Hong_Kong

Responses

200

Updated

application/json

Promo code row — scoped by organizer_api_token (Org or Event, not user). Discount affects ticket pricing; PATCH is human-confirmed via MCP.

idstring · uuidRequired

Promo code ID, UUID

Example: b2e7c3a1-4f5e-4b2a-9c1d-1234567890ab

eventIdstring · nullableRequired

Event ID

Example: aaff0556-85b5-4ac4-a484-486c7f319c08

codeNamestring · nullableRequired

Human-readable code name, unique per event

Example: SUMMER2026

remarksstring · nullableRequired

Internal remarks

Example: Early bird

discountTypestring · nullableRequired

subtractByPercentage | subtractByFixedAmount | chargeByFixedAmount

Example: subtractByPercentage

discountstring · nullableRequired

Fixed amount string, for subtractByFixedAmount/chargeByFixedAmount

Example: 100.00

discountRatestring · nullableRequired

Percentage string 0-100, for subtractByPercentage

Example: 20.00

quotanumber · nullableRequired

Max redemptions, null = unlimited

Example: 100

isActiveboolean · nullableRequired

Whether code is currently active

Example: true

isAppliedToAllTicketClassesboolean · nullableRequired

If true, applies to all ticket classes; otherwise ticketClassIds lists scope

Example: true

ticketClassIdsstring · uuid[]Required

Ticket class IDs this code applies to (empty when isAppliedToAllTicketClasses=true)

Example: ["550e8400-e29b-41d4-a716-446655440011"]

startDatestring · nullableRequired

Start time ISO

Example: 2026-03-01T00:00:00.000Z

endDatestring · nullableRequired

End time ISO, null = no expiry

Example: 2026-04-01T00:00:00.000Z

timezonestring · nullableRequired

IANA timezone for start/end display

Example: Asia/Hong_Kong

createdAtstring · nullableRequiredExample: 2026-01-15T02:00:00.000Z

updatedAtstring · nullableRequiredExample: 2026-01-15T02:00:00.000Z

400

Validation

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

patch/v2/events/{eventId}/promo-codes/{promoCodeId}

PATCH /v2/events/{eventId}/promo-codes/{promoCodeId} HTTP/1.1
Host: api.eventx.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 364

{
  "codeName": "SUMMER2026-V2",
  "remarks": "Updated remarks",
  "discountType": "subtractByFixedAmount",
  "discount": "50.00",
  "discountRate": "15.00",
  "quota": 200,
  "isActive": false,
  "isAppliedToAllTicketClasses": false,
  "ticketClassIds": [
    "550e8400-e29b-41d4-a716-446655440011"
  ],
  "startDate": "2026-03-02T00:00:00.000Z",
  "endDate": "2026-04-01T00:00:00.000Z",
  "timezone": "Asia/Hong_Kong"
}

{
  "id": "b2e7c3a1-4f5e-4b2a-9c1d-1234567890ab",
  "eventId": "aaff0556-85b5-4ac4-a484-486c7f319c08",
  "codeName": "SUMMER2026",
  "remarks": "Early bird",
  "discountType": "subtractByPercentage",
  "discount": "100.00",
  "discountRate": "20.00",
  "quota": 100,
  "isActive": true,
  "isAppliedToAllTicketClasses": true,
  "ticketClassIds": [
    "550e8400-e29b-41d4-a716-446655440011"
  ],
  "startDate": "2026-03-01T00:00:00.000Z",
  "endDate": "2026-04-01T00:00:00.000Z",
  "timezone": "Asia/Hong_Kong",
  "createdAt": "2026-01-15T02:00:00.000Z",
  "updatedAt": "2026-01-15T02:00:00.000Z"
}

PreviousAttendee Addons

NextCustom Fields

Last updated 13 hours ago

List promo codes

Create promo code

Get promo code

Delete promo code

Patch promo code