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

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.

{
  "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.