> For the complete documentation index, see [llms.txt](https://developers.memberspace.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.memberspace.com/admin-api/endpoints/memberships.md).

# Memberships

Enrollments linking members to the plans they are on.

## List memberships

> Returns the API key's site memberships, ordered by id and paginated with an opaque cursor. Filter by plan, member, status, and creation, renewal, or expiration date to answer questions like "which active memberships on plan X renew in the next three months."

```json
{"openapi":"3.2.0","info":{"title":"MemberSpace Admin API","version":"1.0.0"},"tags":[{"name":"memberships","description":"Enrollments linking members to the plans they are on."}],"servers":[{"url":"https://api.memberspace.com/admin/v1","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Opaque Admin API key, prefixed with `ms_admin_`. Pass it as `Authorization: Bearer ms_admin_...`."}},"parameters":{"cursor-header":{"name":"X-Cursor","in":"header","required":false,"schema":{"type":"string"},"description":"First item to return, usually equals the previous page response's `X-Next-Cursor` response header. Omit to fetch the first page. Cursors are opaque tokens — do not parse or construct them."},"itemsAfter-header":{"name":"X-Items-After","in":"header","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Maximum number of results to return beginning with the cursor, or if not sent the first item in the list (1-100, default 25)."}},"schemas":{"Membership":{"type":"object","description":"A member's enrollment on a plan.","allOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Unique membership identifier."},"memberId":{"type":"integer","description":"The member this membership belongs to."},"planId":{"type":"integer","description":"The plan this membership is on."},"planPublicId":{"type":"string","description":"Public identifier of the plan."},"status":{"type":"string","enum":["active","trialing","pastDue","inactive","expired","canceled","incomplete","incompleteExpired","unpaid"],"description":"Membership state. `active`, `trialing`, and `pastDue` grant access; the rest do not."},"createdAt":{"type":"string","format":"date-time"}},"required":["id","memberId","planId","planPublicId","status","createdAt"]},{"oneOf":[{"type":"object","title":"Free","properties":{"type":{"type":"string","enum":["free"],"description":"The type of plan this membership is on."},"expiresOn":{"type":"string","format":"date-time","description":"If the membership is set to expire, this is the expiration date"}},"required":["type"]},{"type":"object","title":"One Time Payment","properties":{"type":{"type":"string","enum":["oneTimePayment"],"description":"The type of plan this membership is on."},"expiresOn":{"type":"string","format":"date-time","description":"If the membership is going to expire, this is the expiration date"},"billing":{"type":"object","properties":{"currency":{"type":"string","description":"3 letter [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217)."}},"required":["currency"]}},"required":["type","billing"]},{"type":"object","title":"Subscription","properties":{"type":{"type":"string","enum":["subscription"],"description":"The type of plan this membership is on."},"cancelsOn":{"type":"string","format":"date-time","description":"When a scheduled cancellation takes effect. Absent unless cancellation is pending."},"billing":{"type":"object","properties":{"billingPeriodEnd":{"type":"string","format":"date-time","description":"Indicates the date-time when the current billing period ends, and the next one begins."},"currency":{"type":"string","description":"3 letter [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217)."},"paymentFailure":{"type":"boolean","description":"Whether the most recent payment attempt failed."}},"required":["billingPeriodEnd","currency","paymentFailure"]}},"required":["type","billing"]},{"type":"object","title":"Multi-payment","properties":{"type":{"type":"string","enum":["multiPayment"],"description":"The type of plan this membership is on."},"expiresOn":{"type":"string","format":"date-time","description":"If the membership is going to expire, this is the expiration date"},"billing":{"type":"object","properties":{"billingPeriodEnd":{"type":"string","format":"date-time","description":"Only present if not yet fully paid. Indicates the date-time when the current billing period ends, and the next one (if there will be one) begins."},"currency":{"type":"string","description":"3 letter [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217)."},"paymentCountMade":{"type":"integer","description":"Number of payments completed so far."},"paymentCountRequired":{"type":"integer","description":"Total number of payments required to fully pay off the plan."},"paymentFailure":{"type":"boolean","description":"Whether the most recent payment attempt failed."}},"required":["currency","paymentCountMade","paymentCountRequired","paymentFailure"]}},"required":["type","billing"]}]}]},"ApiError":{"type":"object","description":"Error response.","properties":{"errors":{"type":"array","description":"The errors that occurred.","items":{"type":"object","properties":{"path":{"type":"string","description":"`base` for errors not tied to a specific field; otherwise the dotted path of the offending field (e.g. `community.isEnabled`)."},"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"required":["path","code","message"]}}},"required":["errors"]}},"headers":{"hasMoreItemsAfter":{"description":"Whether there are more results after the last item in this page.","schema":{"type":"boolean"}},"nextCursor":{"description":"Opaque cursor for the next page. Omitted when X-Has-More-Items-After is false.","schema":{"type":"string"}},"totalCount":{"description":"Total number of items matching the query across all pages, ignoring pagination.","schema":{"type":"integer"}}},"responses":{"400-InvalidRequest":{"description":"Invalid request (e.g. a malformed cursor).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401-AccessDenied":{"description":"The API key is missing, unknown, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404-NotFound":{"description":"The resource doesn't exist, or the API key lacks the scope to access it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429-RateLimited":{"description":"Rate limit exceeded. Wait the number of seconds in the Retry-After header before retrying.","headers":{"Retry-After":{"description":"Number of seconds to wait before making another request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"paths":{"/memberships":{"get":{"tags":["memberships"],"summary":"List memberships","description":"Returns the API key's site memberships, ordered by id and paginated with an opaque cursor. Filter by plan, member, status, and creation, renewal, or expiration date to answer questions like \"which active memberships on plan X renew in the next three months.\"","parameters":[{"$ref":"#/components/parameters/cursor-header"},{"$ref":"#/components/parameters/itemsAfter-header"},{"name":"planId","in":"query","required":false,"schema":{"type":"integer"},"description":"Only return memberships on this plan."},{"name":"memberId","in":"query","required":false,"schema":{"type":"integer"},"description":"Only return memberships belonging to this member."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","trialing","pastDue","inactive","expired","canceled","incomplete","incompleteExpired","unpaid"]},"description":"Only return memberships with this status."},{"name":"createdAfter","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only return memberships created on or after this ISO 8601 date-time (inclusive)."},{"name":"createdBefore","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only return memberships created before this ISO 8601 date-time (exclusive)."},{"name":"renewsAfter","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only return memberships whose billing.billingPeriodEnd is on or after this ISO 8601 date-time (inclusive)."},{"name":"renewsBefore","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only return memberships whose billing.billingPeriodEnd is before this ISO 8601 date-time (exclusive)."},{"name":"expiresAfter","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only return memberships whose expiresAt is on or after this ISO 8601 date-time (inclusive)."},{"name":"expiresBefore","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only return memberships whose expiresAt is before this ISO 8601 date-time (exclusive)."}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Membership"}}}},"headers":{"X-Has-More-Items-After":{"$ref":"#/components/headers/hasMoreItemsAfter"},"X-Next-Cursor":{"$ref":"#/components/headers/nextCursor"},"X-Total-Count":{"$ref":"#/components/headers/totalCount"}}},"400":{"$ref":"#/components/responses/400-InvalidRequest"},"401":{"$ref":"#/components/responses/401-AccessDenied"},"404":{"$ref":"#/components/responses/404-NotFound"},"429":{"$ref":"#/components/responses/429-RateLimited"}}}}}}
```