Broker pricing: putting your clients on a tier

This guide explains how a broker sets the commercial terms for each client organization it creates, using tiers agreed with Nxos in advance.

When you’d use this

If you onboard client organizations through POST /v1/organizations, every client starts on default pricing. A tier lets you move a specific client onto terms you negotiated with us, without asking us to edit anything per client. Typical reasons to reach for it:

A high-volume client you quoted a tighter rate to.
A segment of your book that carries a wider spread and pays you a larger share.
Repricing a client whose volume has changed since onboarding.

If you operate a single organization and don’t onboard clients, this guide doesn’t apply to you.

What a tier is

A tier is two related numbers:

Field	Meaning
`spreadBps`	The markup applied to your client’s conversions, in basis points. `100` = 1%.
`referrerShareBps`	Your share of the spread your client pays, in basis points. `6000` = 60%.

The two move together. A wider spread is what funds a larger referral share, which is why both are part of the same negotiated tier rather than two independent dials. Your client sees the spread on their own quotes. They never see the referral share. Tiers are defined by Nxos and agreed with you up front. You can list and assign them; you cannot create or edit them. GET /v1/sub-org-tiers returns only the tiers agreed with your organization, so a tier negotiated with another broker is never visible to you.

Listing the tiers you can assign

curl https://api.sandbox.nxos.io/v1/sub-org-tiers \
  -H "Authorization: Bearer nxos_sk_test_brkr..."

{
  "object": "list",
  "data": [
    { "object": "sub_org_tier", "key": "STANDARD", "label": "Standard", "spreadBps": 100, "referrerShareBps": 2000 },
    { "object": "sub_org_tier", "key": "PLUS", "label": "Plus", "spreadBps": 250, "referrerShareBps": 6000 }
  ],
  "hasMore": false,
  "nextCursor": null
}

This endpoint requires the broker feature. If it isn’t enabled for you, the call returns 403 forbidden. Contact us to turn it on.

Assigning a tier

Name the client with the Nxos-On-Behalf-Of header and pass the tier’s key:

curl -X PUT https://api.sandbox.nxos.io/v1/organizations/sub-org-tier \
  -H "Authorization: Bearer nxos_sk_test_brkr..." \
  -H "Nxos-On-Behalf-Of: org_cust1234567890abcdef1234567890abcd" \
  -H "Content-Type: application/json" \
  -d '{ "subOrgTierKey": "PLUS" }'

{
  "object": "sub_org_tier_assignment",
  "organizationId": "org_cust1234567890abcdef1234567890abcd",
  "tier": { "key": "PLUS", "label": "Plus", "spreadBps": 250, "referrerShareBps": 6000 }
}

Pass null to remove the tier and return the client to default pricing:

  -d '{ "subOrgTierKey": null }'

Read the current tier back from GET /v1/organizations with the same header. The response carries a subOrgTier field, null when the client is on default pricing. referrerShareBps is included only when you read the client, through Nxos-On-Behalf-Of. If that client reads its own organization with its own API key it sees key, label and spreadBps, but not the share you earn. Your client sees the spread it is charged, never your referral.

Who can assign what

You may only set the tier of an organization you created through POST /v1/organizations. Holding an LOA is not enough, which is what stops a client repricing itself while acting on its own behalf. You do not need to wait for verification. Terms are agreed at onboarding, so you can price a client from the moment you create them.

Setting a tier works before KYB, but reading one back does not. Until a client’s verification is APPROVED, GET /v1/organizations with Nxos-On-Behalf-Of returns 403 authorization_required.That is expected, not a failed write. The response to PUT /v1/organizations/sub-org-tier echoes the tier it stored, so use it as your confirmation.

When pricing takes effect

A tier applies from the client’s next conversion. Quotes already issued and trades already executed are unaffected. Each one snapshots the rate it was priced at, so repricing never rewrites history. The same applies to your referral share: commission is calculated at the rate in force when the trade completed.

Errors

Code	Status	Meaning
`sub_org_tier_not_found`	404	No tier matches the supplied `subOrgTierKey`. Check `GET /v1/sub-org-tiers`.
`sub_org_tier_not_available`	403	The tier exists but was not agreed with your organization.
`forbidden`	403	The target organization was not created by you.
`organization_not_found`	404	The organization in `Nxos-On-Behalf-Of` does not exist.
`validation_error`	422	`subOrgTierKey` is not a string or is longer than 50 characters.

Getting started

Core concepts

Guides

Broker pricing: putting your clients on a tier

When you’d use this

What a tier is

Listing the tiers you can assign

Assigning a tier

Who can assign what

When pricing takes effect

Errors

​When you’d use this

​What a tier is

​Listing the tiers you can assign

​Assigning a tier

​Who can assign what

​When pricing takes effect

​Errors

When you’d use this

What a tier is

Listing the tiers you can assign

Assigning a tier

Who can assign what

When pricing takes effect

Errors