Full Subscription Lifecycle with Failure Recovery

Persona: SaaS platform, gym/fitness membership, instalment billing system.

Scenario: Set up a recurring billing schedule for a customer, handle the payment lifecycle including failures, and eventually cancel the subscription. This covers the full arc from sign-up to churn.

Endpoint sequence

1. POST /plans: create the billing template
2. GET /plans/{id}/calculated-payments: preview the schedule before subscribing
3. POST /subscriptions: subscribe a payer to the plan
4. Receive bank-results / transfer webhook events as payments are processed
5. On dishonour: detect, classify, and retry (see Handle a Dishonoured Direct Debit)
6. DELETE /subscriptions/{id}: cancel when the customer churns

Step 1: Create a plan

A plan is the reusable template that defines how payments are collected over time. Create it once; subscribe multiple payers to it.

POST https://api.getpinch.com.au/test/plans
Authorization: ******
pinch-version: 2020.1
Content-Type: application/json

{
  "name": "Monthly Membership - $49",
  "payments": [
    {
      "type": "recurring",
      "amount": 4900,
      "frequency": "monthly",
      "dayOfMonth": 1
    }
  ]
}

Save the returned id (format: pln_XXXXXXXX). See Create or Update Plan for the full schema including percentage-based payments and fixed one-off instalments.

⚠️

Plans cannot be edited once they have active subscriptions. Treat plans as versioned templates: create a new plan (e.g. "Monthly Membership v2") when pricing changes, and subscribe new customers to the updated version.

Step 2: Preview the payment schedule (recommended)

Before subscribing a customer, retrieve the calculated payment schedule to confirm dates and amounts. This is especially important for plans with percentage-based amounts, where a totalAmount is required to compute the actual payment values.

GET https://api.getpinch.com.au/test/plans/pln_XXXXXXXX/calculated-payments?startDate=2026-08-01&totalAmount=49000
Authorization: ******
pinch-version: 2020.1

Example response (truncated):

{
  "payments": [
    { "date": "2026-08-01", "amount": 4900 },
    { "date": "2026-09-01", "amount": 4900 },
    { "date": "2026-10-01", "amount": 4900 }
  ]
}

Use this to show the customer their upcoming payment schedule before they commit.

Step 3: Create the subscription

Bind the plan to a payer. Pinch automatically generates and schedules all the resulting payments.

POST https://api.getpinch.com.au/test/subscriptions
Authorization: ******
pinch-version: 2020.1
Content-Type: application/json

{
  "planId": "pln_XXXXXXXX",
  "payerId": "pyr_XXXXXXXX",
  "sourceId": "src_XXXXXXXX",
  "startDate": "2026-08-01",
  "metadata": "{\"internalSubscriptionId\": \"sub_internal_789\"}"
}

📘

If the plan's requiresTotalAmount is true, you must include totalAmount (in cents) in the subscription creation request. Omitting it will result in a validation error. Check the plan response for this flag before subscribing.

Save the subscription id (sub_XXXXXXXX) in your database.

Step 4: Retrieve subscriptions

To display a customer's active plans or support a cancellation flow, retrieve their subscriptions:

GET https://api.getpinch.com.au/test/subscriptions/payer/pyr_XXXXXXXX
Authorization: ******
pinch-version: 2020.1

Step 5: Handle payment outcomes via webhooks

Subscription-generated payments are processed by the same overnight pipeline as manually created payments. Listen for the same events:

Match events back to subscriptions using the paymentId from each event item. You can retrieve the full list of payments for a subscription via GET /subscriptions/{id}.

For dishonoured payments, follow the Handle a Dishonoured Direct Debit recipe to classify and retry safely.

Step 6: Cancel a subscription

When a customer churns or requests cancellation:

DELETE https://api.getpinch.com.au/test/subscriptions/sub_XXXXXXXX
Authorization: ******
pinch-version: 2020.1

This cancels all future unpaid payments in the subscription. Payments already collected are unaffected. The payer's payment source (bank account or credit card) is not cancelled; it remains active on the payer and can still be used for other payments or subscriptions.

⚠️

Deleting a plan is destructive. Deleting a plan cancels all its subscriptions and all their future scheduled payments in one operation. Restrict this action in your admin UI and require explicit confirmation before proceeding.

Key caveats

• Plan immutability: once a plan has subscribers, it cannot be modified. Build a versioning strategy (e.g. plan-monthly-v1, plan-monthly-v2) into your data model from the start.
• requiresTotalAmount: check this flag on the plan before creating a subscription. If true, you must supply totalAmount at subscription creation time.
• Subscription payments in bank-results: subscription-generated payments appear alongside manually created payments in bank-results events. Filter by paymentId to identify which subscription they belong to.
• No built-in retry: Pinch does not automatically retry dishonoured subscription payments. You must implement retry logic in your webhook handler.

What to do next

• Plans and Subscriptions Guide: full Plans and Subscriptions feature reference
• Handle a Dishonoured Direct Debit: retry logic for failed subscription payments
• Transfer Reconciliation: reconcile settled subscription payments against your records