Skip to main content

Rebates

What this page solves​

Manage rebate configuration and reconcile batch, payment and row results.

When to use it​

Use this guide to configure rebates for your clients and reconcile the resulting batches, payments and calculation rows.

Before you start​

Use an active signed API key. Select Partnership Read-only access (partnership.all:read) to inspect rebates, or Full access (partnership.all) to create and change rebate settings. See Authentication. Read existing groups and clients before changing them. Obtain group_id from the group list, rule_id from a group's rules, rebate_id from generated batches, and payment_id from payments. This API does not expose approval, rejection or payment-retry operations.

  1. 1
    Read groups, their clients and rules to inspect current configuration.
  2. 2
    If you need to configure rebates, create or update the group, client settings or rules using Full access.
  3. 3
    Read generated rebate batches and inspect their status and amounts.
  4. 4
    Read payment records, then use a returned payment ID to read the included rebate rows.
  5. 5
    Compare processed, rejected and error amounts with individual row statuses.
  6. 6
    Re-read a result when processing has changed; ERROR is not necessarily permanent.

Configure rebates​

Create a group, add client trading accounts, and adjust the group or its rules as needed. You can also set a percentage for multiple client accounts, change one account's rebate settings, or set the destination account for selected rows in a generated batch. Write operations require Full access (partnership.all). Read the affected resource after a lost response before deciding whether to repeat a write.

A group must have no assigned clients before you delete it. For group updates, include the intended rebate_percent even when changing another setting, and check need_approve in the response: approval is a separate process and is not available through this API. A group's AUTO type cannot be set through the update operation. Rule conditions use either USD or lot-based reward volume, and non-default rules run in ascending priority order. Each write operation lists its supported fields in API Reference; read filters such as limit, offset and ordering do not apply to these writes.

Batch periods and account counts​

In the batch list, period_start_date and period_end_date are YYYY-MM-DD dates or null. clients_count counts clients; clients_accounts_count counts their trading accounts. The batch's group_id and group_name, and totals.clients_pending_count, can also be null.

Rebate group responses can return null for clients_count, rebate_percent, some period settings and link_code. Check the selected endpoint's schema before using these values.

Interpreting status​

Status tables

These tables describe status meanings, not a required transition sequence or the sort order of API results. A rebate does not have to pass through every listed status. Status values and their representation depend on the endpoint and response field.

Batch statuses​

StatusWhat It MeansFinal?Client action
PENDINGawaiting approvalNoRead again to check for a later status; approval and payment actions are not available in this API.
APPROVEDapproved for processingNoRead again to check processing progress.
PROCESSINGa non-final processing stateNoDo not wait for this status before checking the rows and payments; it is not a required intermediate stage.
ERRORone or more rebate rows encountered a processing errorNot necessarily; processing can be retriedInspect error and processed amounts and individual rows. ERROR does not imply that the processed amount is zero.
PROCESSED_PARTIALboth processed amounts and amounts with errors are presentPartial resultCompare processed and error amounts with the individual rows.
PROCESSEDprocessing is complete with no remaining pending, approved, processing, or error amountsCompleted outcome*Check rejected amounts and individual row statuses before treating every row as paid.
REJECTEDthe batch was rejectedRejected outcome*Inspect the rejected result; do not count it as a successful payment.

Row statuses​

StatusWhat It MeansFinal?Client action
PENDINGawaiting approvalNoRead again to check approval progress. History and payment-row lists exclude rows in this state.
APPROVEDapproved for processingNoRow-list responses show this state as PROCESSING; aggregate responses can retain APPROVED.
PROCESSINGpayment processing is in progress; row lists also use this value for approved rows awaiting processingNoRead again to reconcile the processing result.
PROCESSEDprocessed successfullyCompleted outcome*Reconcile this row with the amounts and rows in its payment record.
REJECTEDrejected without a successful paymentRejected outcome*Inspect the rejected result; do not count it as a successful payment.
ERRORprocessing failedNot necessarily; processing can be retriedInspect the returned processing error code where present and read again. For an unresolved error, provide the rebate or payment identifier and code to support.

Payment statuses​

StatusWhat It MeansFinal?Client action
PENDINGawaiting payment processingNoVisible in payment details as totals.status; the payment list shows this state as PROCESSING.
PROCESSINGpayment processing is in progress; the payment list also uses this value for payments awaiting processingNoRead again to reconcile the processing result.
PROCESSEDpayment processed successfullyCompleted outcome*Reconcile the reported amounts with the individual rows.
REJECTEDpayment rejected without a successful payoutRejected outcome*Inspect the rejected result; do not count it as a successful payment.
ERRORpayment processing failedNot necessarily; processing can be retriedInspect the returned processing error code where present and read again. For an unresolved error, provide the rebate or payment identifier and code to support.

Where each status appears​

ResponseFieldStatus handling
Batch listdata[].statusBatch status; compare the amounts and individual rows. Do not wait for PROCESSING before checking progress.
Rows for a batchdata[].statusPENDING can appear; APPROVED is returned as PROCESSING.
History and rows for a paymentdata[].statusPENDING rows are excluded; APPROVED is returned as PROCESSING.
Aggregated rowsdata[].statusPENDING and APPROVED can appear. Rows are grouped by status as well as account fields; this is not an overall status for the client account.
Payment listdata[].statusPENDING is returned as PROCESSING, which covers both waiting and ongoing processing.
Rows for a paymenttotals.statusPayment status, separate from each row status in data. It can be null; when present, it preserves PENDING.

*Completed or rejected describes the returned outcome. The contract does not guarantee that status values are immutable. Batch PROCESSED can include rejected rows: completion is determined from amounts, not solely from row counts. ERROR is not necessarily permanent. The same client account can have separate aggregate rows with different statuses; do not combine them into a single status by taking the first or last row.

Unrecognized status values​

Unknown statuses

Status strings have no closed enums, and some totals.status fields can be null. The tables explain the currently documented values. Preserve an unrecognized string or null; neither confirms a successful or final outcome. Inspect the accompanying amounts and rows, and use support when the outcome cannot be interpreted. Do not trigger a payment or retry payment processing based on an unknown status. This API has no payment-retry operation.

API endpoints​

Read rebates​

Change rebate settings​

Example request​

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

GET /v1/partnership/autorebates/payments 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 data and totals. Amounts in this operation are numbers; destination_client_account, client_account_type, error_code and processed_date can be null. When present, processed_date is a calendar date, not proof of a successful payment. The example illustrates response structure with an empty result.

{
  "data": [],
  "totals": {
    "count": 0,
    "reward": 0,
    "reward_usd": 0,
    "volume_lots": 0,
    "processed_rebate": 0,
    "processed_rebate_usd": 0,
    "rejected_rebate_usd": 0,
    "error_rebate_usd": 0
  }
}

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.
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​

Statuses are separate

Interpret batch, row and payment statuses separately. PROCESSED at batch level does not mean every row was paid.

Row lists return APPROVED as PROCESSING; aggregates retain APPROVED. The payment list returns PENDING as PROCESSING, while payment details preserve the original payment status in totals.status when it is not null. Use the endpoint and field distinctions above when comparing results. error_code describes rebate processing and is separate from HTTP errors. For an unresolved processing error, provide the rebate or payment ID and returned code to support. No payment-retry operation is exposed.