Memberships

Permission: memberships (read / write).

A shop sells membership plans: monthly or yearly dues, an optional initiation fee, family members, guest passes and an optional minimum term. Members get the plan's perks, such as range member rates and member pricing in the store. The shop runs billing. Dues are charged to a saved card, emailed as a pay link, or paid at the register, and every payment is recorded as an order with a membership line. Through the API you read plans and members, sign people up, cancel and use guest passes.

Plans

GET /v1/membership-plans (read). Filter: status (active or archived).

{
  "object": "membership_plan",
  "id": 7,
  "name": "Range Family",
  "description": null,
  "perks": "Up to 4 in the household, unlimited lane time",
  "status": "active",
  "price_cents": 5900,
  "billing_interval": "month",
  "interval_count": 1,
  "initiation_fee_cents": 2500,
  "commitment_months": 6,
  "max_members": 4,
  "guest_passes_per_period": 2,
  "customer_group_id": null,
  "product_id": null,
  "taxable": false,
  "created_at": "2026-09-26T19:40:02Z",
  "updated_at": "2026-09-26T19:40:02Z"
}

Field	Notes
price_cents	Dues for each period, before tax. Members keep the price they joined at, even if the plan changes later.
billing_interval, interval_count	The period length, e.g. month × 3 is quarterly
commitment_months	Minimum term. Cancelling inside it runs to the end of the term.
customer_group_id	Members get that customer group's prices
product_id	The product that sells the plan on the shop's BigCommerce store. A paid online order for it signs the buyer up.

Memberships

GET /v1/memberships (read). Oldest first, cursor-paginated.

Filter	Notes
customer_id	Matches the primary member or a family member
plan_id	One plan
status	One status (see below)
updated_since	ISO-8601 date-time

GET /v1/memberships/{id} (read) also returns the last 50 charges.

{
  "object": "membership",
  "id": 12,
  "number": "M00012",
  "plan_id": 7,
  "customer_id": 1388,
  "location_id": 3,
  "status": "active",
  "billing_method": "card",
  "has_saved_card": true,
  "price_cents": 5900,
  "started_on": "2026-08-05",
  "current_period_start": "2026-09-05",
  "current_period_end": "2026-10-04",
  "next_bill_on": "2026-10-05",
  "commitment_ends_on": "2027-02-04",
  "cancel_at_period_end": false,
  "cancel_reason": null,
  "cancelled_at": null,
  "frozen_until": null,
  "guest_passes_left": 1,
  "source": "register",
  "card_link_url": "https://app.ironregister.com/api/public/card/9b1e…",
  "members": [
    { "customer_id": 1388, "role": "primary", "added_at": "2026-08-05T14:00:00Z" },
    { "customer_id": 1391, "role": "member", "added_at": "2026-08-05T14:03:12Z" }
  ],
  "charges": [
    { "object": "membership_charge", "id": 51, "kind": "dues", "period_start": "2026-09-05", "period_end": "2026-10-04", "amount_cents": 5900, "status": "paid", "due_on": "2026-09-05", "attempts": 1, "last_error": null, "order_id": 9120, "pay_url": null, "paid_at": "2026-09-05T10:00:03Z" }
  ],
  "created_at": "2026-08-05T14:00:00Z",
  "updated_at": "2026-09-05T10:00:03Z"
}

Field	Values / notes
status	See the status table below
billing_method	card (the saved card is charged on the due date and retried if declined), link (a pay link is emailed), counter (paid at the register)
card_link_url	The member's own page for saving a card. Send it to them to move dues onto automatic billing. Saving a card there also pays anything owed.
charges[].kind	signup (the first period plus the initiation fee) or dues
charges[].status	due, failed (card declined), paid, waived, void
charges[].pay_url	A pay link while the charge is unpaid
charges[].order_id	The order that paid it

The status values:

status	Meaning	Perks
pending	Joined, first payment not made	no
active	Paid through current_period_end	yes
past_due	Dues unpaid after the due date (the grace period)	yes
frozen	Billing paused until frozen_until	no
expired	Lapsed: unpaid past the shop's last retry day	no
cancelled	Ended	no

Sign someone up

POST /v1/memberships (write). An Idempotency-Key is accepted.

Field	Required	Notes
customer_id	yes	The primary member (see Customers to create one)
plan_id	yes	An active plan
billing_method	yes	link (later dues are emailed as pay links, which needs the shop to have card processing on) or counter
paid	no	true = the first period was paid on your channel, so the membership starts active. You report the money, so no order is created. Otherwise it waits pending until the first payment is made by its pay link or at the register.
location_id	no	The member's home store. A key limited to certain locations must name one of them; left out, the member is homed at the key's location.
external_reference	no	Your id. Sending it again returns the same membership.

It returns 201 with the membership and its charges. Errors:

• 409 ALREADY_MEMBER: they're already on this plan.
• 422 PLAN_ARCHIVED
• 422 MEMBERSHIPS_OFF: the shop has memberships switched off.
• 422 CARD_PROCESSING_OFF: link billing without card processing.

Cancel

POST /v1/memberships/{id}/cancel (write) with { "reason": "Moving away", "at_period_end": true }. A key limited to certain locations can only cancel memberships whose home store is one of them; others answer 404. Reads and guest passes work across every store.

• By default the membership ends at the close of the paid period, or at the end of the minimum term if that's later. Dues continue until then. The membership shows cancel_at_period_end: true until it ends.
• at_period_end: false ends it now and voids anything owed.

Use a guest pass

POST /v1/memberships/{id}/guest-pass (write), with an optional note. The allowance resets every period. The call returns 422 NO_GUEST_PASSES when there are none left.

Webhooks

Event	When
membership.created	Someone joins
membership.updated	Renewed, past due, frozen, cancelled, lapsed, members or billing changed. The payload adds change (e.g. renewed, past_due, expired, cancelled) and detail.
membership.payment_failed	Dues on a saved card were declined. The shop retries on its schedule.

Dues payments also fire sale.completed for their order.