# Subscriptions

Building with an AI agent? Start at https://docs.payme.io/agents.md

Recurring payments with subscriptions: the lifecycle, statuses, pausing, template subscriptions, callbacks and iteration types.

A subscription charges a buyer on a fixed schedule. Each iteration is charged separately: unlike an installment sale, nothing is authorized up front. For 100.00 a month over 10 months, each month is charged 100.00, not 1,000.00 at once. 

How charging, retries, callbacks and saved cards work in detail: [Saved cards & recurring](/payments/saved-cards-recurring).

## Endpoints

- [Create a subscription](/payments/subscriptions/post-generate-subscription): `POST /generate-subscription`
- [Pay a subscription](/payments/subscriptions/post-generate-subscription-2): `POST /pay-subscription`
- [Pause a subscription](/payments/subscriptions/post-pause-subscription): `POST /pause-subscription`
- [Resume a subscription](/payments/subscriptions/patch-subscriptions-sub-payme-id-resume): `PATCH /subscriptions/{sub_payme_id}/resume`
- [Update a subscription's price](/payments/subscriptions/patch-subscriptions-sub-id-set-price): `PATCH /subscriptions/{sub_payme_id}/set-price`
- [Cancel a subscription](/payments/subscriptions/postcancel-subscription): `POST /cancel-subscription`
- [List subscriptions](/payments/query-apis/post-get-subscriptions): `POST /get-subscriptions`

## Lifecycle

1. Create the subscription. It starts in status `1` (Initial) and returns `sub_url`, the hosted page where the buyer enters a card. Or send a permanent `buyer_key` to attach a saved card at once.
2. When a card is attached, the status becomes `2` (Active) and PayMe sends `sub-active`.
3. A background job charges each iteration when its date arrives; the first charge runs within about a minute after `sub_start_date`. Each successful charge creates a sale and sends `sub-iteration-success`.
4. If the card check fails when the buyer pays, the status becomes `4` (Failed) and PayMe sends `sub-failure`. The subscription isn't canceled: the buyer can pay again.
5. A failed scheduled charge moves the subscription to status `7` and is retried once a day, up to 7 attempts in total. A daily subscription, and the seventh consecutive failure, are canceled instead (status `5`, `sub-cancel`).
6. After the last iteration, the status becomes `6` (Completed) and PayMe sends `sub-complete`.

## Pausing

While a subscription is paused (status `3`), nothing is charged. Each iteration whose date passes is skipped: it counts in `sub_iterations_skipped`, reduces `sub_iterations_left`, and sends `sub-iteration-skipped`. Resuming doesn't charge skipped iterations and sends no callback. If every remaining iteration is skipped, the subscription becomes `6` (Completed) while still paused.

## Automatic cancellation and blocked sellers

No charges run while the seller's account is blocked. PayMe cancels a subscription automatically after the last failed charge attempt. It also cancels the active subscriptions, and those waiting for a retry, of a seller whose account has been blocked for more than 30 days.

## Template subscriptions

A template (`sub_type` `10`), also called a "Multilink subscription", is one shareable payment link for many buyers. You can post it on a social network, for example. Each buyer who pays it gets their own subscription with its own `sub_payme_id` (`sub_type` `2`). Send the number `10`; the text `template` is rejected.  

| `sub_type` | Meaning |
|---|---|
| `1` | Regular subscription (the default). |
| `2` | A subscription created when a buyer paid a template. You don't send this value. |
| `10` | Template. Its link doesn't expire. |

## Iteration types

| ID | Interval |
|---|---|
| `1` | Daily |
| `2` | Weekly |
| `3` | Monthly. The start day must be between 1 and 28. |
| `4` | Yearly |
| `5` | Quarterly |

## Statuses

| ID | Status |
|---|---|
| `1` | Initial: waiting for the buyer to pay. |
| `2` | Active: a card is attached and charges run on schedule. |
| `3` | Paused: no charges; iterations whose date passes are skipped. |
| `4` | Failed: the card check failed when the buyer paid. No automatic retry; the buyer can pay again. |
| `5` | Canceled: by the seller, or automatically after the last failed attempt. |
| `6` | Completed: all iterations were charged or skipped. |
| `7` | Failed, retry pending: a scheduled charge failed and is retried the next day. |

## Callbacks

PayMe sends callbacks to `sub_callback_url`, or to your partner's default callback URL if you didn't send one. They are `POST` requests of type `x-www-form-urlencoded`. The fields are listed on [Callbacks → Subscriptions](/payments/getting-started/callbacks#subscriptions).

| `notify_type` | When |
|---|---|
| `sub-create` | The subscription was created. |
| `sub-active` | A card was attached and the subscription is active. The first charge follows within about a minute after `sub_start_date`. |
| `sub-iteration-success` | A scheduled charge succeeded. |
| `sub-failure` | A charge failed: the card check when the buyer paid (status `4`), or a scheduled charge that will be retried (status `7`). |
| `sub-pause` | The subscription was paused. |
| `sub-iteration-skipped` | An iteration date passed while the subscription was paused. The iteration is skipped and never charged. |
| `sub-complete` | The last iteration was charged or skipped. |
| `sub-cancel` | The subscription was canceled, by the seller or automatically. |

## Saved cards

To charge a saved card instead of sending the buyer to `sub_url`, pass a permanent `buyer_key` to [Create a subscription](/payments/subscriptions/post-generate-subscription). How to get one: [Saved cards & recurring](/payments/saved-cards-recurring).

## Endpoints

- [Create a subscription](/payments/subscriptions/post-generate-subscription): POST /generate-subscription
- [Pay a subscription](/payments/subscriptions/post-generate-subscription-2): POST /pay-subscription
- [Cancel a subscription](/payments/subscriptions/postcancel-subscription): POST /cancel-subscription
- [Pause a subscription](/payments/subscriptions/post-pause-subscription): POST /pause-subscription
- [Resume a subscription](/payments/subscriptions/patch-subscriptions-sub-payme-id-resume): PATCH /subscriptions/{sub_payme_id}/resume
- [Update a subscription's price](/payments/subscriptions/patch-subscriptions-sub-id-set-price): PATCH /subscriptions/{sub_payme_id}/set-price