POST /api/v1/codes

Reference codes attach a per-code afftax override (and an optional free-form label) to your partner record. Callers select a code at request time via X-API-KEY: <prefix>.<code>. The auth layer looks it up, verifies ownership and enabled state, and feeds the per-code afftax into /api/v1/price and /api/v1/create.

Codes are optional — your default referral link already earns without one. Use codes to bill a different markup per channel, or rotate them per campaign to track conversion without issuing a new credential bundle. Default cap is 50 codes per partner. The operator can raise it on request.

Code format

• Regex: ^[A-Za-z0-9_-]{4,32}$: URL-safe alphabet, length 4..32.
• No dots: the auth-side parser splits X-API-KEY on the first . and assumes the suffix is a single segment.
• Optional label is a free-form string up to 64 characters. Bookkeeping for you, never surfaced to end users.

POST /api/v1/codes — create

{
  "code": 0,
  "msg": "",
  "data": {
    "id": "ckxq0...",
    "code": "main-site",
    "label": "Main site",
    "afftaxBps": 500,
    "enabled": true,
    "createdAt": "2026-05-13T08:42:11.000Z"
  }
}

# Create a new reference code with a per-code afftax (500 bps). Authenticate via
# the top-level apiKey + apiSecret bundle. Callers then use
# X-API-KEY: <prefix>.<code>  to attribute traffic to this code.
APIKEY="rWqZ...Rg"
APISECRET="G1JV...n4"
NONCE=$(openssl rand -hex 16)
BODY='{"code":"main-site","label":"Main site","afftaxBps":500}'
SIGN=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$APISECRET" | sed 's/^.* //')

curl -sS -X POST "https://0trace.io/api/v1/codes" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $APIKEY" \
  -H "X-API-SIGN: $SIGN" \
  -H "X-API-NONCE: $NONCE" \
  --data "$BODY"

GET /api/v1/codes — list

Returns every code owned by the partner (enabled + disabled), newest first, capped at 100 rows. Sign an empty body "" for the request signature.

{
  "code": 0,
  "msg": "",
  "data": [
    {
      "id": "ckxq0...",
      "code": "main-site",
      "label": "Main site",
      "afftaxBps": 500,
      "enabled": true,
      "createdAt": "2026-05-13T08:42:11.000Z"
    },
    {
      "id": "ckxp9...",
      "code": "newsletter",
      "label": null,
      "afftaxBps": 200,
      "enabled": false,
      "createdAt": "2026-05-12T22:18:03.000Z"
    }
  ]
}

DELETE /api/v1/codes — soft-disable

Disabled codes are still listed by GET /api/v1/codes. They are rejected at authentication, so a caller using a disabled code receives code 3 AUTH_INVALID.

POST /api/v1/codes/enable — re-enable

Errors

Rate limit

Every verb (POST create, GET list, DELETE disable, POST codes/enable) charges 1 weight unit against the per-partner sliding-window budget.