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

# Memberships

> Reusable plans: setup fee, trial, billing cycle, minimum term and cancellation rules.

A membership is a plan definition. Subscriptions are created against it, so define the plan once and reuse it for every customer.

| Action | Request |
| - | - |
| Create | `POST /membership` |
| Retrieve | `GET /membership/{membership}` |
| List | `GET /membership?page[number]=1&page[items]=5&archive=false` |
| Modify | `PATCH /membership/{membership}` — unspecified fields are unchanged |

## Create

```bash theme={null}
curl https://api-sandbox.paychoice.com.au/api/v4/membership \
  -u "$PAYCHOICE_USERNAME:$PAYCHOICE_PASSWORD" \
  -H "Accept: application/json" \
  -d merchant_id=$PAYCHOICE_MERCHANT_GUID \
  -d name="Personal50 Plan" \
  -d setup_fee=99 \
  -d "billing_cycle[amount]=48" -d "billing_cycle[length]=1" \
  -d "billing_cycle[unit]=months" -d "billing_cycle[min_length]=3" \
  -d fixed_term=false -d cancellation_fee=150.99 -d charge_remain=false
```

**name** `string` *required*

Membership name.

**billing\_cycle\[amount]** `decimal` *required*

Amount charged each cycle.

**billing\_cycle\[length]** `integer` *required*

Charge every *n* units.

**billing\_cycle\[unit]** `string` *required*

`days`, `weeks`, `months` or `years`.

**billing\_cycle\[min\_length]** `integer` *required*

Minimum contract length, in cycles. Minimum 1.

**setup\_fee** `decimal` (default: 0)

One-off fee at sign-up.

**trial\_period\[amount]** `decimal` (default: 0)

Also `trial_period[length]` (default 0) and `trial_period[unit]` (default `days`).

**fixed\_term** `boolean` (default: false)

`true` ends the membership at the end of the contract; `false` continues until further notice.

**cancellation\_fee** `decimal` (default: 0)

Charged if cancelled before `min_length` is reached.

**charge\_remain** `boolean` (default: false)

On early cancellation, charge the remaining contract value.

**merchant\_id** `uuid`

The merchant the membership belongs to.

```json theme={null}
{
  "status": "Success",
  "code": 201,
  "messages": [ { "message_text": "Data created", "message_type": "success" } ],
  "membership": {
    "id": "3f2a9c1e-7b64-4d8a-9e21-5c0d8f7a1b23",
    "reference_id": 199,
    "name": "Personal50 Plan",
    "setup_fee": 99.00,
    "currency": "AUD",
    "cancellation_fee": "$150.99",
    "fixed_term": false,
    "charge_remain": "Remaining Amount",
    "billing_cycle": { "amount": 48.00, "interval": 3, "length": 1, "unit": "Monthly" },
    "trial_period": false,
    "status": "active",
    "link": { "href": "/api/v4/membership/3f2a9c1e-7b64-4d8a-9e21-5c0d8f7a1b23", "rel": "self" }
  },
  "object_type": "membership",
  "link": { "href": "/api/v4/membership", "rel": "self" }
}
```

**id** `uuid`

The membership ID — use it as `membership_id` when creating a subscription.

**reference\_id** `integer`

Numeric reference, for display.

**billing\_cycle** `object`

`amount`, `interval` (number of instalments in the minimum term), `length` (every *n* units), `unit`.

**trial\_period** `object | false`

`false` when there is no trial; otherwise `amount`, `length`, `unit`.

**fixed\_term** `boolean`

**charge\_remain** `boolean | string`

`true` when no rule is configured; `"Original Amount"` or `"Remaining Amount"` when the remaining contract is charged on early cancellation.

**cancellation\_fee** `string | null`

Cancellation fee label.


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