Customer Memberships API Documentation
Overview
This collection contains customer memberships — the records of customers enrolled in your organization's membership types. Each record represents one membership owned by a customer, including its status, term dates, billing details, and (for group memberships) the members it covers. This is the collection to pull to learn who your members are.
Each record links to its membership type via membership_id (see the Membership Types collection) and to its owning customer via owner_id (see the Customers collection). For a per-member view with one row per person (including covered group members), see the Members collection.
This collection is read-only: only the list and read operations are supported. Results are ordered by membership start date, newest first.
Memberships that never completed their initial payment (statuses PAY and IPC) are never returned. All other statuses — including active, frozen, ended/cancelled, denied, and not-yet-started memberships — are returned by default. See Statuses and Pulling All Members.
Fields
All fields are read-only. They are grouped below by purpose for readability; all groups appear together in each record.
Member & Owner
| Name | Type | Description |
|---|---|---|
| id | integer | The unique identifier of the customer membership record. This is placed in the URL when making API calls for the membership. |
| url | string (URL) | The unique API URL of the customer membership. |
| owner_id | integer | The identifier of the customer who owns the membership. |
| owner_url | string (URL) | The API URL of the owning customer. |
| owner_first_name | string | The owner's first name. |
| owner_last_name | string | The owner's last name. |
| owner_email | string | The owner's email address. |
| owner_birthday | string (ISO-8601 date) or null | The owner's birthday. |
| owner_home_location_id | integer or null | The identifier of the owner's home location. |
| owner_home_location_name | string or null | The name of the owner's home location. |
| owner_is_member | boolean | Whether the owner is themselves a covered member of the membership (an owner may pay for a membership without being a member of it). |
Membership Type
These fields describe the membership type this record is enrolled in.
| Name | Type | Description |
|---|---|---|
| membership_id | integer | The identifier of the membership type. |
| membership_url | string (URL) | The API URL of the membership type. |
| name | string | The membership type's name. |
| membership_status | string | The membership type's own status (DRA, ACT, or RET) — not the member's status. |
| purchase_type | string | The membership type's purchase type: REC (Recurring), PRE (Prepaid), or BEN (Benefit). |
| interval | string | The membership type's billing interval for recurring types (e.g. MON), or empty for prepaid. See billing intervals. |
| is_group | boolean | Whether this is a group membership covering multiple members. |
| is_youth_programming | boolean | Whether the membership type is a youth programming membership. |
| has_fixed_date_ranges | boolean | Whether the membership type runs over fixed calendar date ranges. |
| duration_years | integer or null | The membership type's duration in years, if applicable. |
| duration_months | integer or null | The membership type's duration in months, if applicable. |
| duration_days | integer or null | The membership type's duration in days, if applicable. |
Status & Dates
| Name | Type | Description |
|---|---|---|
| status | string | The membership's status. One of the statuses. |
| is_pending_staff_approval | boolean | Whether the membership is awaiting staff approval and not yet usable for entry. |
| start_date | string (ISO-8601 date) | The membership's start date, in the local time of your organization. |
| has_started | boolean | Whether the membership has started as of now. A membership with a future start_date has has_started of false. |
| end_date | string (ISO-8601 date) | The membership's end date (or next bill date for recurring memberships), in organization-local time. |
| days_remaining | integer | The number of days remaining (or days frozen, if frozen). |
| membership_cancel_date | string (ISO-8601 date) or null | The scheduled cancellation date, if a cancellation is scheduled. |
| membership_freeze_date | string (ISO-8601 date) or null | The scheduled freeze date, if a freeze is scheduled. |
| membership_unfreeze_date | string (ISO-8601 date) or null | The scheduled unfreeze date, if applicable. |
| new_end_date_if_unfrozen | string (ISO-8601 date) or null | The projected end date if the membership were unfrozen now. Null if not frozen. |
| last_date_frozen | string (ISO-8601 date) or null | The date the membership was last frozen. |
| days_frozen | integer or null | The number of days remaining at the time of freezing; null when frozen until the next bill date. |
| created_at | string (ISO-8601 datetime) | When the membership record was created, as a UTC timestamp. |
| updated_at | string (ISO-8601 datetime) | When the membership record was last updated, as a UTC timestamp. |
Members Covered (Group Memberships)
| Name | Type | Description |
|---|---|---|
| all_customers | list of JSON objects | All members covered by this membership. See the covered member object. |
| customers_less_owner | list of JSON objects | The covered members excluding the owner, in the same shape as all_customers. |
| unlinked_customers | list of JSON objects | Covered people who do not have their own customer account. Each object has id, first_name, and last_name. |
| customer_add_ons | JSON object | A map of customer ID to the list of add-ons currently applied to that member. Keys for unlinked members are prefixed with u. |
| customer_add_ons_to_add | JSON object | Add-ons scheduled to be added at the next billing cycle (recurring memberships only). |
| customer_add_ons_to_remove | JSON object | Add-ons scheduled to be removed at the next billing cycle. |
| customer_add_on_options | list of JSON objects | The add-on options available for this plan and location. |
Billing & Payment
| Name | Type | Description |
|---|---|---|
| billing_amount | string (decimal) | The amount billed each interval for recurring memberships (after any recurring discount); 0 for non-recurring memberships. |
| billing_location_id | integer or null | The identifier of the location used for billing. |
| billing_location_url | string (URL) or null | The API URL of the billing location. |
| billing_location_name | string or null | The name of the billing location. |
| location_id | integer or null | The identifier of the membership's location. |
| location_url | string (URL) or null | The API URL of the membership's location. |
| location_name | string or null | The name of the membership's location. |
| payment_processor_connection_id | integer or null | The identifier of the resolved payment-processor connection. |
| payment_processor_type | string or null | The payment processor type (e.g. Stripe). |
| has_payment_method | boolean | Whether a saved payment method is on file for the membership. |
| payment_method_type | string or null | The type of the saved payment method. |
| payment_method_last4 | string or null | The last four digits of the saved payment method. |
| payment_method_exp_month | integer or null | The expiry month of the saved card. |
| payment_method_exp_year | integer or null | The expiry year of the saved card. |
| upcoming_bill_dates | list of dates | The next bill dates (up to twelve) for recurring memberships; empty otherwise. |
| has_freeze_fee | boolean | Whether a freeze fee applies to this membership. |
| one_off_discount_type | string | The type of any one-off discount: CUR (currency amount) or PER (percentage). |
| one_off_discount_amount | string (decimal) | The amount of any one-off discount. |
| one_off_discount_applies_to_add_ons | boolean | Whether the one-off discount applies to add-ons. |
| one_off_discount_name | string | The name of the one-off discount. |
Recurring memberships additionally include a set of recurring_discount_* fields describing any automatic recurring discount applied to the membership (its type, amount, name, code, and the association, plan, or referral it derives from). These are null for memberships with no recurring discount.
Invoices & Totals
| Name | Type | Description |
|---|---|---|
| last_invoice_id | integer or null | The identifier of the most recent invoice for this membership. |
| last_invoice_amount | string (decimal) or null | The amount of the most recent invoice. |
| last_invoice_tax_amount | string (decimal) or null | The tax amount of the most recent invoice. |
| last_invoice_date | string (ISO-8601 date) or null | The date of the most recent invoice. |
| first_completed_invoice_date | string (ISO-8601 date) or null | The date of the first completed invoice for this membership. |
| total_paid_to_date | string (decimal) | The total amount paid toward this membership to date. |
| total_refunded_to_date | string (decimal) | The total amount refunded for this membership to date. |
Referral, Staff & Other
| Name | Type | Description |
|---|---|---|
| referring_customer_id | integer or null | The identifier of the customer who referred this membership, if any. Accompanied by referring_customer_url, referring_customer_first_name, referring_customer_last_name, referring_customer_birthday, and referring_customer_email. |
| staff_user_id | integer or null | The identifier of the staff member who sold the membership, if any. Accompanied by staff_user_email, staff_user_first_name, and staff_user_last_name. |
| rolling_event_type_id | integer or null | For memberships tied to a rolling event type, the identifier of that event type. |
| rolling_event_type_roster_id | integer or null | The identifier of the associated roster, if any. |
| rolling_event_type_roster_name | string or null | The name of the associated roster, if any. |
| event_granting_benefit_id | integer or null | The identifier of the event that granted this membership as a benefit, if any. |
| event_granting_benefit_name | string or null | The name of the event that granted this membership as a benefit, if any. |
| status_change_logs_url | string (URL) | The API URL of this membership's status-change log sub-collection. |
Covered Member Object
Each entry in all_customers and customers_less_owner is a JSON object with the following fields:
| Name | Type | Description |
|---|---|---|
| id | integer | The covered member's customer ID. |
| member_id | integer | The identifier of the membership-member link record. |
| first_name | string | The covered member's first name. |
| last_name | string | The covered member's last name. |
| is_individually_frozen | boolean | Whether this member is individually frozen. |
| is_pending_addition | boolean | Whether this member is pending addition to the membership. |
| is_pending_removal | boolean | Whether this member is pending removal from the membership. |
| member_freeze_date | string (ISO-8601 date) or null | The member's scheduled freeze date, if any. |
| member_unfreeze_date | string (ISO-8601 date) or null | The member's scheduled unfreeze date, if any. |
Statuses
The two initial statuses below are never returned by this collection; all others are returned.
| Name | Syntax | Returned? |
|---|---|---|
| Awaiting Initial Payment | PAY | No |
| Initial Payment Cancelled | IPC | No |
| Initial Payment Processing | IPP | Yes |
| Active | ACT | Yes |
| Frozen | FRZ | Yes |
| Renewal Payment Pending | PPE | Yes |
| Renewal Payment Processing | PPR | Yes |
| Renewal Payment Failed | PAF | Yes |
| Freeze Payment Pending | FPE | Yes |
| Freeze Payment Processing | FPR | Yes |
| Freeze Payment Failed | FPF | Yes |
| Denied Staff Approval | DEN | Yes |
| Ended (cancelled or expired) | END | Yes |
There is no distinct "future" status: a not-yet-started membership has status ACT with a future start_date and has_started of false.
Filters
See the filtering documentation for more information on how to use filters in the Capitan API.
| Name | Syntax | Description |
|---|---|---|
| Membership Type | membership_id |
Filters for memberships enrolled in the given membership type ID. |
| Status | status_in |
Filters for memberships whose status is one of the given comma-separated codes. For example, ACT,FRZ. |
| Minimum Start Date | start_date_min |
Filters for memberships starting on or after the given date (organization-local). |
| Maximum Start Date | start_date_max |
Filters for memberships starting on or before the given date (organization-local, inclusive). |
| Minimum End Date | end_date_min |
Filters for memberships ending on or after the given date (organization-local). |
| Maximum End Date | end_date_max |
Filters for memberships ending on or before the given date (organization-local, inclusive). |
| Purchase Type | membership_purchase_type |
Filters for memberships whose membership type has the given purchase type (REC, PRE, or BEN). |
| Is Recurring | membership_is_recurring |
If true, filters for recurring memberships; if false, excludes them. |
| Is Group | membership_is_group |
Filters for memberships whose plan is (true) or is not (false) a group membership. |
| Is Youth Programming | membership_is_youth_programming |
Filters for memberships whose plan is (true) or is not (false) a youth programming membership. |
| Owner Home Location | owner_home_location_id |
Filters for memberships whose owner's home location is the given ID. |
| Has Payment Method | has_payment_method |
Filters for memberships that have (true) or do not have (false) a saved payment method. |
Operations
List
Request
GET /api/customer-memberships/
Response
200 OK
{
"count": 540,
"next": "https://api.hellocapitan.com/api/customer-memberships/?page=2",
"previous": null,
"results": [
{
"id": 84213,
"url": "https://api.hellocapitan.com/api/customer-memberships/84213/",
"membership_id": 412,
"name": "Adult Monthly Membership",
"status": "ACT",
"purchase_type": "REC",
"interval": "MON",
"start_date": "2025-03-01",
"has_started": true,
"end_date": "2026-07-01",
"owner_id": 53120,
"owner_first_name": "Jordan",
"owner_last_name": "Rivera",
"owner_email": "jordan.rivera@example.com",
"all_customers": [
{"id": 53120, "member_id": 70881, "first_name": "Jordan", "last_name": "Rivera",
"is_individually_frozen": false, "is_pending_addition": false, "is_pending_removal": false,
"member_freeze_date": null, "member_unfreeze_date": null}
],
"billing_amount": "59.00",
"total_paid_to_date": "885.00",
"created_at": "2025-03-01T16:04:22.511000Z",
"updated_at": "2026-06-01T09:15:03.220000Z",
...
},
...
]
}
Read
Request
GET /api/customer-memberships/84213/
Response
200 OK
{
"id": 84213,
"url": "https://api.hellocapitan.com/api/customer-memberships/84213/",
"membership_id": 412,
...
}
Pulling All Members
To pull every member — active, frozen, ended/cancelled, denied, and not-yet-started — issue an unfiltered, paginated request. No status parameter is required to include non-active records; all statuses except the two never-paid initial states (PAY, IPC) are returned by default.
GET /api/customer-memberships/?page_size=100
Page through results using the next link until it is null; see the pagination documentation. To restrict to current members, filter with status_in=ACT,FRZ. Each record carries an updated_at timestamp you can use to detect changes between snapshots.