Skip to main content

Partner Tiers and Progress Rewards

What this page solves​

Read tier state and conditions, then inspect the compensation associated with progress rewards.

When to use it​

Use this workflow when showing qualification information or reconciling a progress-reward record with its order-level detail.

Before you start​

Use an active signed API key and the access required by the selected operation. See Authentication and Partnership permissions. Read access is required. Obtain tier_id from tier state or tier conditions; obtain compensation_id from the progress-reward list. Lot commission requires the symbol and account_type parameters documented in API Reference.

  1. 1
    Read current tier state and qualification tier.
  2. 2
    Read tier conditions using page and page_size when paging, then read the applicable fix-per-lot matrix. The matrix can be empty.
  3. 3
    Read lot commission for the selected symbol and account type when needed.
  4. 4
    List progress-reward records.
  5. 5
    Use a returned compensation ID to inspect detailed calculations.

Reading tier conditions​

Each tier has a conditions array containing its qualification conditions. When commission is returned, it groups percentages by reward formula. Each percentage array contains the first-level value followed by the second-level value; preserve null when a percentage is unavailable.

Main endpoints​

Example request​

Request-shape example; replace the authentication placeholders with a fresh signature.

GET /v1/partnership/reports/progress-reward HTTP/1.1
Host: <your-api-host>
EXN-API-KEY: <your-api-key>
EXN-TIMESTAMP: <fresh-unix-milliseconds>
EXN-SIGN-VERSION: 1
EXN-DATA: <base64url-signed-data>
EXN-SIGN: <base64url-signature>

What to expect in return​

HTTP 200 returns compensation records and totals. commission_percentage is an object of account categories, each with numeric old_tier and new_tier. payment_date records a payment-status update and does not itself confirm a successful payout.

{
  "data": [
    {
      "compensation_id": 1,
      "payment_date": "2026-07-30T10:30:00Z",
      "compensation_period_start": "2026-07-30T10:30:00Z",
      "compensation_period_end": "2026-07-30T10:30:00Z",
      "old_tier_group_id": 1,
      "new_tier_group_id": 1,
      "compensation_amount": 123.45,
      "commission_percentage": {
        "pro": {
          "old_tier": 17,
          "new_tier": 18
        }
      }
    }
  ],
  "totals": {
    "count": 1,
    "ab_test_enabled": true
  }
}

Common errors​

The following errors apply to the example operation. Other operations can declare a different subset; follow their API Reference links.

HTTP status / codeWhat It MeansHow to Fix It
429 / ThrottledA Partnership operation rate limit was exceeded.Slow down the request rate and honor Retry-After when it is returned.
504 / ServiceTransportErrorA service required by the Partnership operation could not be reached or timed out.Retry the request with exponential backoff.
500 / ErrorA Partnership operation failed because a required service could not complete the request.Retry the request with backoff.
401 / AuthenticationFailedA Partnership service rejected the authenticated request after request authentication. API-key and request-signature failures use the numeric authentication errors.Check the request authorization context. When the response uses the numeric envelope, follow the action for its error_message.
403 / PermissionDeniedThe authenticated identity cannot perform the operation or access the requested partner data.Use credentials with the required Partnership permission and resource access.
400 / ValidationErrorRequest validation failed, including bad-request or conflict conditions returned as validation errors.Do not retry unchanged. Correct the request using details, then sign the corrected request again.
404 / NotFoundThe resource does not exist or is not available to the partner.Verify the identifier and current resource list.
502 / 1 — SYSTEM_BAD_GATEWAYThe API could not complete the request to the Partnership service.Retry the request with backoff.
503 / 2 — SYSTEM_TEMPORARY_UNAVAILABLEA required service is temporarily unavailable or the request deadline was exceeded.Retry the request with backoff.
500 / 3 — SYSTEM_INTERNAL_ERRORThe API encountered an unexpected internal error.Retry the request with backoff.
401 / 1000 — AUTH_INVALID_API_KEYThe API key is invalid, expired, revoked, or not allowed for the request source.Check the API key, its state, and its allowed source IP.
401 / 1001 — AUTH_INVALID_SIGNATUREThe request signature or signed timestamp is invalid.Rebuild the signature from the exact request and a fresh timestamp.
403 / 1002 — AUTH_FORBIDDENThe API key does not have a required operation scope.Use an API key with the required Partnership scope.
429 / 1003 — AUTH_RATE_LIMITThe authentication rate limit was exceeded.Honor Retry-After and reduce request rate.
400 / 3001 — REQUEST_INVALID_PARAMETERSRequired headers or signed request data are malformed or inconsistent.Correct the headers or signed values named by description, then sign the exact request again.

Recovery and reconciliation​

Preserve compensation IDs when reconciling detail. Current and qualification tier can differ.

Progress-reward payment

A record in the progress-reward list can relate to a rejected payment; do not count its presence or date as proof that money was paid. The contract specifies no delivery-time SLA.