# Create, list, retrieve, update, and manually pay a subscription

Create, list, retrieve, update, and manually pay a subscription

1. Assign the customer to a payment plan by creating the subscription. The body links the payment plan (`paymentPlanId`) and the stored secure token (`paymentMethod`, where the field is `token`, not `secureTokenId`) and sets `startDate`. `subscriptionId` is the merchant-assigned handle reused by every later step. Requires a unique `Idempotency-Key` header. Returns 201.
 [createSubscription](/api/create-subscription)
2. OPTIONAL — lists subscriptions on the terminal, filtered by customer name, and extracts the first result's `subscriptionId`. The response is paginated — subscriptions are in the `data` array. Skip this step if you already hold the `subscriptionId`.
 [listSubscriptions](/api/list-subscriptions)
3. OPTIONAL — retrieve the subscription to confirm its current state before acting. Surfaces the `status`, the collection `type` (`manual` vs `automatic`), and the `nextDueDate`.
 [getSubscription](/api/get-subscription)
4. OPTIONAL — partially updates the subscription with an RFC 6902 JSON Patch document (the `patchDocument` input: an array of `op`/`path`/`value` operations), NOT a plain resource object. You cannot patch `currentState`, `type`, `frequency`, or `paymentPlan`, and cannot remove `recurringOrder`, `description`, or `name`. Requires a unique `Idempotency-Key` header. Returns 200.
 [updateSubscription](/api/update-subscription)
5. Optional, and ONLY for a `manual`-type subscription. For an `automatic` subscription the terminal collects each payment itself, so running this step would take an unintended extra charge — confirm `type` is `manual` (step 3) before calling it. The body carries an `order` object with the amount to collect. Requires a unique `Idempotency-Key` header. Returns 201, and the `paymentId` for follow-on actions lives at `payment/paymentId`.
 [paySubscription](/api/pay-subscription)

## Workflow diagram

```mermaid
flowchart TD
  step0["1. create subscription request · API"]
  step1["2. subscription search · API"]
  step0 --> step1
  step2["3. subscription lookup · API"]
  step1 --> step2
  step3["4. JSON Patch update · API"]
  step2 --> step3
  step4["5. manual payment request · API"]
  step3 --> step4
```