# Subscriptions and payment plans

Bill a customer on a schedule: memberships, retainers, or a fixed number of payments.

```bash
curl -X POST https://paylynks.io/api/v1/subscriptions -H "Authorization: Bearer $PAYLYNKS_SECRET_KEY" \
  -H "Content-Type: application/json" -d '{
    "name": "Pat Lee", "email": "pat@example.com",
    "amount": 4900, "description": "Maintenance plan", "interval": "month", "total_cycles": 12
  }'
```

| Field | Notes |
| --- | --- |
| `amount` | Cents per payment, before card fees. |
| `interval`, `interval_count` | `day`, `week`, `month`, `year`; e.g. every 2 weeks = `week` + `2`. |
| `total_cycles` | Number of payments for a payment plan. Omit for "until canceled". |
| `start_date` | `YYYY-MM-DD`, default today. |
| `customer` or `name`/`email`/`phone` | Who pays. |
| `payment_method` | A saved card to bill. Without it the customer gets a signup link. |
| `send_via`, `sms_consent` | How to send the signup link. |

## Signup link

`subscription.url` (`/sub/<token>`) shows the terms (amount, frequency, start, how to cancel). The customer agrees, adds a card and pays the first payment (or just saves the card if the plan starts later). The same link lets them update their card or cancel.

## Billing and retries

A daily job charges due payments. A failure is retried 3, 5 and 7 days later and the customer is emailed an update-card link; after that the subscription is `unpaid` and stops. Updating the card charges an overdue payment right away. Monthly plans keep the start date's day (Jan 31 → Feb 28 → Mar 31).

Statuses: `incomplete`, `active`, `past_due`, `unpaid`, `paused`, `canceled`, `completed`.

- `POST /:id/pause`, `POST /:id/resume` (skipped periods aren't billed), `POST /:id/cancel`
- `GET /api/v1/subscriptions`, `GET /:id`