Core Concepts
Use the distinctions below when joining data, displaying amounts and deciding whether a business process has completed.
Partners, clients and attribution
A partner attracts clients through partner links. A client can own more than one trading account. Client attribution associates the client with a partner; trading-account attribution associates an individual account with a partner. A client and that client's accounts can be attributed to different partners. Use the Clients report for client-level information and the Client accounts report for account-level activity.
partner_uid identifies a partner. client_uid identifies a client; client_account identifies a trading account. They are not interchangeable. Preserve the type documented by each endpoint instead of converting every identifier to a number. Check the identifier format expected by each operation before using a value from another response. Some responses shorten client identifiers or mask account numbers; those displayed values must not be treated as full identifiers for another request.
Campaigns and partner links
A campaign groups links and tracking attributes. campaign_code identifies the campaign. partner_code and link_code refer to the same partner-link identifier, but the accepted parameter name depends on the operation. Use only the parameter documented for that report. The Client transactions report does not accept campaign or link filters.
Campaign reward models are revenue_share and cpa; creating a campaign defaults to revenue_share when the field is omitted. The returned link fields describe the actual link associated with the campaign.
Reward orders, rewards and revenue share
A reward order is a contribution calculated from an eligible closed client order. A reward aggregates reward orders for a partner, client account and payout cycle. Daily and instant rewards use different processing cycles; no delivery-time SLA is specified.
An IB partner can receive revenue-share rewards from eligible client trading activity. Revenue share is a reward model, not an additional reward record. Calculation can vary by the client's trading-account type. Do not infer a monetary calculation from the model name alone.
Subpartners and second-level rewards
A subpartner is registered under a master partner. The directly attributed partner receives first-level reward; the master partner can receive second-level reward. Use the second-level API variants of Reward history and Client accounts when analyzing this relationship, and retain the returned subpartner identifiers.
Rebates, rows and payments
A rebate returns part of a partner reward to a client. A rebate row contains the amount calculated for one client trading account. A rebate payment aggregates the rows included in that payment. rebate_id identifies a generated batch or period; payment_id identifies a payment aggregate; row id values identify calculation rows.
Batch, row and payment statuses have different meanings. A PROCESSED batch can contain rejected rows.
ERROR can change after processing is retried. Row lists return APPROVED as PROCESSING, while aggregates can expose APPROVED separately. Follow Rebates to reconcile amounts and individual rows. The API also lets you create and change rebate groups, client settings and rules. Rebate history returns calculation rows with their current processing results; it is not a log of every status transition.
Referral agents, agreements and effective dates
A referral agent attracts clients for a master partner through a dedicated link and receives an agreed share of the master's reward for those clients. The master partner owns the link.
A referral-agent agreement is versioned reward-share terms. Effective dates determine which share applies to a reward calculation. Returned commercial terms describe current configuration; this version does not include operations to manage agreement terms. It supports creating the link, reading it, changing its alias and archiving it.
Shared-report access is returned configuration. It is not an API capability to change that access or retrieve shared-report data. agent_commission_usd and reward_usd in referral-agent lists are nullable numbers; preserve null instead of changing it to zero or a string.
Partner tier and progress reward
A partner tier is a reward level determined by qualification conditions. Current tier and qualification tier can differ. Progress reward is additional compensation associated with reaching a higher tier during a benefit period.
A progress-reward compensation_id identifies a compensation record and can be used in the detailed report path. commission_percentage maps account categories to old_tier and new_tier percentages.
payment_date is a payment-status update timestamp; its presence alone does not confirm a successful payout.
Report consistency and pagination
Reports update asynchronously. Recent changes can appear at different times across report families.
Where present, limit controls the page size and offset the starting row. Keep the filters and ordering stable throughout one export. A sequence of pages is not a stable snapshot of changing data.
Use the response's totals or metadata when provided; do not infer total row count from page length. See Reports for the identifiers returned by each report.
Amounts, null and time
Money and volume fields use the exact string or numeric types declared by the operation. Use decimal-aware processing for accounting and avoid binary floating-point arithmetic for monetary calculations. A null value is not the same as zero or an absent property.
Absolute timestamps use UTC; date-only fields use YYYY-MM-DD. For example, client reg_date is a calendar date and trade_fn can be a calendar date or null, while progress-reward payment_date is a timestamp. Interpret a date as a date instead of adding an invented time.
Access and recovery
The API key determines the partner and resource access. A key with partnership.all includes read and write access; partnership.all:read is read-only. Resource reads can return NotFound when an identifier does not exist or is inaccessible, where that error is documented.
This version has no idempotent-write semantics. The signed idempotency_key is empty; no idempotency header prevents duplicate execution. Read current state after an unknown write outcome, then decide what to do next. If the outcome remains unclear, do not automatically repeat the write. See Troubleshooting Your API Requests.