API · Promoters

Promoters are ordinary team memberships with role promoter. 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 and promoter sessions cannot read this account-wide endpoint.

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