> ## 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. # Set a client's tier > Put a client organization on a pre-agreed sub-org tier, or take it off one. Name the client with the `Nxos-On-Behalf-Of` header. Unlike other cross-org endpoints, holding an LOA is not sufficient here: you may only set the tier of an organization **you created** via `POST /v1/organizations`. This stops a customer repricing itself while acting on its own behalf. You can price a client from the moment you create them — verification does not need to have completed. Assign a tier at any time after the client is created — pricing takes effect on their next quote, and on the commission you earn from their next trade. Trades already executed are unaffected. Pass `subOrgTierKey: null` to remove the tier and return the client to default pricing. List the tiers you may assign with `GET /v1/sub-org-tiers`. ## OpenAPI ````yaml PUT /v1/organizations/sub-org-tier openapi: 3.0.0 info: title: nxos API version: 1.0.0 contact: name: nxos url: https://nxos.io description: |- The nxos platform API provides programmatic access to accounts, balances, quotes, and trades. All endpoints require API key authentication. servers: - url: https://api.nxos.io description: Production variables: {} - url: https://api.sandbox.nxos.io description: Sandbox variables: {} security: [] tags: - name: Accounts - name: Quotes - name: Beneficiaries - name: Fiat Payouts - name: Crypto Payouts - name: Sandbox Faucet - name: Nxosnet - name: Fees - name: Sub-Org Tiers - name: Funding Methods - name: Transactions - name: Organizations - name: Authorizations - name: Webhooks description: >- Register an HTTPS endpoint to receive events (organization verification and transaction status changes) instead of polling. Deliveries are signed; verify the `svix-signature` header before acting on an event. See the [Webhooks guide](https://docs.nxos.io/core-concepts/webhooks) for the delivery format, signature verification, retries, and broker behavior. Payload shapes are documented in the `…Event` models below. paths: /v1/organizations/sub-org-tier: put: tags: - Organizations description: >- Put a client organization on a pre-agreed sub-org tier, or take it off one. Name the client with the `Nxos-On-Behalf-Of` header. Unlike other cross-org endpoints, holding an LOA is not sufficient here: you may only set the tier of an organization **you created** via `POST /v1/organizations`. This stops a customer repricing itself while acting on its own behalf. You can price a client from the moment you create them — verification does not need to have completed. Assign a tier at any time after the client is created — pricing takes effect on their next quote, and on the commission you earn from their next trade. Trades already executed are unaffected. Pass `subOrgTierKey: null` to remove the tier and return the client to default pricing. List the tiers you may assign with `GET /v1/sub-org-tiers`. operationId: Organizations_setSubOrgTier parameters: - $ref: '#/components/parameters/ApiKeyAuth' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateSubOrgTierRequest' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/SubOrgTierAssignment' '401': description: Access is unauthorized. content: application/json: schema: $ref: '#/components/schemas/Error401' '403': description: Access is forbidden. content: application/json: schema: $ref: '#/components/schemas/Error403' '404': description: The server cannot find the requested resource. content: application/json: schema: $ref: '#/components/schemas/Error404' '422': description: Client error content: application/json: schema: $ref: '#/components/schemas/Error422' '429': description: Client error content: application/json: schema: $ref: '#/components/schemas/Error429' '500': description: Server error content: application/json: schema: $ref: '#/components/schemas/Error500' components: parameters: ApiKeyAuth: name: Authorization in: header required: true description: 'Bearer token. Format: `Bearer `' schema: type: string schemas: UpdateSubOrgTierRequest: type: object properties: subOrgTierKey: type: string nullable: true description: >- Key of the tier to assign, from `GET /v1/sub-org-tiers`. Pass `null` (or omit) to remove the organization's tier, dropping it back to default pricing. description: Request body for `PUT /v1/organizations/sub-org-tier`. SubOrgTierAssignment: type: object required: - object - organizationId - tier properties: object: type: string enum: - sub_org_tier_assignment description: Object type. Always `sub_org_tier_assignment`. organizationId: type: string description: Organization the tier applies to. tier: type: object allOf: - $ref: '#/components/schemas/SubOrgTier' nullable: true description: The tier now in force, or `null` when the organization is on none. description: Result of setting or clearing an organization's sub-org tier. Error401: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. example: error: code: missing_api_key message: No Authorization header provided. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 Error403: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. example: error: code: forbidden message: Your organization is not enabled for this action. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 Error404: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. example: error: code: not_found message: The requested resource was not found. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 Error422: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. example: error: code: validation_error message: Request body failed validation. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 Error429: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. example: error: code: rate_limited message: 'Rate limit exceeded: 1000 requests per minute. Retry in 23 seconds.' requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 Error500: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. example: error: code: internal_error message: An unexpected server error occurred. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 SubOrgTier: type: object required: - key - label - spreadBps - referrerShareBps properties: key: type: string description: >- Stable identifier for the tier. Pass this as `subOrgTierKey` when assigning. label: type: string description: Human-readable name, safe to show in your own UI. spreadBps: type: integer format: int32 description: >- Full bid+ask spread applied to the client's quotes, in basis points. `100` = 1%. referrerShareBps: type: integer format: int32 description: >- Share of the client's spread fee paid to you, in basis points. `5000` = 50%. description: >- A pre-agreed commercial bundle a broker can apply to a client organization. Setting a tier changes two things for that client: the spread it is quoted, and the commission you earn on that client's spread fee. Tiers are agreed with Nxos up front — you can list and assign them, but not create them. `GET /v1/sub-org-tiers` returns only the tiers agreed with your organization. ErrorBody: type: object required: - code - message - requestId properties: code: allOf: - $ref: '#/components/schemas/ErrorCode' description: Machine-readable error code. message: type: string description: Human-readable error message. requestId: type: string description: Unique identifier for this request, useful for debugging. ErrorCode: type: string enum: - missing_api_key - authentication_failed - invalid_api_key - forbidden - swap_direction_not_allowed - sub_org_tier_not_available - service_not_enabled - not_found - organization_not_found - account_not_found - quote_not_found - beneficiary_not_found - transaction_not_found - funding_method_not_found - authorization_not_found - nxosnet_handle_not_found - sub_org_tier_not_found - quote_expired - quote_already_used - beneficiary_already_archived - beneficiary_not_archived - beneficiary_blocked - nxosnet_not_enabled - nxosnet_handle_taken - chain_send_failed - idempotency_key_in_use - idempotency_request_in_flight - invalid_request - insufficient_funds - validation_error - share_token_invalid - verification_import_unsupported - verification_required - rate_limited - webhooks_unavailable - internal_error description: All possible error codes returned by the API. ````