## How it works

Subscriptions connect a customer and recurring catalog price to the shop's billing processor. Processor capabilities determine which lifecycle actions can be offered.

## Implementation

Select the shop for every subscription request. A catalog recurring price must be mapped to the processor, or choose a supported provider plan. /subscriptions/create prepares customer confirmation; the checkout uses the subscription ID and short-lived client secret. Retrieve capabilities before exposing pause, resume, cancellation or plan changes. Monitor subscription and invoice events and retain access until the applicable paid period ends. Adopting existing provider subscriptions does not itself charge the buyer.

## Manage subscriptions

| Task | Request |
| --- | --- |
| Retrieve | `GET /subscriptions/{subscription_id}` |
| List | `GET /subscriptions/list` |
| Pause, resume | `POST /subscriptions/{subscription_id}/pause`, `/resume` |
| Cancel | `POST /subscriptions/{subscription_id}/cancel` |
| Change plan | `PUT /subscriptions/{subscription_id}/update` |
| Billing cycles | `GET /subscriptions/{subscription_id}/invoices` |
| Refresh from the processor | `POST /subscriptions/{subscription_id}/sync` |

## Related guides

- [Customers & saved methods](/docs/payment-api/customers/)
- [Products and line items](/docs/payment-api/products/)
- [Hosted checkout](/docs/payment-api/hosted-checkout/)
- [Webhook events](/docs/payment-api/webhooks/)

## Request examples

```bash
curl -X POST https://api.spicepay.net/subscriptions/create \
  -H 'api-key: YOUR_API_KEY' \
  -H 'X-Profile-Id: pro_xxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_id": "cus_xxxxx",
    "product_id": "prd_xxxxx",
    "price_id": "prc_xxxxx",
    "payment_details": {
      "return_url": "https://shop.example/subscription/return"
    }
  }'
```

```
https://checkout.spicepay.net/pay/{merchant_id}/{subscription_id}?cs={client_secret}
```