API · Promoters

Promoters are ordinary team memberships with role promoter. For reusable terms and organizer-chosen personal codes, use Promoter programs. Their codes are existing promo codes with promoter_membership_id set. A zero discount attributes sales without changing prices. See the promoter guide for the full workflow and revenue definitions.

`GET /admin/promoters`

Use an organizer account Bearer token and Accept: application/json. Personal co-organizer tokens return only promoters and codes accessible through their assigned events. Shop-wide and partly inaccessible programs are excluded. Sales are limited to currently assigned events, including historical program sales; requesting an unassigned event returns 404. Promoter sessions cannot read this endpoint.

Results are ordered by tickets_sold descending for the selected event and period, with alphabetical name ties.

Optional query parameters:

Parameter	Values
`event_id`	An event covered by the promoter codes on this account. Foreign or unavailable events return `404`.
`period`	`today`, `week`, `month`, `year`, `all` (default). Uses purchase time in the account timezone.

{
  "promoters": [
    {
      "membership_id": 42,
      "name": "Lisa",
      "email": "lisa@example.com",
      "state": "active",
      "tickets_sold": 12,
      "revenue": { "amount": "240.0", "currency": "EUR" },
      "promo_codes": [
        {
          "id": 17,
          "code": "LISA-SUMMER",
          "event_id": 23,
          "active": true,
          "removed_at": null,
          "share_url": "https://example.usetix.io/events/summer?promo=LISA-SUMMER",
          "tickets_sold": 12,
          "revenue": { "amount": "240.0", "currency": "EUR" }
        }
      ]
    }
  ]
}

Includes active and deactivated promoter memberships, plus former promoters whose codes retain sales history. Code arrays and totals follow the filters. Historical codes remain in the report after removal. Each code exposes active (the personal code flag), removed_at (UTC timestamp or null), and share_url (null when the code, program, or promoter is inactive, the assignment is removed, the code is expired, or its redemption limit is reached). Use only non-null sharing URLs. Program codes additionally expose promoter_program_id (public ID) and event_ids; do not infer their scope from legacy event_id. Purchased event attribution stays unchanged when a program scope changes. Buyer data and individual orders are not part of this report. Refunds update the revenue of the original purchase period.

Organizers can filter draft and unlisted events covered by their codes. The promoter’s personal dashboard has a narrower event filter: explicitly assigned code events, plus published and publicly listed events with paid ticket sales through their account-wide codes.

Invite and assign

Invite through POST /admin/invitations with {"invitation":{"email":"lisa@example.com","role":"promoter"}}. After acceptance, retrieve the membership ID from Memberships and create or update an unused code with promoter_membership_id: 42. Set discount_amount: 0 for tracking without a discount. Writes require an organizer write token.

Promoters use their session-based personal dashboard at /promoter. This release does not issue personal API tokens or MCP access to promoter memberships.