> ## Documentation Index > Fetch the complete documentation index at: https://docs.1club.ai/llms.txt > Use this file to discover all available pages before exploring further. # Record a settlement > Records revenue you collected outside 1club as one sum for a club - for example a period's takings for bookings you recorded at 0. It is a paid transaction of type `settlement` on the club, settled against your key's payment method, and counts in the club's revenue under the revenue account you name. It is not split across bookings or customers. `amount` is what customers paid, tax included; the tax is taken out at the revenue account's rate. A `payment.reference` your key already recorded is refused with `409 DUPLICATE_REFERENCE` (`details.transactionId` names the existing one). No receipt is sent. Supports the `Idempotency-Key` header. ## OpenAPI ````yaml /openapi-platform.json post /v1/platform/transactions openapi: 3.0.0 info: title: 1club Platform API version: 1.0.0 description: >- The 1club Platform API lets you programmatically access and manage your organization's data. ## Official API Contract This documentation is the official source of truth for the 1club Platform API. If an integration relies on undocumented endpoints, fields, response shapes, or internal behavior outside this spec, we can't guarantee backward compatibility. Build against what's documented here to stay stable as the platform evolves. ## Authentication All requests require a customer API key passed as a Bearer token: ``` Authorization: Bearer 1club_sk_live_... ``` Generate API keys from the admin portal under **Settings > API Tokens**. The key is tied to your organization - all responses are scoped to your org's data. ## Rate Limiting - **100 requests per minute** per API key - When exceeded, the API returns `429 Too Many Requests` with a `Retry-After` header - Rate limit headers are included in every response: - `X-RateLimit-Limit` - max requests per window - `X-RateLimit-Remaining` - requests remaining - `X-RateLimit-Reset` - seconds until the window resets ## Errors | Status | Meaning | |--------|---------| | `400` | Invalid request parameters | | `401` | Missing or invalid API key | | `404` | Resource not found (or doesn't belong to your organization) | | `429` | Rate limit exceeded | | `500` | Internal server error | contact: name: 1club API Support email: support@1club.ai servers: - url: https://api.1club.ai description: Production API security: - customerApiAuth: [] tags: [] paths: /v1/platform/transactions: post: tags: - Transactions summary: Record a settlement description: > Records revenue you collected outside 1club as one sum for a club - for example a period's takings for bookings you recorded at 0. It is a paid transaction of type `settlement` on the club, settled against your key's payment method, and counts in the club's revenue under the revenue account you name. It is not split across bookings or customers. `amount` is what customers paid, tax included; the tax is taken out at the revenue account's rate. A `payment.reference` your key already recorded is refused with `409 DUPLICATE_REFERENCE` (`details.transactionId` names the existing one). No receipt is sent. Supports the `Idempotency-Key` header. parameters: - in: header name: Idempotency-Key schema: type: string maxLength: 255 description: >- Retry-safe key; a repeat of the same request replays the first response requestBody: required: true content: application/json: schema: type: object required: - clubId - date - amount - revenueAccountId - payment properties: clubId: type: integer contactId: type: integer description: The customer the whole sum belongs to, if there is one. date: type: string format: date description: The day it is reported on. amount: type: number description: What was collected, tax included. description: type: string maxLength: 500 description: Defaults to your key's name. revenueAccountId: type: integer description: The account the revenue posts to; its tax rate applies. payment: type: object required: - status - reference properties: status: type: string enum: - paid reference: type: string maxLength: 128 description: Your id for the money, e.g. a payout id. fee: type: number description: Your commission. Recorded, does not reduce the revenue. responses: '201': description: Settlement recorded content: application/json: schema: $ref: '#/components/schemas/PlatformTransaction' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/PlatformError' '401': $ref: '#/components/responses/PlatformUnauthorized' '403': description: API key is missing the required `transactions:write` scope content: application/json: schema: $ref: '#/components/schemas/PlatformError' '409': description: The reference is already recorded content: application/json: schema: $ref: '#/components/schemas/PlatformError' '429': $ref: '#/components/responses/PlatformRateLimited' security: - customerApiAuth: [] components: schemas: PlatformTransaction: type: object description: >- A billing transaction with amounts, payment status, and links to the originating booking or membership. properties: id: type: integer uuid: type: string format: uuid description: >- Stable unguessable identifier. Prefer this over `id` when storing a reference. description: type: string nullable: true transactionType: type: string nullable: true description: >- TransactionType enum value (e.g. booking_creation, membership_creation, product_sale, membership_recurrence, etc.). A settlement recorded with `POST /v1/platform/transactions` is `settlement`. bookingId: type: integer nullable: true membershipId: type: integer nullable: true contactId: type: integer nullable: true description: The customer charged, when there is one. clubId: type: integer nullable: true description: >- Set on a settlement only; other transactions take their club from their booking or membership. createdAt: type: string format: date-time date: type: string format: date-time paymentStatus: type: string enum: - pending - paid - void - failed - settled - overdue - partially_paid - refunded - cancelled amount: type: string description: >- Pre-tax amount as a decimal string (e.g. "25.00"). Serialized as a string to preserve precision. taxAmount: type: string description: Tax portion as a decimal string. totalAmount: type: string description: Total billed amount as a decimal string (amount + taxAmount). PlatformError: type: object properties: error: type: string responses: PlatformUnauthorized: description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/PlatformError' PlatformRateLimited: description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/PlatformError' securitySchemes: customerApiAuth: type: http scheme: bearer description: >- Organization-scoped bearer credential: a customer API key (1club_sk_live_...) or an MCP OAuth access token. ````