> ## 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. # Create a membership > Puts a customer on a plan. The plan is snapshotted onto the membership exactly as it is when sold in 1club - club, session allowance, coverage, billing frequency and renewal window - so the membership draws down booking allowance identically. `paid` records a payment against the External / API method with no gateway call; `unpaid` leaves the membership's transactions outstanding. The total charged is the period amount plus any joining fee, both taken from the plan unless overridden. Collection and refunds stay with you. When nothing is owed at all - a free plan with no joining fee, or an `amount` of 0 on such a plan - the membership is created active straight away rather than awaiting a payment that will never come. Supports the `Idempotency-Key` header. ## OpenAPI ````yaml /openapi-platform.json post /v1/platform/memberships 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/memberships: post: tags: - Memberships summary: Create a membership description: > Puts a customer on a plan. The plan is snapshotted onto the membership exactly as it is when sold in 1club - club, session allowance, coverage, billing frequency and renewal window - so the membership draws down booking allowance identically. `paid` records a payment against the External / API method with no gateway call; `unpaid` leaves the membership's transactions outstanding. The total charged is the period amount plus any joining fee, both taken from the plan unless overridden. Collection and refunds stay with you. When nothing is owed at all - a free plan with no joining fee, or an `amount` of 0 on such a plan - the membership is created active straight away rather than awaiting a payment that will never come. 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: - contactId - planId - payment properties: contactId: type: integer description: >- Customer to give the membership to (from GET /v1/platform/contacts) planId: type: integer description: Plan to put them on startDate: type: string format: date-time description: Defaults to now autoRenew: type: boolean description: Defaults to the plan's setting overrides: type: object description: > The membership's own snapshot of the plan. Omit any field to take the plan's value; the admin Add membership dialog works the same way, so a negotiated sale is a normal case. Look the plan up first with GET /v1/platform/plans to see what you are overriding. properties: amount: type: number maximum: 1000000 description: Charged each period; defaults to the plan's price signupFee: type: number maximum: 1000000 description: >- Charged once on top of `amount`; defaults to the plan's joining fee, 0 waives it maxUses: type: number nullable: true description: >- Session allowance; defaults to the plan's, null for unlimited usesRemaining: type: number nullable: true description: >- Sessions left now; defaults to the full allowance. Set it lower when migrating a partly-used package. sessionUnit: type: string enum: - booking - hour description: >- Whether a use is a booking or an hour; defaults to the plan's payment: type: object required: - status properties: status: type: string enum: - paid - unpaid responses: '201': description: Membership created content: application/json: schema: $ref: '#/components/schemas/PlatformMembership' '400': description: >- Contact or plan not found in this organization, or the contact is archived content: application/json: schema: $ref: '#/components/schemas/PlatformError' '401': $ref: '#/components/responses/PlatformUnauthorized' '403': description: API key is missing the required `memberships:write` scope content: application/json: schema: $ref: '#/components/schemas/PlatformError' '409': $ref: '#/components/responses/PlatformConflict' '429': $ref: '#/components/responses/PlatformRateLimited' security: - customerApiAuth: [] components: schemas: PlatformMembership: type: object description: >- A customer's membership on a plan. The plan is snapshotted onto it at creation, so allowance and coverage behave exactly as they do for a membership sold in 1club. properties: membershipId: type: integer membershipUuid: type: string format: uuid description: >- Stable unguessable identifier. Prefer this over `membershipId` when storing a reference. contactId: type: integer description: Customer the membership belongs to planId: type: integer planName: type: string nullable: true clubId: type: integer nullable: true description: >- Club the membership is limited to; null when it applies organization-wide. status: type: string description: >- active, paused, cancelled, expired, used, pending, or pending_payment startDate: type: string format: date-time endDate: type: string format: date-time nullable: true renewalDate: type: string format: date-time nullable: true autoRenew: type: boolean price: type: number nullable: true billingFrequency: type: string maxUses: type: number nullable: true description: Session allowance snapshotted from the plan; null when unlimited. usesRemaining: type: number nullable: true createdAt: type: string format: date-time PlatformError: type: object properties: error: type: string responses: PlatformUnauthorized: description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/PlatformError' PlatformConflict: description: >- The request conflicts with existing state, or reuses an Idempotency-Key with a different body 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. ````