Create a membership
Requires thememberships:write scope.
contactId(required) - the customer, from ContactsplanId(required) - the plan, from PlansstartDate(optional) - ISO date-time with offset; defaults to nowautoRenew(optional) - defaults to the plan’s settingclassId(required for a plan withchargesPerSession, 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 withPLAN_REQUIRES_STANDING_PLACE. See Per-session plans.payment.status(required) -paid(you collected the money) orunpaid(outstanding)payment.reference(optional) - your own id for the payment you collected, up to 128 characters. Requirespayment.status: "paid".payment.fee(optional) - what you kept out of the amount, your commission. Recorded for reconciliation; it does not reduce the sale. Requirespayment.status: "paid"and an explicitoverrides.amountit cannot exceed.overrides(optional) - see Overriding the plan
endDate: how long a membership runs follows from the plan.
Response (201 Created):
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 becomesactive, orpendingwhen 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 atpending_payment. It grants no access until the money is settled in 1club.- Nothing owed - a free plan with no joining fee is
activestraight away. There is no payment to wait for.
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 pricesignupFee- the joining fee;0waives itmaxUses- session allowance;nullfor unlimitedusesRemaining- sessions left right now, which is how you migrate a package the customer has already partly used.nullmeans unlimited usage, so it is only valid when the allowance is unlimited too.sessionUnit-bookingorhour
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.List memberships
Requires thememberships:read scope.
contactId(optional) - only this customer’s membershipsplanId(optional) - only memberships on this planstatus(optional) - one ofpending,active,expired,cancelled,used,paused,pending_paymentlimit(optional) - 1 to 100, defaults to 25offset(optional) - defaults to 0
status
is a 400, not an empty list.
Get a membership
Requires thememberships: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 thememberships:write scope.
status on its own, optionally with the field that
configures it:
A detail change - any of these:
autoRenew- whether it renewscommitmentMonths- a new minimum term in months, counted from the start date;nullremoves it. Only a renewing membership carries one.maxUses- session allowance;nullfor unlimitedusesRemaining- sessions left, for setting a balance migrated in. Send it together withmaxUses: 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-bookingorhour. A change recounts what is left in the new unit.sessionLengthMinutes- how long one visit lasts at the door, from its first entry;nulllasts 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
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.
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.
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 takesallowances 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.
id(required) - theallowanceIdfrom the membershipvalidFor(optional) - what this allowance covers, replaced wholemaxUses(optional) - sessions each period;nullfor unlimitedsessionUnit(optional) -bookingorhour
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 thememberships: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.
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.
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.