> ## 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.

# Recurring billing overview

> Customers, memberships, subscriptions, payment schedules and invoices — and the response format they share.

The Billing API lets PayChoice run recurring charges for you. You describe the plan and the customer; PayChoice generates the schedule, raises invoices, charges the stored payment method as each item falls due, and tells you the outcome by [webhook](https://developers.paychoice.com.au/getting-the-result/webhooks.md).

## The flow

**1. Create a customer**

A [customer](https://developers.paychoice.com.au/billing/customers.md) record with contact and address details. You get a GUID.

**2. Attach a payment method**

Tokenise a card or bank account — via the [API](https://developers.paychoice.com.au/storing-payment-methods/tokens.md) or the [Create Token page](https://developers.paychoice.com.au/storing-payment-methods/create-token-page.md) — and [attach it](https://developers.paychoice.com.au/billing/payment-methods.md) to the customer. Attaching it is what stops the token expiring after first use.

**3. Define a membership**

A [membership](https://developers.paychoice.com.au/billing/memberships.md) is a reusable plan: setup fee, optional trial, billing cycle, minimum term, cancellation rules.

**4. Subscribe the customer**

A [subscription](https://developers.paychoice.com.au/billing/subscriptions.md) links a customer to a membership from a start date.

**5. PayChoice takes it from there**

The [payment schedule](https://developers.paychoice.com.au/billing/payment-schedule.md) lists what will be charged and when. As each item falls due, an [invoice](https://developers.paychoice.com.au/billing/invoices.md) is raised and the customer's default payment method charged. Failed payments can attract a [dishonour fee](https://developers.paychoice.com.au/billing/dishonour-fees.md).

## Response envelope

Billing responses use a different envelope from the payment endpoints. Every success looks like this, with the payload under a key named by `object_type`:

```json theme={null}
{
  "status": "Success",
  "code": 200,
  "messages": [
    { "message_text": "Data Selected", "message_type": "success" }
  ],
  "customer": { "...": "..." },
  "object_type": "customer",
  "link": { "href": "/api/v4/customer/{id}", "rel": "self" }
}
```

**status** `string`

Always `"Success"` on a successful call.

**code** `integer`

`201` when a record was created, otherwise `200`. The HTTP status is `200` in both cases.

**messages** `array`

One item: `message_text` and `message_type` (`success`).

**\<object\_type>** `object | array`

The payload, e.g. `customer`, `membership`, `subscription_list`.

**from\_item / to\_item / total\_count** `integer`

Paginated lists only (customers, memberships, subscriptions). `null` on an empty page.

## Errors

> [!WARNING]
>
> Send `Accept: application/json` on every Billing request. Without it, errors come back as HTML.

```json theme={null}
{
  "status": false,
  "code": 422,
  "messages": [
    { "message_text": "The email field is required.", "message_type": "error", "message_field": "email" }
  ],
  "message": "The given data was invalid."
}
```

`status` is `false`, `code` matches the HTTP status, and `messages` has one item per problem (`message_field` on validation errors). `message` is `Unauthorized` (401), `Forbidden` (403), `Not Found` (404) or `The given data was invalid.` (422). See [Errors](https://developers.paychoice.com.au/reference/errors.md) for the full list.

## Identifiers

Customers, memberships, subscriptions, payment-schedule items and invoices are identified by **GUID** in URLs and in each object's `id`. Objects also expose an integer `reference_id` (or `customer_id` / `invoice_number`) for display; don't use the integer in URLs.

## Request format

Billing endpoints are documented with v4 form-data; `/api/v5/` accepts the same fields as JSON. URLs are case-sensitive.


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