Plans and Subscriptions

Plans and Subscriptions let you define multi-payment schedules and then attach those schedules to customers (Payers) so Pinch can automatically generate and manage the resulting payments.

---

What you build

Plan (template)

A Plan is the reusable template that describes how to take payments over time. A plan can include:

• Fixed payments: one-off payments scheduled on specific dates/offsets.
• Recurring payments: a repeating schedule.
• Amounts in either:
  • fixed cents (e.g., $50.00 = 5000), and/or
  • percentage of a total (0.0–1.0), which requires a subscription total to calculate actual payment amounts.

Subscription (instance)

A Subscription is a customer-specific instance of a plan. It binds:

• a Plan
• a Payer
• and (optionally/conditionally) a Total Amount

…into an actual schedule of dated payments.

---

Recommended integration flow

1. Create a Plan (once, or as needed when your pricing changes) This can be done through the portal or directly with the API.
2. Preview the calculated payment schedule (optional but recommended for UX and validation).
3. Create a Subscription for a payer against that plan.
4. List and fetch subscriptions for your records and customer support.
5. Cancel subscriptions when needed.

---

Plans API

List plans (paged)

GET /plans?page=1&pageSize=50

Returns a paginated list of plans for the authenticated merchant.

Get a plan

GET /plans/{planId}

Fetches a single plan.

Create or update a plan

POST /plans

Creates a new plan or updates an existing plan depending on whether the request body includes an id.

Implementation detail:

• If id is empty: returns 201 Created
• If id is present: returns 200 OK

Caveats you must design around

• Plans can only be edited if they have no subscriptions attached.
• There is currently no “move subscribers to a new plan” operation; typical approach is cancel + recreate.

Delete a plan

DELETE /plans/{planId}

Deletes the plan.

Important: deleting a plan also cancels the plan’s subscriptions and future scheduled payments:

Docs note:

“Deleting a plan will cancel all subscriptions attached to the plan… and cancel any payments… not yet been taken.”

Preview calculated payments for a plan

GET /plans/{planId}/calculated-payments

Query parameters:

• startDate (optional)
• totalAmount (optional, cents)
• skip / limit (optional)

This endpoint returns the computed schedule (dates + amounts) that would result from subscribing to the plan under the given inputs.

Use it to:

• show a customer a schedule before they commit
• validate that a percentage-based plan computes correctly for a given total amount
• implement internal quoting

---

Subscriptions API

Create a subscription

POST /subscriptions

Creates a new subscription (instance of a plan) for the authenticated merchant.

The Engine maps the request into SubscriptionCreateOptions including:

• planId
• payerId
• totalAmount (when required)
• startDate
• currency
• sourceId
• plus merchant identifiers

List subscriptions (paged)

GET /subscriptions?page=1&pageSize=50

Get a subscription

GET /subscriptions/{subscriptionId}

List subscriptions for a payer

GET /subscriptions/payer/{payerId}

Useful when your system is payer-centric (e.g., “show this customer all their active repayment plans”).

List subscriptions for a plan (paged)

GET /subscriptions/plan/{planId}?page=1&pageSize=50

Useful for back-office screens (“who is currently subscribed to this plan?”).

Cancel a subscription

DELETE /subscriptions/{subscriptionId}

Cancels the subscription.

---

When is totalAmount required?

Some plans contain percentage-based payments (or “pay until fully paid” styles) and therefore require a total subscription amount to calculate payment amounts.

Pinch surfaces this in plan responses via requiresTotalAmount:

Integrator guidance:

• If requiresTotalAmount = true, you should collect and provide totalAmount when creating the subscription.
• Use the calculated payments endpoint to confirm the schedule you will be creating.

---

Operational considerations for integrators

• Plan versioning strategy: because plans can’t be edited once they have subscribers, treat plans as versioned templates (e.g., “Plan A v1”, “Plan A v2”) and subscribe new customers to the latest version.
• Destructive deletes: deleting a plan has cascading impact (subscriptions + future payments). Consider restricting this action in your UI or requiring confirmation.
• Preview before commit: use /plans/{id}/calculated-payments to generate accurate schedules for customer-facing disclosures.