Skip to main content
Use the membership endpoints to integrate membership management into your application. A policy holds the purchase and billing relationship. A seat is one person’s place on that policy. A policy whose plan covers more than one person has several seats: one for the primary member plus one for each secondary member. Secondary members can be added after purchase, so a policy’s seats can grow.
The membership API is in beta: its request and response contract can still change while it’s being developed.
Requests, paging and errors work as described in the API overview. Server integrations use an unrestricted organizer key; scoped keys receive 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 policyId or seatId it 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, LDT or SYSTEM, or null when it wasn’t recorded. Calls made with your key are recorded as ORGANIZER, whoever asked you. Changes made by Let’s Do This staff while supporting you are recorded as LDT.

Typical flow with an organizer key

  1. 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.
  2. Read the policy dashboard for its status, renewal and price.
  3. Read the seat’s entries and member details as your app needs them.
  4. Open a billing portal session when the member wants to change their payment method, and redirect them to it straight away.

Custom member answers

Read GET /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}:
Replace the example IDs and options with those returned by the form. Text, text-area, date, select and radio questions use 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 from gender 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:
Update gender through the member-details endpoint:
Use a value accepted by that question. Values are preserved rather than converted to a shared gender enum. 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

Use entitled 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. Treat cancellationEffectiveAt 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.
A member inside a cooling-off window, with nothing owed:
A member outside cooling-off, on a scheme with a notice period, whose latest renewal is unpaid:
cancellationEffectiveAt, memberMayCancelNow and outstandingInvoices are null when they can’t be worked out; treat null as unknown rather than as “no”.

2. Cancel

Send cancelWhen 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:
The membership stays active until 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:
An immediate cancellation ends the membership at once, so nothing is left pending. Two optional fields can come back with it:
  • coolingOffRefund, only when a member cancels immediately with their own token inside a cooling-off window. Its outcome is REFUNDED, SUPPORT_REVIEWS (our support team decides the refund) or REFUND_FAILED, with the amount when it’s known. A cancellation made with an organizer key never refunds a payment, inside a cooling-off window or not.
  • outstandingInvoicesVoidIncomplete: true when you asked for VOID and 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 returns outstandingInvoices: null. Check the open invoices in your Stripe account to see what is still owed.
A member cancelling immediately, with their own token, inside a cooling-off window:

Outstanding invoices

With an organizer key, invoices the membership still owes stay owed unless you send outstandingInvoices: "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

Until effectiveAt, 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.
When nothing was pending the answer is { "withdrawn": false, "kind": null }. The same endpoint withdraws a pending offering change.

Errors

Errors carry a code 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.
  1. List the entries with status=WAITING to see who you can select, oldest first.
  2. Select each person you pick, one call per entry. Their membership starts in the background on the saved card, at the quotedPrice.
  3. Read the entry again: JOINED carries the new policyId and seatId. REFUSED carries a refusal saying why the membership couldn’t start, such as a changed price; nothing was charged.
The first payment is taken about an hour after selection, the same way a renewal is, and 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, call GET /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.
  • createdAt is 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.
  • updatedAt is 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 use updatedAt[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 neither emailAddress nor list=all, or with both, is refused with 400, 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 with 400. The date filters and sorts don’t combine with emailAddress.

Keeping data fresh

Every read returns current data, so read when your app needs it: on sign-in, when a membership view opens, and when the member returns from the billing portal. A member-facing app doesn’t need timed background polling; a sync of your own member list does (see above). There are no membership webhooks.

Data that is never returned

Membership responses never include Stripe account, customer, subscription, product or price IDs, payment method IDs, internal subscription configuration IDs, client secrets or full card numbers. The optional card details contain only the last four digits. The billing portal URL is the one short-lived credential returned; don’t log, store or share it. Reservation codes and claim links aren’t returned either: a member claims a reserved place from the email sent when it’s reserved.