> ## Documentation Index > Fetch the complete documentation index at: https://docs.hyperprop.com/llms.txt > Use this file to discover all available pages before exploring further. # Update your billing details > Replaces all billing details: send every field, as a missing field is cleared. Each value is checked (for example the tax ID format for its type and country); a rejected value returns 400 with `fields`, and nothing is saved. **Locking.** You can save incomplete details as often as you need. Once complete details are saved (`complete: true`), they are locked (`locked: true`) and further updates return 403 `BILLING_DETAILS_LOCKED`, CC emails included. Contact Hyperprop at finance@hyperprop.com to change locked details. Read the details first and send only when `locked` is false. **Tax ID types:** `eu_vat`, `gb_vat`, `ch_vat`, `no_vat`, `us_ein`, `ca_bn`, `au_abn`, `nz_gst`, `ae_trn`, `sg_uen`, `sg_gst`, `hk_br`, `in_gst`, `il_vat`, `jp_cn`, `kr_brn`, `za_vat`, `br_cnpj`, `mx_rfc`, `sa_vat`. Invoice emails go to the billing email; CC emails are stored as extra invoice contacts. At most 20 updates per 10 minutes per organization (429 `RATE_LIMITED` with `Retry-After`). **Access:** full-access API keys only (a read-only key gets `403 READ_ONLY_KEY`). Dashboard members need manage access to Billing & purchases revenue. ## OpenAPI ````yaml https://api.hyperprop.com/platform/openapi.json put /v1/organization/billing/details openapi: 3.0.0 info: title: Hyperprop Platform API version: 1.0.0 description: >- REST API for the Hyperprop Trading Platform — provision evaluation and funded trading accounts, manage traders and plans, react to account lifecycle events via signed webhooks, and reconcile billing. Built for prop firms integrating from their own backend. Authentication, quick start, error handling, idempotency, pagination, custom metadata, webhooks, and the MCP connector are documented at https://docs.hyperprop.com. x-logo: url: https://app.hyperprop.com/logo-icon.svg altText: Hyperprop href: https://hyperprop.com servers: - url: https://api.hyperprop.com/platform description: Production security: [] tags: - name: Trading accounts description: Create, update, and inspect trading accounts. - name: Traders description: Look up and update the traders in your organization. - name: Trading plans description: Define the plans you sell. - name: Trading rules description: Define how accounts are evaluated. - name: Instruments description: >- The contracts your organization's accounts can trade, with their specifications. - name: Lockouts description: Pause and resume trading on an account. - name: Payouts description: Check payout eligibility and record payouts. - name: Purchases description: Purchases recorded for your organization. - name: Time Machine description: Restore accounts to an earlier trading day or instant. - name: Mass credit description: >- Credit back losses across many accounts after an incident, as background jobs you can follow, pause, export and reverse. - name: Webhooks description: Register webhook endpoints and inspect deliveries. - name: Events description: Your organization's event history, to replay or audit what happened. - name: Real-time streams description: >- Live events and trading data over a WebSocket, for dashboards and CRMs that update as things happen. - name: Reconciliation description: Balances, end-of-day snapshots, and fills for reconciliation. - name: Analytics description: Organization performance, revenue and top traders. - name: Risk description: Firm profit and loss and plan economics. - name: Billing and invoices description: >- Your Hyperprop invoices, credits and billing details, with usage so far this month, billing cycles, forecasts and CSV exports. - name: Team and roles description: Manage dashboard access for your staff. - name: API keys description: >- Manage your organization's API keys: rotation, read-only keys and IP allowlists. - name: Logs and health description: >- API request logs, the audit log, integration health, and idempotency key recovery. - name: Organization profile description: Your organization's profile and logo. - name: Support description: Open and follow up on support tickets. - name: Partner access description: >- Read a trader's journal as an approved partner app, with the trader's own key. paths: /v1/organization/billing/details: put: tags: - Billing and invoices summary: Update your billing details description: >- Replaces all billing details: send every field, as a missing field is cleared. Each value is checked (for example the tax ID format for its type and country); a rejected value returns 400 with `fields`, and nothing is saved. **Locking.** You can save incomplete details as often as you need. Once complete details are saved (`complete: true`), they are locked (`locked: true`) and further updates return 403 `BILLING_DETAILS_LOCKED`, CC emails included. Contact Hyperprop at finance@hyperprop.com to change locked details. Read the details first and send only when `locked` is false. **Tax ID types:** `eu_vat`, `gb_vat`, `ch_vat`, `no_vat`, `us_ein`, `ca_bn`, `au_abn`, `nz_gst`, `ae_trn`, `sg_uen`, `sg_gst`, `hk_br`, `in_gst`, `il_vat`, `jp_cn`, `kr_brn`, `za_vat`, `br_cnpj`, `mx_rfc`, `sa_vat`. Invoice emails go to the billing email; CC emails are stored as extra invoice contacts. At most 20 updates per 10 minutes per organization (429 `RATE_LIMITED` with `Retry-After`). **Access:** full-access API keys only (a read-only key gets `403 READ_ONLY_KEY`). Dashboard members need manage access to Billing & purchases revenue. operationId: putV1OrganizationBillingDetails parameters: - name: Idempotency-Key in: header required: false description: >- Optional. A value that identifies this operation on your side, at most 255 characters. A retry with the same key, method, path and body within 24 hours returns the original response (with `Idempotency-Replayed: true`) instead of repeating the change. The same key with a different body returns `409 IDEMPOTENCY_KEY_REUSED`; a retry while the first request is still running returns `409 IDEMPOTENCY_KEY_IN_PROGRESS`. Server errors (5xx) are not saved, so a retry runs again. example: crm-sync-8814-attempt-1 schema: type: string maxLength: 255 requestBody: content: application/json: schema: $ref: '#/components/schemas/OrgBillingDetailsInput' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Model1662' '400': description: >- Invalid billing details. `fields` lists every rejected field; nothing was saved content: application/json: schema: $ref: '#/components/schemas/BillingDetailsError' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Model11' '403': description: >- The details are locked, the key is read-only, or the caller has no manage access to Billing content: application/json: schema: $ref: '#/components/schemas/BillingDetailsLockedError' '409': description: >- The `Idempotency-Key` was used with a different body (`IDEMPOTENCY_KEY_REUSED`), or a request with the same key is still running (`IDEMPOTENCY_KEY_IN_PROGRESS`) content: application/json: schema: type: object properties: success: type: boolean description: Always false on errors example: false statusCode: type: integer example: 409 error: type: string example: Conflict message: type: string example: >- This Idempotency-Key was already used with a different request body. Use a new key for a different request. code: type: string enum: - IDEMPOTENCY_KEY_REUSED - IDEMPOTENCY_KEY_IN_PROGRESS example: IDEMPOTENCY_KEY_REUSED description: >- Machine-readable error code — switch on this, not on message text '429': description: >- Too many requests (limit: 20 per 10 minutes per organization). Retry after `Retry-After` seconds headers: Retry-After: description: Seconds to wait before retrying schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Model1666' '500': description: An unexpected error occurred content: application/json: schema: $ref: '#/components/schemas/Model6' security: - X-API-Key: [] components: schemas: OrgBillingDetailsInput: type: object properties: legalName: type: string example: Example Trading Ltd. maxLength: 200 x-convert: trim: true billingEmail: type: string example: ap@example.com maxLength: 254 x-format: email: true x-convert: trim: true ccEmails: $ref: '#/components/schemas/Model1660' address: $ref: '#/components/schemas/OrgBillingDetailsAddress' taxId: $ref: '#/components/schemas/OrgBillingTaxId' Model1662: type: object properties: success: type: boolean example: true data: $ref: '#/components/schemas/Model1661' BillingDetailsError: type: object properties: success: type: boolean example: false statusCode: type: number example: 400 error: type: string example: Bad Request message: type: string example: 'taxId.value: This does not look like a valid EU VAT number' code: $ref: '#/components/schemas/Model1663' fields: $ref: '#/components/schemas/fields' Model11: type: object properties: success: type: boolean description: Always false on errors example: false statusCode: type: number example: 401 error: type: string example: Unauthorized message: type: string example: Authentication required code: type: string description: Machine-readable error code — switch on this, not on message text example: UNAUTHORIZED BillingDetailsLockedError: type: object properties: success: type: boolean example: false statusCode: type: number example: 403 error: type: string example: Forbidden message: type: string example: >- Billing details are locked. Contact Hyperprop at finance@hyperprop.com to change them. code: $ref: '#/components/schemas/Model1665' Model1666: type: object properties: success: type: boolean description: Always false on errors example: false statusCode: type: number example: 429 error: type: string example: Too Many Requests message: type: string example: >- Too many requests (limit: 20 per 10 minutes per organization). Retry after `Retry-After` seconds code: type: string description: Machine-readable error code — switch on this, not on message text example: RATE_LIMITED Model6: type: object properties: success: type: boolean description: Always false on errors example: false statusCode: type: number example: 500 error: type: string example: Internal Server Error message: type: string example: An unexpected error occurred code: type: string description: Machine-readable error code — switch on this, not on message text example: INTERNAL_ERROR Model1660: type: array description: >- Extra contacts for invoices. Invoice emails currently go to the billing email only. maxItems: 10 x-constraint: unique: true items: type: string maxLength: 254 x-format: email: true x-convert: trim: true OrgBillingDetailsAddress: type: object properties: line1: type: string example: Herengracht 100 maxLength: 200 x-convert: trim: true line2: type: string maxLength: 200 x-convert: trim: true city: type: string example: Amsterdam maxLength: 100 x-convert: trim: true state: type: string description: State, province or region maxLength: 100 x-convert: trim: true postalCode: type: string example: 1015 BS maxLength: 20 x-convert: trim: true country: type: string example: NL x-constraint: length: 2 x-convert: trim: true OrgBillingTaxId: type: object properties: type: $ref: '#/components/schemas/Model415' value: type: string example: NL123456789B01 minLength: 3 maxLength: 40 x-convert: trim: true required: - type - value Model1661: type: object properties: details: $ref: '#/components/schemas/BillingDetails' Model1663: type: string description: >- `VALIDATION_ERROR` = the body does not match the schema; `INVALID_BILLING_DETAILS` = a value failed a check (for example a tax ID) example: INVALID_BILLING_DETAILS enum: - VALIDATION_ERROR - INVALID_BILLING_DETAILS fields: type: array description: One entry per rejected field, as a field path items: $ref: '#/components/schemas/Model1664' Model1665: type: string description: >- `BILLING_DETAILS_LOCKED` = the details were saved complete; `READ_ONLY_KEY` = use a full-access key; `INSUFFICIENT_PERMISSIONS` = no manage access to Billing example: BILLING_DETAILS_LOCKED enum: - BILLING_DETAILS_LOCKED - READ_ONLY_KEY - INSUFFICIENT_PERMISSIONS - IP_NOT_ALLOWED Model415: type: string example: eu_vat enum: - eu_vat - gb_vat - ch_vat - no_vat - us_ein - ca_bn - au_abn - nz_gst - ae_trn - sg_uen - sg_gst - hk_br - in_gst - il_vat - jp_cn - kr_brn - za_vat - br_cnpj - mx_rfc - sa_vat BillingDetails: type: object properties: organizationId: type: string example: 0e9b6a14-7c2d-4b8f-93a1-6d5e2f8c0b47 x-format: guid: true organizationName: type: string example: Acme Trading Co legalName: type: string example: Example Trading Ltd. billingEmail: type: string description: Invoices are emailed here example: ap@example.com ccEmails: $ref: '#/components/schemas/ccEmails' address: $ref: '#/components/schemas/OrgBillingDetailsAddress' taxId: $ref: '#/components/schemas/OrgBillingTaxId' complete: type: boolean description: Everything needed to issue an invoice is present example: true missing: $ref: '#/components/schemas/missing' locked: type: boolean description: >- Saved complete: your organization can no longer change the details. Contact Hyperprop at finance@hyperprop.com to change them example: true updatedAt: type: string example: '2026-10-28T10:12:00.000Z' x-format: isoDate: true Model1664: type: object properties: field: type: string example: taxId.value message: type: string example: This does not look like a valid EU VAT number ccEmails: type: array description: Extra invoice contacts (stored; invoice emails go to the billing email) example: - finance@example.com items: type: string missing: type: array description: >- Required fields still missing: `legalName`, `billingEmail`, `address.line1`, `address.city`, `address.postalCode` (except where a country has none), `address.country` example: [] items: type: string securitySchemes: X-API-Key: type: apiKey name: X-API-Key in: header description: >- Organization API key (`hp_live_...`), sent in the `X-API-Key` header. Create, rotate and restrict keys in the dashboard or with the API keys endpoints; an organization can have two active keys, so you can rotate without downtime. A **full-access** key can call every endpoint in this reference. A **read-only** key can call `GET` endpoints (and create a trading stream token); any other request returns `403 READ_ONLY_KEY`. A key with an IP allowlist returns `403 IP_NOT_ALLOWED` from any other address. Each endpoint lists which keys can call it under **Access**. ```` ## Related topics - [Get your billing details](https://docs.hyperprop.com/platform-api/billing-and-invoices/get-your-billing-details.md) - [Billing and invoices](https://docs.hyperprop.com/guides/billing-and-invoices.md) - [Build your own CRM on Hyperprop](https://docs.hyperprop.com/guides/build-a-crm.md) - [Team and roles](https://docs.hyperprop.com/guides/team-and-roles.md) - [Get bulk operation details](https://docs.hyperprop.com/platform-api/trading-accounts/get-bulk-operation-details.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.