> ## Documentation Index
> Fetch the complete documentation index at: https://partner-help.letsdothis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Membership API

> List or find members' seats, read benefits and billing status, update member details, cancel a membership, and open a billing portal from your server.

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.

> [!NOTE]
>
> 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](https://partner-help.letsdothis.com/api-reference/overview.md). Server integrations use an unrestricted
organizer key; [scoped keys](https://partner-help.letsdothis.com/api-reference/scoped-keys.md) receive `403`.
For apps that call the API as a signed-in member, use
[member access with OAuth](https://partner-help.letsdothis.com/api-reference/member-access.md). 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](https://partner-help.letsdothis.com/api-reference/member-access.md) 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](https://partner-help.letsdothis.com/api-reference/endpoints/membership/quote-a-membership-cancellation.md)
  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](https://partner-help.letsdothis.com/api-reference/member-access.md), 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](#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](https://partner-help.letsdothis.com/api-reference/endpoints/membership/list-membership-seats.md) 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](https://partner-help.letsdothis.com/api-reference/endpoints/membership/get-a-membership-dashboard.md) for its status, renewal and price.
3. Read the seat's [entries](https://partner-help.letsdothis.com/api-reference/endpoints/membership/list-the-races-linked-to-a-seat.md) and
   [member details](https://partner-help.letsdothis.com/api-reference/endpoints/membership/read-member-details.md) as your app needs them.
4. Open a [billing portal session](https://partner-help.letsdothis.com/api-reference/endpoints/membership/create-a-membership-billing-portal-session.md) 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}`:

```json theme={null}
{
  "customFields": [
    { "id": "nationality-question-id", "value": "Danish" },
    { "id": "training-group-question-id", "values": ["Morning", "Weekend"] }
  ]
}
```

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:

| Question type | Allowed values | Answer property |
| - | - | - |
| `SELECT`, `RADIO_BUTTONS` | `optionValues` | `value` |
| `CHECK_BOXES` | `optionValues` | `values` |

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:

```json theme={null}
{
  "id": "gender-question-id",
  "name": "Gender identity",
  "type": "SELECT",
  "required": false,
  "editable": true,
  "answerShape": "value",
  "optionValues": ["Woman", "Man", "Non-binary"],
  "answer": { "value": "Non-binary" }
}
```

Update gender through the member-details endpoint:

```json theme={null}
{ "gender": "Non-binary" }
```

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](https://partner-help.letsdothis.com/api-reference/member-access.md); with a member token only the
policy's primary member can call them.

| Step | Endpoint |
| - | - |
| [Quote](https://partner-help.letsdothis.com/api-reference/endpoints/membership/quote-a-membership-cancellation.md) what would happen | `GET /v0/membership-policies/{policyId}/cancellation-quote` |
| [Cancel](https://partner-help.letsdothis.com/api-reference/endpoints/membership/cancel-a-membership-policy.md) | `POST /v0/membership-policies/{policyId}/cancel` |
| [Read](https://partner-help.letsdothis.com/api-reference/endpoints/membership/get-a-policys-pending-change.md) what is pending | `GET /v0/membership-policies/{policyId}/pending-change` |
| [Withdraw](https://partner-help.letsdothis.com/api-reference/endpoints/membership/withdraw-a-policys-pending-change.md) it | `POST /v0/membership-policies/{policyId}/pending-change/withdraw` |

### Who can do what

| | Member token | Organizer key |
| - | - | - |
| `cancelWhen: END_OF_BILLING_PERIOD` | Allowed; the scheme's notice period applies | Allowed; no notice period |
| `cancelWhen: IMMEDIATELY` | Only when the quote's `memberMayCancelNow` is `true`; otherwise `409` | Always allowed |
| `outstandingInvoices` | Refused with `403`; the scheme's rules decide | `KEEP` (default) or `VOID` |
| `reason`, `note` | Refused with `403` | Optional |
| Withdraw a pending cancellation | Allowed | Allowed |

### 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`.

```bash theme={null}
curl "https://api.letsdothis.com/v0/membership-policies/6731f0c2a4b8e91d5c7f2a10/cancellation-quote" \
  --header "Authorization: Bearer YOUR_API_KEY"
```

A member inside a cooling-off window, with nothing owed:

```json theme={null}
{
  "cancellationEffectiveAt": "2026-12-14T09:30:00.000Z",
  "memberMayCancelNow": true,
  "coolingOff": {
    "window": "afterJoining",
    "endsAt": "2026-11-28T09:30:00.000Z"
  },
  "coolingOffRefundQuote": {
    "refund": {
      "mode": "FULL",
      "amount": { "value": 12000, "currencyCode": "DKK" },
      "paid": { "value": 12000, "currencyCode": "DKK" },
      "daysLeft": null,
      "daysInPeriod": null
    },
    "escalationReason": null,
    "nothingToRefund": false
  },
  "outstandingInvoices": { "count": 0, "amount": null }
}
```

A member outside cooling-off, on a scheme with a notice period, whose latest
renewal is unpaid:

```json theme={null}
{
  "cancellationEffectiveAt": "2027-01-14T09:30:00.000Z",
  "memberMayCancelNow": false,
  "coolingOff": null,
  "coolingOffRefundQuote": null,
  "outstandingInvoices": {
    "count": 1,
    "amount": { "value": 12000, "currencyCode": "DKK" }
  }
}
```

`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:

```bash theme={null}
curl --request POST \
  "https://api.letsdothis.com/v0/membership-policies/6731f0c2a4b8e91d5c7f2a10/cancel" \
  --header "Authorization: Bearer MEMBER_ACCESS_TOKEN" \
  --header "Idempotency-Key: 3f0c1a52-7d7e-4a51-9a3c-2b8a6f2f4d11" \
  --header "Content-Type: application/json" \
  --data '{ "cancelWhen": "END_OF_BILLING_PERIOD" }'
```

```json theme={null}
{
  "policyId": "6731f0c2a4b8e91d5c7f2a10",
  "pendingChange": {
    "id": "6741a9d3c5e7f20b8d1e4c33",
    "kind": "CANCELLATION",
    "timing": "AT_RENEWAL",
    "effectiveAt": "2026-12-14T09:30:00.000Z",
    "requestedAt": "2026-11-19T10:02:11.000Z",
    "requestedByKind": "MEMBER",
    "requestedVia": "PUBLIC_API",
    "cancellationCause": "BY_REQUEST",
    "toOfferingId": null,
    "direction": null,
    "amountDueNow": null,
    "payBy": null,
    "releaseSeatIds": []
  }
}
```

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:

```bash theme={null}
curl --request POST \
  "https://api.letsdothis.com/v0/membership-policies/6731f0c2a4b8e91d5c7f2a10/cancel" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Idempotency-Key: 8b1d6e0a-51c4-4a0e-b3f7-0c9e5d2a7f64" \
  --header "Content-Type: application/json" \
  --data '{
    "cancelWhen": "IMMEDIATELY",
    "outstandingInvoices": "VOID",
    "reason": "DUPLICATE_MEMBERSHIP",
    "note": "Joined twice by mistake; keeping the newer membership."
  }'
```

```json theme={null}
{
  "policyId": "6731f0c2a4b8e91d5c7f2a10",
  "pendingChange": null
}
```

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:

```json theme={null}
{
  "policyId": "6731f0c2a4b8e91d5c7f2a10",
  "pendingChange": null,
  "coolingOffRefund": {
    "outcome": "REFUNDED",
    "amount": { "value": 12000, "currencyCode": "DKK" }
  }
}
```

#### 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.

| `reason` | Use it when |
| - | - |
| `REQUESTED_BY_MEMBER` | The member asked you to cancel |
| `UNPAID_FEES` | You are cancelling because fees went unpaid |
| `BREACH_OF_TERMS` | The member broke your membership terms |
| `DUPLICATE_MEMBERSHIP` | The member holds another membership |
| `OTHER` | None of the above; say more in `note` |

`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:

| `cancellationCause` | Meaning |
| - | - |
| `BY_REQUEST` | The member or the organizer asked for it |
| `NON_PAYMENT` | A renewal went unpaid; paying it calls the cancellation off |

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.

```bash theme={null}
curl --request POST \
  "https://api.letsdothis.com/v0/membership-policies/6731f0c2a4b8e91d5c7f2a10/pending-change/withdraw" \
  --header "Authorization: Bearer MEMBER_ACCESS_TOKEN"
```

```json theme={null}
{ "withdrawn": true, "kind": "CANCELLATION" }
```

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:

```json theme={null}
{
  "code": "MEMBERSHIP_CANCELLATION_OUTSIDE_COOLING_OFF",
  "statusCode": 409,
  "message": "The member cannot cancel immediately outside a cooling-off window"
}
```

| Status | `code` | What to do |
| - | - | - |
| `403` | `MEMBERSHIP_CANCELLATION_INVOICE_CHOICE_NOT_PERMITTED` | A member token sent `outstandingInvoices`; leave it out |
| `403` | `MEMBERSHIP_CANCELLATION_DETAILS_NOT_PERMITTED` | A member token sent `reason` or `note`; leave them out |
| `409` | `MEMBERSHIP_CANCELLATION_IN_PROGRESS` | Another cancellation of this policy is running; retry shortly, same key |
| `409` | `MEMBERSHIP_CANCELLATION_OUTSIDE_COOLING_OFF` | The member can't cancel immediately; offer `END_OF_BILLING_PERIOD` |
| `409` | `MEMBERSHIP_CANCELLATION_NO_BILLING_PERIOD` | Nothing bills this membership, so it has no period end; cancel immediately |
| `409` | `MEMBERSHIP_PENDING_CHANGE_WITHDRAWAL_REFUSED` | The pending change can't be withdrawn, for example nothing is left to renew |
| `422` | `MEMBERSHIP_IDEMPOTENCY_KEY_REUSED` | The key was used for a different request; send a new key |

## 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](https://partner-help.letsdothis.com/api-reference/endpoints/membership/list-membership-waitlist-entries.md)
   with `status=WAITING` to see who you can select, oldest first.
2. [Select](https://partner-help.letsdothis.com/api-reference/endpoints/membership/select-a-membership-waitlist-entry.md)
   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](https://partner-help.letsdothis.com/api-reference/endpoints/membership/read-a-membership-waitlist-entry.md)
   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`](https://partner-help.letsdothis.com/api-reference/endpoints/membership/list-membership-seats).
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:

| Parameter | Effect |
| - | - |
| `createdAt[after]`, `createdAt[before]` | Seats created after or before a date-time (exclusive) |
| `updatedAt[after]`, `updatedAt[before]` | Seats whose record changed after or before a date-time |
| `sort[createdAt]`, `sort[updatedAt]` | `1` for oldest first, `-1` for newest first; one at a time |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.