# Subscriptions

Subscriptions bill a customer's card on a schedule. Setting one up takes three calls.

### 1. Create a customer

`POST /subscriptions-customers/` is an upsert keyed on `email`.

```bash
curl -X POST https://api.intasend.com/api/v1/subscriptions-customers/ \
  -H "Authorization: Bearer $INTASEND_SECRET_KEY" -H "Content-Type: application/json" \
  -d '{"email": "jane@example.com", "first_name": "Jane", "last_name": "Doe", "country": "KE", "reference": "user-42"}'
```

### 2. Create a plan

`POST /subscriptions-plans/` is an upsert keyed on `name`.

```bash
curl -X POST https://api.intasend.com/api/v1/subscriptions-plans/ \
  -H "Authorization: Bearer $INTASEND_SECRET_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Pro monthly", "amount": 1000, "currency": "KES", "frequency": 1, "frequency_unit": "M", "billing_cycles": 12}'
```

`frequency_unit` is `D` (day), `W` (week), `M` (month) or `Y` (year).

### 3. Subscribe the customer

```bash
curl -X POST https://api.intasend.com/api/v1/subscriptions/ \
  -H "Authorization: Bearer $INTASEND_SECRET_KEY" -H "Content-Type: application/json" \
  -d '{"customer_id": "CUSTOMER_ID", "plan_id": "PLAN_ID", "reference": "sub-42", "redirect_url": "https://example.com/done"}'
```

Send the customer to the returned `setup_url` to add their card. The subscription then becomes `ACTIVE`.

## Manage

| Call | Purpose |
|---|---|
| `GET /subscriptions/{id}/` | Details: `status`, `next_date`, `completed_cycles`, `card_mask` |
| `PUT /subscriptions/{id}/` | Change `plan_id`, and optionally `start_date` (`YYYY-MM-DD`, today or later) |
| `GET /subscriptions/{id}/transactions/` | Payments made |
| `POST /subscriptions/{id}/unsubscribe/` | Cancel |

`status` is one of `PENDING`, `ACTIVE`, `CANCELED`, `COMPLETE` or `FAILED`. Changes are sent as the `subscription_event` [webhook](https://developers.intasend.com/guides/webhooks/).