Recurring and installment payments

Create a subscription with POST /api/v1/subscriptions. A subscription charges an active saved card for an existing customer at a location you are authorized to use. ACH subscriptions are not supported.

Create Subscription request

Field	Requirement and meaning
`locationId`	Required; approved billing location
`customerId`	Required; customer owning the saved card
`savedPaymentMethodId`	Required at runtime; active saved card for this customer, even though the schema permits null
`planName`	Required nonblank description
`amount`	Required positive integer in minor currency units; `5000` is USD 50.00
`currency`	Required three-letter currency, such as `USD`
`interval`	Required: `DAILY`, `WEEKLY`, `MONTHLY`, `QUARTERLY` or `YEARLY`
`intervalCount`	Positive count of intervals; defaults to `1`
`startDate`	Required date (`YYYY-MM-DD`); determines the billing day
`endDate`	Optional date limiting the subscription's duration
`maxCycles`	Optional positive number of successful billing cycles before completion
`trialPeriodDays`	Optional positive trial length in days
`items`	Optional list of catalog items: required `priceId`, positive `quantity` (default `1`), and optional string-to-string `metadata` map
`metadata`	Optional string map, no more than 50 entries
`taxAmount`	Optional nonnegative tax amount in minor units
`purchaseOrder`	Optional purchase-order reference, up to 64 characters
`customerCode`	Optional customer reference, up to 64 characters

There is no idempotency header on subscription creation. Persist the returned subscription ID; do not blindly repeat a create after a lost response. Locate the existing subscription before creating another.

USD 50 monthly donation

{
  "locationId": "loc_example",
  "customerId": "cus_example",
  "savedPaymentMethodId": "cpm_example",
  "planName": "Monthly donation",
  "amount": 5000,
  "currency": "USD",
  "interval": "MONTHLY",
  "intervalCount": 1,
  "startDate": "2027-01-15"
}

These are illustrative IDs; replace them with your location, customer and saved card. A start date of today bills immediately unless a configured trial defers charging. For monthly billing, choose the desired billing day in startDate.

USD 600 over 12 monthly payments

Use the same request with planName: "12-payment plan" and maxCycles: 12. Each successful cycle charges 5000 minor units. After 12 successful cycles, status becomes COMPLETED and Peak emits subscription.completed with reason: "MAX_CYCLES" and cyclesBilled: 12. Failures do not count as successful paid cycles. You can also set endDate for a date-bounded subscription; completion then uses reason: "END_DATE".

Cancel or replace a card

Cancel with POST /api/v1/subscriptions/{id}/cancel:

{"cancelAt":"END_OF_CYCLE","reason":"Customer requested cancellation"}

Use IMMEDIATELY instead of END_OF_CYCLE to end it now. Read the resulting status; cancellation is not a refund of previous payments.

To change the card on a subscription with an open dunning case, use its subscription-bound hosted recovery link: after successful setup, Peak updates that subscription on the server. The public API does not expose a general-purpose PATCH /api/v1/subscriptions/{id} that accepts savedPaymentMethodId. A standalone setup-intent replacement or a change to the customer's default card does not update existing subscriptions' saved-card references. See retries and card updates for the distinction and subscription webhooks for authoritative events.