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.

​

The flow

1. Create a customer

   A customer record with contact and address details. You get a GUID.

2. Attach a payment method

   Tokenise a card or bank account — via the API or the Create Token page — and attach it to the customer. Attaching it is what stops the token expiring after first use.

3. Define a membership

   A membership is a reusable plan: setup fee, optional trial, billing cycle, minimum term, cancellation rules.

4. Subscribe the customer

   A subscription links a customer to a membership from a start date.

5. PayChoice takes it from there

   The payment schedule lists what will be charged and when. As each item falls due, an invoice is raised and the customer’s default payment method charged. Failed payments can attract a dishonour fee.

​

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:

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

Send Accept: application/json on every Billing request. Without it, errors come back as HTML.

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