> ## 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. # Refund a settlement > Records money given back out of a settlement your key recorded, reducing the club's revenue by it. Nothing is moved. Omit `amount` to refund everything still refundable. A `reference` already recorded on this settlement is refused with `409 DUPLICATE_REFERENCE`; send an `Idempotency-Key` too, so two retries in flight at once cannot both be recorded. ## OpenAPI ````yaml /openapi-platform.json post /v1/platform/transactions/{id}/refund 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/{id}/refund: post: tags: - Transactions summary: Refund a settlement description: > Records money given back out of a settlement your key recorded, reducing the club's revenue by it. Nothing is moved. Omit `amount` to refund everything still refundable. A `reference` already recorded on this settlement is refused with `409 DUPLICATE_REFERENCE`; send an `Idempotency-Key` too, so two retries in flight at once cannot both be recorded. 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 - in: path name: id required: true schema: type: integer requestBody: required: true content: application/json: schema: type: object required: - reference properties: amount: type: number description: Tax included. Defaults to everything still refundable. reference: type: string maxLength: 128 description: Your refund id. responses: '200': description: Refund recorded content: application/json: schema: $ref: '#/components/schemas/PlatformTransaction' '400': description: Invalid request, or more than is still refundable 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' '404': description: No settlement with this id was recorded by your key content: application/json: schema: $ref: '#/components/schemas/PlatformError' '409': description: Already refunded in full, or 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. ````