Sopmi

Sopmi Ticket API

Connect your ticketing platform to Sopmi so that event organizers can reward their ambassadors for every ticket they sell.

Overview

Sopmi is an ambassador platform for events. Organizers run ticket missions: each ambassador gets a personal code, shares it with friends and followers, and earns points for every ticket sold with that code. Points are later exchanged for rewards.

Your platform sells the tickets, so you know which code was used. This API lets you:

You never receive personal data about ambassadors, and Sopmi never needs personal data about ticket buyers. A code and an order ID are enough.

How it works

1. KeyThe organizer creates an API key in Sopmi (Integrations, Ticket API) and gives it to you.
2. CodesYou fetch the codes of the organizer's ticket missions and make them valid in the shop.
3. SaleWhen an order with a code is paid, you report it. Sopmi credits the ambassador.
4. RefundWhen that order is refunded or cancelled, you report it. Sopmi reverses the points.

Base URL: https://api.sopmi.app/v1. All requests and responses are JSON over HTTPS.

Authentication

Every request needs the organizer's API key in the Authorization header:

Authorization: Bearer spk_3f9a…(68 characters in total)

Each key belongs to exactly one organizer and only gives access to that organizer's missions, codes and sales. If you work for several organizers, store one key per organizer.

Keys are never accepted in the URL. A request with ?key= is rejected, so keys do not end up in logs.

Security

  • Keys are stored as a SHA-256 hash. Sopmi shows a key once when it is created. Lost keys cannot be recovered; the organizer creates a new one.
  • Revocable. The organizer can revoke a key at any time. Requests with a revoked key return 401 immediately.
  • Least privilege. A key can only read codes and report sales and refunds for its own organizer. It cannot read ambassadors' names, emails or points.
  • Server to server only. The API sends no CORS headers. Never put a key in a browser, app or public repository.
  • Idempotent. Sales are unique per order_id. Retrying the same request never credits points twice.
  • Brute-force protection. After 20 requests with an invalid key from the same IP address within a minute, further invalid requests get 429. Valid keys are never blocked by this, so one revoked key cannot take down your other organizers. IP addresses are stored only as a hash.
  • Strict input. Unknown endpoints, wrong methods, non-JSON bodies and bodies over 16 KB are rejected before any data is touched.

Found a security issue? Tell the organizer you work with, so they can report it to Sopmi through the Sopmi helpdesk.

Rate limits

Each key can make 120 requests per minute. Every response includes:

HeaderMeaning
X-RateLimit-LimitRequests allowed per minute (120).
X-RateLimit-RemainingRequests left in the current minute.
Retry-AfterOnly on 429 and 503: seconds to wait before retrying.
X-Request-IdUnique ID of the request. Include it when you contact support.

Requests with an invalid key are limited to 20 per minute per IP address. Requests with a valid key only count towards that key's own limit.

Recommended retry policy: retry 429, 500 and 503 with exponential backoff (for example 1, 2, 4, 8 seconds, at most 5 attempts). Do not retry other 4xx responses; fix the request instead. Because sales are idempotent, retrying a sale is always safe.

Errors

Errors always have the same shape:

{
  "error": { "code": "invalid_request", "message": "order_id is required (max 200 characters)." },
  "request_id": "6c1f2c8e-3f0a-4c8f-9a51-2f9a1c0b7d11"
}
StatusCodeWhen
400invalid_requestA field is missing or invalid, or the key was sent in the URL.
401unauthorizedThe key is missing, invalid or revoked.
404not_foundUnknown endpoint, mission, code or order for this organizer.
405method_not_allowedThe endpoint exists but not with this HTTP method.
413payload_too_largeThe body is larger than 16 KB.
415unsupported_media_typeA POST without Content-Type: application/json.
429rate_limitedToo many requests. Wait for Retry-After seconds.
500server_errorSomething went wrong on our side. Nothing was booked. Retry with backoff.
503unavailableSopmi is temporarily unreachable. Retry with backoff.

Check a key

GET/api/v1/ping

Use this to validate a key when an organizer pastes it into your dashboard.

curl https://api.sopmi.app/v1/ping \
  -H "Authorization: Bearer $SOPMI_KEY"
200 OK
{ "ok": true, "key_name": "Byticks", "request_id": "…" }

List missions

GET/api/v1/missions

Returns the organizer's ticket missions, newest first. Archived missions are left out.

200 OK
{
  "data": [
    {
      "id": "0b6c7a52-1f0e-4f43-9a0e-5f2d2b1c9e77",
      "title": "Summer Festival 2027",
      "status": "active",
      "starts_at": "2027-05-01T00:00:00Z",
      "ends_at": "2027-07-15T00:00:00Z",
      "points_per_ticket": 10,
      "codes": 48
    }
  ],
  "request_id": "…"
}

List codes

GET/api/v1/missions/{mission_id}/codes

Returns the ambassador codes of a mission. A code is 8 lowercase letters and digits, for example k3m9x2pa. Ambassadors claim their code whenever they join, so new codes keep appearing.

Query parameterDescription
updated_sinceOptional ISO 8601 timestamp. Only codes created after this moment. Use the newest created_at you have seen.
curl "https://api.sopmi.app/v1/missions/0b6c7a52-1f0e-4f43-9a0e-5f2d2b1c9e77/codes?updated_since=2027-05-02T10:00:00Z" \
  -H "Authorization: Bearer $SOPMI_KEY"
200 OK
{
  "data": [
    { "code": "k3m9x2pa", "created_at": "2027-05-02T10:14:03Z" },
    { "code": "q7w2e8rt", "created_at": "2027-05-02T11:40:51Z" }
  ],
  "request_id": "…"
}

Poll every few minutes with updated_since. Codes are case-insensitive: accept K3M9X2PA as well.

Report a sale

POST/api/v1/sales

Report a paid order that used an ambassador code. Send it once the payment is confirmed, not when the order is created.

FieldTypeDescription
codestring, requiredThe ambassador code used in the order.
order_idstring, requiredYour unique order ID, at most 200 characters. Used for idempotency and refunds.
quantityinteger, optionalNumber of tickets in the order that count, 1 to 1000. Default 1.
curl https://api.sopmi.app/v1/sales \
  -H "Authorization: Bearer $SOPMI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "k3m9x2pa", "order_id": "ORD-104233", "quantity": 2 }'
201 Created
{
  "data": { "order_id": "ORD-104233", "code": "k3m9x2pa", "quantity": 2, "points": 20,
            "refunded": false, "duplicate": false },
  "request_id": "…"
}

Sending the same order_id again returns 200 with "duplicate": true and the original values. No extra points are credited, even if the quantity differs.

Get a sale

GET/api/v1/sales/{order_id}

Check whether Sopmi received an order. URL-encode the order ID.

200 OK
{
  "data": { "order_id": "ORD-104233", "code": "k3m9x2pa", "quantity": 2, "points": 20,
            "created_at": "2027-05-03T19:02:11Z", "refunded": false, "refunded_at": null },
  "request_id": "…"
}

Report a refund

POST/api/v1/refunds

Report that a previously reported order was refunded or cancelled. Sopmi reverses the points of that order. Repeating the request is safe.

curl https://api.sopmi.app/v1/refunds \
  -H "Authorization: Bearer $SOPMI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "order_id": "ORD-104233" }'
200 OK
{
  "data": { "order_id": "ORD-104233", "refunded": true, "refunded_at": "2027-05-04T08:30:00Z", "points_reversed": 20 },
  "request_id": "…"
}

Refunds apply to the whole order. If only some tickets of an order are refunded, report the refund and then report a new sale with a new order_id (for example ORD-104233-r1) for the remaining tickets.

Integration checklist

  1. Add a field in your organizer dashboard where the organizer pastes their Sopmi API key. Validate it with GET /ping and store it encrypted.
  2. Let the organizer pick a Sopmi mission (GET /missions) for an event in your system.
  3. Sync codes every few minutes (GET /missions/{id}/codes?updated_since=…) and accept them in the shop.
  4. On a paid order with a code: POST /sales. Retry with backoff on 429, 5xx or a timeout.
  5. On a refund or cancellation: POST /refunds.
  6. If a key returns 401, show the organizer that the connection stopped and ask for a new key.

Questions or want a test organizer? Ask the organizer you work with to contact Sopmi through the Sopmi helpdesk.

Changelog

DateChange
18 November 2026Version 1: ping, missions, codes, sales, sale status and refunds.