The membership API is in beta: its request and response contract can still
change while it’s being developed.
403.
For apps that call the API as a signed-in member, use
member access with OAuth. Each endpoint’s
reference page describes its fields.
What your integration is responsible for
Some of what keeps members safe can’t be enforced from our side. These are yours, and they are part of the contract for using this API.- Keep the organizer key on a server. In a mobile app or a browser it lets anyone read every member’s details and open billing sessions for all of them. An app with no server of its own uses member access instead.
- Decide which member is acting. We check that a policy or seat belongs to
your organization, and nothing more. Check which member is signed in and
only pass their own policy and seat IDs. If your server passes on a
policyIdorseatIdit was sent by a client, one member can reach another’s data or billing, and to us it looks like any other call. Don’t treat knowing an email address as proof of identity. Your app also enforces the member’s primary or secondary role. - An organizer key cancels as you, not as the member. A cancellation made with it is the organizer’s own: the scheme’s notice period isn’t applied, no cooling-off refund is made, and what the member owes stays owed unless you void it. The quote describes the member’s rules, but an organizer-key request isn’t held to them, so it can’t reproduce a member’s cancellation. Where members cancel for themselves in your product, have them cancel with a member token, which applies the notice period, cooling-off and their invoices for you. If you cancel for a member with your key anyway, honouring their notice, refunding a cooling-off cancellation and settling what they owe are all yours to do.
- Cancelling doesn’t settle what’s owed. A member can always cancel. With an organizer key an unpaid invoice stays open on your Stripe account unless you void it, and collecting or writing off that balance is yours to do. A member’s own cancellation follows the scheme, which voids it in some cases: see Outstanding invoices.
- Who made a change is recorded. A pending change shows
requestedByKind:MEMBER,ORGANIZER,LDTorSYSTEM, ornullwhen it wasn’t recorded. Calls made with your key are recorded asORGANIZER, whoever asked you. Changes made by Let’s Do This staff while supporting you are recorded asLDT.
Typical flow with an organizer key
- Find the member’s seats by email after they sign in. An email can return several seats and policies, so don’t assume the first one is the only one.
- Read the policy dashboard for its status, renewal and price.
- Read the seat’s entries and member details as your app needs them.
- Open a billing portal session when the member wants to change their payment method, and redirect them to it straight away.
Custom member answers
ReadGET /v0/membership-seats/{seatId}/form before building a custom-field
editor. It returns the seat’s current questions, accepted options, required
flags and structured answers. Use each question’s id and answerShape when
sending customFields to PATCH /v0/membership-seats/{seatId}:
value; checkboxes use
values. Dates use YYYY-MM-DD. Choice answers use the tokens in optionValues;
accepted case variants are returned in the form’s spelling. The member-details
response continues to show custom answers as text; the form endpoint provides
their structured values.
Choice constraints use the same names as the booking import field contract:
Choice values include only enabled options from the current form; free-text
questions do not have an
optionValues list. Grouped choices and custom address
or phone questions stay read-only. Their existing answers remain available as text on member details;
the form returns editable: false, answerShape: null and no structured answer
for those composite values.
Only send fields you want to change. To clear an optional answer, send its
id without an answer property. Required answers cannot be cleared. Each
request can contain up to 100 custom fields, with each ID appearing once.
Invalid answers reject the whole update, including any core details sent in
the same request.
Only offer edits where editable is true. Hidden and deleted questions and
questions the caller cannot read are omitted. Field permissions also apply
to writes. Waivers, conditional questions and their parents, priced or verified fields, and
unsupported field types remain read-only through this endpoint. Email changes
still use the membership transfer flow.
Gender
Read a member’s gender fromgender in the member-details response. The gender
question is omitted from customFields and remains available in the form
endpoint with its accepted values, required flag and editable setting.
A gender question in the form response might look like this:
null clears an optional answer; a required
answer cannot be cleared. You can also update the original question through
customFields using its form ID. Send one representation per request; sending
both rejects the update. The response exposes the answer once, as gender.
gender is null when no answer is available or the API cannot identify a
single gender question. Only offer edits when the question’s editable flag
is true.
Access and status
Useentitled to decide whether the member has access. status explains why,
and paymentFailed warns that a renewal payment has failed before access is
lost, so it can be true while entitled is still true. Treat unknown future
values conservatively.
Cancelling a membership
Four endpoints cover cancellation. Each works with an organizer key or a member token; with a member token only the policy’s primary member can call them.Who can do what
1. Quote the cancellation
Read the quote before showing a cancel screen. It says when a period-end cancellation asked for now would take effect, whether the member may cancel immediately, any open cooling-off window with its refund, and what the membership still owes. The terms describe the member’s rules even when you read them with an organizer key. TreatcancellationEffectiveAt as an estimate. On a scheme with no notice
period, a membership whose renewal is unpaid can end immediately even when the
member asks for END_OF_BILLING_PERIOD.
cancellationEffectiveAt, memberMayCancelNow and outstandingInvoices are
null when they can’t be worked out; treat null as unknown rather than as
“no”.
2. Cancel
SendcancelWhen and an Idempotency-Key header unique to this cancellation:
1 to 100 visible ASCII characters with no spaces, such as a UUID. Reuse the same key when you retry after a timeout
or a 5xx, so the membership is cancelled once.
A member cancelling at the end of their billing period:
effectiveAt. timing is AT_RENEWAL when
it ends with a billing period and AT_DATE when the scheme’s notice period
puts the end on another date.
An organizer cancelling immediately, clearing what the member owes and
recording why:
coolingOffRefund, only when a member cancels immediately with their own token inside a cooling-off window. ItsoutcomeisREFUNDED,SUPPORT_REVIEWS(our support team decides the refund) orREFUND_FAILED, with theamountwhen it’s known. A cancellation made with an organizer key never refunds a payment, inside a cooling-off window or not.outstandingInvoicesVoidIncomplete: truewhen you asked forVOIDand some invoices aren’t voided yet. They are retried for about an hour. The quote can’t confirm the balance once the membership has ended: it returnsoutstandingInvoices: null. Check the open invoices in your Stripe account to see what is still owed.
Outstanding invoices
With an organizer key, invoices the membership still owes stay owed unless you sendoutstandingInvoices: "VOID". A member’s own cancellation follows the
scheme: we attempt to void an unpaid invoice when they cancel immediately inside
a cooling-off window, or when an unpaid member cancels on a scheme with no
notice period. A successful response confirms the cancellation, not that the
balance was cleared: check the invoice’s status in your Stripe account before
telling a member they owe nothing.
Reason and note
Both are optional, organizer-key only, and for your own records: they don’t change billing.note is private plain text of up to 2000 characters and is never shown to the
member. More reason codes may be added.
3. Read what is pending
GET /v0/membership-policies/{policyId}/pending-change returns
{ "pendingChange": { ... } }, with the same object the cancel response
carries, or { "pendingChange": null } when no change is recorded. Check
pendingChange for null first, then pendingChange.kind, which is
CANCELLATION or OFFERING, before reading the rest.
null means no recorded change. A cancellation scheduled before these records
existed can still have renewal turned off, and withdrawing still turns it back
on.
cancellationCause says how a cancellation came about, and is separate from
the reason an organizer records:
More causes may be added.
cancellationCause is null for an offering change.
4. Withdraw a pending cancellation
UntileffectiveAt, the cancellation can be withdrawn, which turns renewal
back on. The call takes no body.
It withdraws whichever change is pending when it arrives, so don’t retry it
blindly after a timeout: a change scheduled since your first call would be
withdrawn too. Read the pending change first, and withdraw again only if the
one you meant to call off is still there.
With nothing to withdraw it answers { "withdrawn": false, "kind": null }.
A repeat within a few seconds of a successful withdrawal can answer
{ "withdrawn": true, "kind": "CANCELLATION" } again while billing catches
up; it changes nothing.
{ "withdrawn": false, "kind": null }. The same endpoint withdraws a pending
offering change.
Errors
Errors carry acode to branch on:
Waitlists
An offering can be joined by waitlist instead of bought. A person joins in checkout with the member form and a saved card, and nothing is charged. Waitlist endpoints are restricted: ask your Let’s Do This representative to enable them.- List the entries
with
status=WAITINGto see who you can select, oldest first. - Select
each person you pick, one call per entry. Their membership starts in the
background on the saved card, at the
quotedPrice. - Read the entry
again:
JOINEDcarries the newpolicyIdandseatId.REFUSEDcarries arefusalsaying why the membership couldn’t start, such as a changed price; nothing was charged.
firstPaymentAt is set once it succeeds. If the card is
declined, the membership follows your scheme’s failed-renewal handling: its
grace period, Stripe’s retries and the billing portal, and it ends if the
payment never succeeds.
Waitlisted people aren’t members: they don’t appear in seat lookups until
they’ve joined. Nothing limits how many people you select, so keep to your
membership’s size yourself.
Prices
Amounts are in minor currency units:12000 in DKK means DKK 120.00. An
offering’s current price is what a new member would pay. An existing member
pays the price on their policy dashboard, which can be a revision that is no
longer on sale. The organizer can move existing policies to a newer revision
when the price changes, so an existing member’s price can rise.
A price’s fee is always in the same currency as its amount. A policy
dashboard shows a subscription price in the currency the member’s
subscription bills in. If the price isn’t sold in that currency, amount and
fee are null and detailsAvailable is false.
Listing every member
To keep your own member list in step, callGET /v0/membership-seats?list=all.
It returns every seat in your organization, whatever its status, in seat ID
order, up to 500 per page with page[size]. Follow page.next with page[after], sending
list=all again on each page, until it’s empty. Each seat carries the member’s email address
and name, createdAt, updatedAt, its policy’s status, entitled,
expiresAt and renewalDate, and its tier and plan.
Filter and sort the list as you would the API’s other lists:
A
createdAt filter together with an updatedAt filter returns seats that
match either, so createdAt[after] and updatedAt[after] with the same time
give you everything new or changed since then. Keep paging with the cursors
the response gives you; a sorted list’s cursors only work with the same sort.
createdAtis when the seat was created. That’s when the member joined, except for members added by a bulk import, who carry the import’s date. A seat transferred to someone else keeps its date, and a member who rejoins after their membership ended gets a new seat.updatedAtis when the seat record last changed: the member’s details, their tier or plan, who holds the seat, or its place on the policy.- Status is worked out when you ask, and doesn’t move
updatedAt. A member whose membership ends or freezes isn’t marked as changed, so read the whole list again on a schedule to refresh status, even if you useupdatedAt[after]for everything else. Removed seats drop out of the list, so a full read is also how you find members who left. - The whole list only comes back when you ask for it with
list=all. A call with neitheremailAddressnorlist=all, or with both, is refused with400, so a lookup that loses its email address never returns every member. - Any query parameter other than
emailAddress,list, the paging parameters and the ones above is refused with400. The date filters and sorts don’t combine withemailAddress.

