Promo codes and invitations

Configure event promotions and issue invitations with explicit recipient results.

Read used-code labels

GET /{event_id}/promocodes/all_data.json and GET /promocodes/all_data.json return cached maps from code UUID to visible code, scoped to event or accessible companies. The query includes codes referenced by orders; unused configured codes do not appear. An empty map can serialize as []. Use validators to handle 304 responses.

The legacy promocodes/index.json list produced malformed JSON during local discovery: PHP notices and HTML appeared despite a JSON content type and HTTP 200. It is excluded from the supported JSON reference. There is currently no advertised full promo-detail catalog endpoint; use the organizer promotion view for that workflow.

Create and edit

POST /{event_id}/promocodes/add/{type}.json creates a single code. Types are products (product-specific price) and prd_prct (percentage, using Promocode.discount). Submit Promocode plus event-owned ProductsPromocode rows.

{
  "Promocode":{"code":"WELCOME","active":1,"stock":100},
  "ProductsPromocode":[{"product_id":"22222222-2222-4222-8222-222222222222","active":1,"max":1,"price":"0.00"}]
}

Code length is at most 25 characters. Other allowed settings include discount, expiry, budget, guaranteed stock, invoice allowance and hiding other products. Product links use product_id, active, max and price. A promo link's zero maximum has different semantics from the waiting-list invitation's required 1–50 amount.

PUT /{event_id}/promocodes/edit/{promocode_id}.json edits an authorized code with the same envelopes. Single-code create/edit success returns {"ok":true,"id":"..."}. Validation and save failures have JSON error handling. Batch code_amount creation uses a legacy success redirect and is not part of this single-code result contract.

Activate or remove

PUT /{event_id}/promocodes/activate/{promocode_id}.json, deactivate/{promocode_id}.json or delete/{promocode_id}.json. Referenced codes can be protected from deletion. Inspect ok/error even on HTTP 200. Bulk deletion and company-wide promotion forms retain separate legacy rendering and need their own response verification.

Invite recipients

Read GET /{event_id}/promocode_invites/view/{promocode_id}.json for MailQues history (up to 500 rows), limit and remaining. POST /{event_id}/promocode_invites/add/{promocode_id}.json with recipient rows.

{"invites":[{"firstname":"Alex","lastname":"Example","email":"alex@example.com"}]}

Firstname and a valid email are required. At most 100 recipients are accepted per request; duplicate email addresses are rejected. An organization awaiting clearance can have a three-invitation organization-wide allowance.

The result contains status (ok, partial, error), queued, queued_indices, rejected, message, limit and remaining. Rejected rows have an index/reason. Correct and resend only rejected rows; don't resend recipients already queued. A wholly rejected validation request can return 422 and a storage failure 500. Queue acceptance does not prove delivery.

For invitations linked to waiting-list entries, use waiting-list invitations so prior invitation codes and entry links are updated together.

Company and batch workflows

The coverage table records company-wide promo management, batch creation and full-catalog limits. Create individual event codes when you need a structured returned ID; keep that ID because used-label maps exclude unused codes.