Skip to main content
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.
Body fields:
  • contactId (required) - the customer, from Contacts
  • planId (required) - the plan, from Plans
  • startDate (optional) - ISO date-time with offset; defaults to now
  • autoRenew (optional) - defaults to the plan’s setting
  • classId (required for a plan with chargesPerSession, ignored otherwise) - any session of the recurring class the customer takes a place in, from Classes. They are booked into every session of it from the start date. Without it the call is refused with PLAN_REQUIRES_STANDING_PLACE. See Per-session plans.
  • payment.status (required) - paid (you collected the money) or unpaid (outstanding)
  • payment.reference (optional) - your own id for the payment you collected, up to 128 characters. Requires payment.status: "paid".
  • payment.fee (optional) - what you kept out of the amount, your commission. Recorded for reconciliation; it does not reduce the sale. Requires payment.status: "paid" and an explicit overrides.amount it cannot exceed.
  • overrides (optional) - see Overriding the plan
There is no endDate: how long a membership runs follows from the plan. Response (201 Created):
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 a payment method named after your API key (no card is charged) and the membership becomes active, or pending when it starts in the future. The customer is not sent a payment receipt for it - you issue your own.
  • 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.
  • 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.
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 - and allowances, which lists what it covers (validFor), its session count, and what is left. A membership sold from a plan with several allowances, such as 5 Yoga + 4 Pilates, has one entry for each, each with the allowanceId you use to change it. nextCharge is its next renewal charge (chargeDate, periodStart, periodEnd, amount), or null when none is coming. On a per-session plan its perSession says what the charge is made of, before tax: totalAmount (what the parts add up to), fixedAmount, each of the sessions with its price, the discount, correctionsAmount for earlier months and carriedCreditAmount. Its usesRemaining is the makeups it owes.

Update a membership

Requires the memberships:write scope.
Three kinds of change, and they cannot be combined: A status transition - status on its own, optionally with the field that configures it: A detail change - any of these:
  • autoRenew - whether it renews
  • commitmentMonths - a new minimum term in months, counted from the start date; null removes it. Only a renewing membership carries one.
  • maxUses - session allowance; null for unlimited
  • usesRemaining - sessions left, for setting a balance migrated in. Send it together with maxUses: what is left otherwise follows from the allowance and what was spent. To give or take back sessions, use session adjustments.
  • validFor - what it covers. See Change what a membership covers.
  • sessionUnit - booking or hour. A change recounts what is left in the new unit.
  • sessionLengthMinutes - how long one visit lasts at the door, from its first entry; null lasts until the end of the gym’s day. It applies only to a membership that counts sessions per booking.
  • shareWithAccount - whether the people on the holder’s account can use it too
A move to another class - classId on its own, for a membership on a per-session plan. See Move to another class. 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.

Change what a membership covers

validFor replaces what the membership covers, so send the whole coverage. It uses the same shape as a plan’s: scopes picks classes, areas, and/or instructors, and classTypes, areaTypes, and instructorTypes narrow a scope to those type ids. A scope with no list covers every type in it.
This changes the membership’s own copy of the plan, never the plan or anyone else’s membership. The new coverage decides what is spent from here on. Sessions already spent stay spent. These requests return a 400 instead of being stored and not acted on: A type id from another organization is also a 400.

Move to another class

A membership on a per-session plan holds a seat in every session of one recurring class. classId moves it to another: send any session of the new class, from Classes. From that session on, the member holds a seat in every session of the new class. Their place in the old class ends just before it: those sessions are cancelled, are not billed, and owe no makeup. The next monthly charge settles a month that was already charged.
A membership on any other plan is refused with STANDING_PLACE_NOT_PER_SESSION, and a class that does not repeat with STANDING_PLACE_NEEDS_RECURRING_CLASS.

Change one of several allowances

A membership with several allowances takes allowances instead of validFor, maxUses, usesRemaining, and sessionUnit. Send only the allowances that change, with only the fields that change. The rest stay as they are.
Each entry takes:
  • id (required) - the allowanceId from the membership
  • validFor (optional) - what this allowance covers, replaced whole
  • maxUses (optional) - sessions each period; null for unlimited
  • sessionUnit (optional) - booking or hour
No two allowances may cover the same type (PLAN_ALLOWANCES_OVERLAP). What is used stays used: a count raised by two leaves two more. Sending the wrong shape for the membership is a 400: MEMBERSHIP_HAS_SEVERAL_ALLOWANCES for the single-allowance fields on a membership with several, and MEMBERSHIP_HAS_ONE_ALLOWANCE for allowances on a membership with one.

Adjust sessions

Requires the memberships:write scope. Gives a membership sessions or takes some back, with a reason, the same way staff do in 1club. Use it for a goodwill session or a correction. To change the allowance itself, update the membership.
Body fields:
  • units (required) - sessions given (positive) or taken back (negative), up to 1000 either way, and not zero. These are hours on an hourly pass.
  • reason (required) - why, up to 500 characters. It is recorded with the adjustment.
  • allowanceId (optional) - which allowance. Required on a membership with several.
Returns the updated membership. On a membership with a session allowance, the adjustment lasts for the current allowance period, and the next period starts from the allowance again. Adjusting sessions accepts an Idempotency-Key, so a retry cannot adjust them twice.

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 price or billing changes. Changing what a membership costs, or how often it bills, is also done in 1club.
  • No end date changes. How long a membership runs follows from the plan. Extending one is done in 1club.
  • No refunds. Cancelling releases the membership; it never returns money.
  • No deletes. Cancel it instead, so the history stays intact.