> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nxos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Broker pricing: putting your clients on a tier

> How a broker applies pre-agreed commercial terms to the clients it onboards.

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`](/api-reference/organizations/create), 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

```bash theme={null}
curl https://api.sandbox.nxos.io/v1/sub-org-tiers \
  -H "Authorization: Bearer nxos_sk_test_brkr..."
```

```json theme={null}
{
  "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`:

```bash theme={null}
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" }'
```

```json theme={null}
{
  "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:

```bash theme={null}
  -d '{ "subOrgTierKey": null }'
```

Read the current tier back from [`GET /v1/organizations`](/api-reference/organizations/get) 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.

<Note>
  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.
</Note>

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