Memberships

A membership puts a customer on a plan. The plan supplies the price, joining fee, billing frequency and session allowance, so a normal sale sends only the customer, the plan, and whether you collected the money.

Create a membership

Requires the memberships:write scope.

curl -X POST "https://api.1club.ai/v1/platform/memberships" \
  -H "Authorization: Bearer 1club_sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: membership-ivan-2026-08" \
  -d '{
    "contactId": 300,
    "planId": 9,
    "payment": { "status": "paid" }
  }'

Body fields:

contactId (required) - the customer, from Contacts
planId (required) - the plan, from Plans
startDate (optional) - ISO date-time; defaults to now
endDate (optional) - omit to let the plan’s billing frequency decide
autoRenew (optional) - defaults to the plan’s setting
payment.status (required) - paid (you collected the money) or unpaid (outstanding)
overrides (optional) - see Overriding the plan

Response (201 Created):

{
  "membershipId": 7412,
  "contactId": 300,
  "planId": 9,
  "planName": "Unlimited",
  "clubId": 5,
  "status": "active",
  "startDate": "2026-08-01T00:00:00.000Z",
  "endDate": "2026-09-01T00:00:00.000Z",
  "renewalDate": "2026-09-01T00:00:00.000Z",
  "autoRenew": true,
  "price": 49,
  "billingFrequency": "monthly",
  "maxUses": null,
  "usesRemaining": null,
  "createdAt": "2026-08-01T09:12:00.000Z"
}

Creating a membership accepts an Idempotency-Key, so a timeout cannot produce two. See Idempotency.

How payment decides the status

The membership starts life according to what is owed, not according to what you declare:

paid - 1Club records a payment against the External / API payment method (no card is charged) and the membership becomes active, or pending when it starts in the future.
unpaid - the charge is left outstanding and the membership sits at pending_payment. It grants no access until the money is settled in 1Club.
Nothing owed - a free plan with no joining fee is active straight away. There is no payment to wait for.

An unpaid membership does not give the customer access. If they are already training, either send paid or settle the charge in 1Club. This differs from bookings, where an unpaid booking still stands - a membership grants ongoing access, so it waits for the money.

Collection and refunds stay with you. 1Club never charges a card for these memberships.

Overriding the plan

A membership keeps its own copy of the plan’s commercial terms, so a negotiated sale is a normal case. Send only what differs; anything omitted takes the plan’s value.

curl -X POST "https://api.1club.ai/v1/platform/memberships" \
  -H "Authorization: Bearer 1club_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": 300,
    "planId": 9,
    "payment": { "status": "paid" },
    "overrides": {
      "amount": 35,
      "signupFee": 0,
      "maxUses": 12,
      "usesRemaining": 4,
      "sessionUnit": "hour"
    }
  }'

amount - charged each period, instead of the plan’s price
signupFee - the joining fee; 0 waives it
maxUses - session allowance; null for unlimited
usesRemaining - sessions left right now, which is how you migrate a package the customer has already partly used. null means unlimited usage, so it is only valid when the allowance is unlimited too.
sessionUnit - booking or hour

usesRemaining can never exceed the allowance it draws from, whether that is a maxUses you sent or the plan’s own. The same holds on update, against the state the membership will be left in - so you cannot lower maxUses below a balance already on it, and you cannot leave the balance unlimited under a finite allowance.

The two nulls are not the same. maxUses: null is an unlimited allowance, which nothing can exceed. usesRemaining: null is unlimited usage, so a ten-session allowance rejects it - otherwise the allowance would mean nothing. Send both as null for a genuinely unlimited membership.

This is the same set of fields the gym’s staff can change in the Add membership dialog, so an API sale and a front-desk sale can express the same deal.

Read the plan first. Overriding blindly is how a membership ends up cheaper - or more generous - than anyone intended.

List memberships

Requires the memberships:read scope.

curl "https://api.1club.ai/v1/platform/memberships?contactId=300&status=active" \
  -H "Authorization: Bearer 1club_sk_live_..."

Query parameters:

contactId (optional) - only this customer’s memberships
planId (optional) - only memberships on this plan
status (optional) - one of pending, active, expired, cancelled, used, paused, pending_payment
limit (optional) - 1 to 100, defaults to 25
offset (optional) - defaults to 0

Returns a page in the usual shape, newest start date first. An unrecognised status is a 400, not an empty list.

Get a membership

Requires the memberships:read scope. Returns one membership by its 1Club id, including usesRemaining - the sessions the customer has left.

curl "https://api.1club.ai/v1/platform/memberships/7412" \
  -H "Authorization: Bearer 1club_sk_live_..."

Update a membership

Requires the memberships:write scope.

curl -X PATCH "https://api.1club.ai/v1/platform/memberships/7412" \
  -H "Authorization: Bearer 1club_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "cancelled", "cancelMode": "end_of_period" }'

Two kinds of change, and they cannot be combined: A status transition - status on its own, optionally with the field that configures it:

`status`	Companion field	What happens
`cancelled`	`cancelMode`	`end_of_period` (default) keeps access until the paid period ends and stops the renewal. `immediate` ends access today.
`paused`	`resumeAt`	Pauses the membership. `resumeAt` must be in the future; the pause lifts by itself then.
`active`	-	Resumes a paused membership. Only valid from `paused`.

A detail change - any of endDate, autoRenew, maxUses, usesRemaining. Use usesRemaining to correct a balance after a migration. cancelMode only applies to a cancellation and resumeAt only to a pause; sending either with the wrong status is a 400 rather than being quietly ignored.

Statuses 1Club works out for itself - expired, used, pending_payment - cannot be set here. They follow from dates, usage, and payment.

What this API does not do

No plan changes. Moving a customer to a different plan is a priced change needing proration, invoicing, and possibly a refund. Do it in 1Club.
No refunds. Cancelling releases the membership; it never returns money.
No deletes. Cancel it instead, so the history stays intact.

Getting Started

Channel integration

Area Blocks

Areas

Bookings

Check-ins

Classes

Clubs

Contacts

Content

Instructors

Account

Media

Plans

Products

Transactions

Website

Memberships

Create a membership

How payment decides the status

Overriding the plan

List memberships

Get a membership

Update a membership

What this API does not do

​Create a membership

​How payment decides the status

​Overriding the plan

​List memberships

​Get a membership

​Update a membership

​What this API does not do

Create a membership

How payment decides the status

Overriding the plan

List memberships

Get a membership

Update a membership

What this API does not do