> ## Documentation Index
> Fetch the complete documentation index at: https://kb.paymentsmojo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Recurring plans

> Create a recurring plan, send its setup link, and follow its payments.

A **recurring plan** charges a customer's card on a schedule. Your system creates the plan; Mojo Payments sends the
customer a setup link, where they authorize it with their card; then each payment is charged on its date. See
[Recurring billing](https://kb.paymentsmojo.com/merchants/recurring-billing.md) for what the merchant and the customer see.

Needs: recurring billing turned on for your account, and an API key with `payments.create` (to create, send, pause,
resume and cancel) and `payments.view` (to read).

## Create one

Pick the MID it's paid to (`GET /accounts`, its `id`), then:

```bash theme={null}
curl https://api.paymentsmojo.com/recurring-plans \
  -H "Authorization: Bearer eyJ…" \
  -H "Idempotency-Key: plan-hlg-2041" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantAccountId": "4d2a9c71-8e3b-4f05-b6d2-91c7e0a5f318",
    "description": "Office coffee service",
    "amount": 249.00,
    "frequency": "Monthly",
    "startDate": "2026-11-01",
    "reference": "HLG-2041",
    "customerCompany": "Harbor Law Group",
    "customerName": "Morgan Lee",
    "customerEmail": "morgan@example.com",
    "lines": [
      { "description": "Brewer rental and service", "quantity": 1, "unitCost": 99.00 },
      { "description": "Coffee, 12 lb", "quantity": 1, "unitCost": 150.00 }
    ]
  }'
```

| Field | Rules |
| - | - |
| `description` | Required, up to 200 characters: what the customer is paying for. |
| `amount` | Required: each payment, $0.01 to $999,999.99. |
| `frequency` | Required: `Weekly`, `Biweekly`, `Monthly`, `Quarterly` or `Yearly`. |
| `startDate` | The first payment's date, from today to a year ahead; today when left out. Monthly, quarterly and yearly plans keep its day of the month (the 31st falls on a shorter month's last day). |
| `totalPayments` | How many payments in all, 1 to 1,000; left out, the plan runs until cancelled. |
| `customerEmail` | Required: it's how Mojo Payments knows the customer. |
| `customerCompany`, `customerName` | At least one. |
| `customerPhone`, `delivery` | `delivery` is `Email` (default) or `Text`; a text needs a US phone number. |
| `reference`, `poNumber`, `memo` | Optional: your own reference (up to 50 characters), the customer's PO (up to 36), a note (up to 500). |
| `lines` | Optional: what each payment covers (`description`, `quantity`, `unitCost`, and optionally `uom`, `commodityCode`, `upc`). They must add up to `amount`, and go with each payment as Level 3 data. |
| `send` | `false` creates the plan and its link without sending anything. |

The answer (`201`) is the plan, with its `id`, `status` (`PendingSetup`) and the customer's `link`. Send an
[`Idempotency-Key`](https://kb.paymentsmojo.com/developers/idempotency) so a retry can't create it twice.

Nothing is charged until the customer authorizes the plan on its page. If its first payment is today, it's charged then;
otherwise the card is checked (nothing charged) and the first payment comes on its date.

## Send the link again

`POST /recurring-plans/{id}/send` sends the setup link again, while the customer hasn't authorized the plan. `sentAt`,
`sentVia` and `sendProblem` say what happened.

## Follow it

`GET /recurring-plans/{id}` gives the plan with its lines (`lineItems`), every payment made or tried (`charges`), and
the card it charges (`cardLastFour`, `cardExpiry`). `GET /recurring-plans` lists them a page at a time
([Pagination](https://kb.paymentsmojo.com/developers/pagination.md)): `q` searches the description, reference, PO, the customer's company, name,
email and phone, the note, MID, location and amount; `status` keeps one status.

| `status` | Means |
| - | - |
| `PendingSetup` | Waiting for the customer to authorize it. |
| `Active` | Charging on schedule. `nextChargeDate` is the next payment; `failedAttempts` and `problem` show a retry after a decline. |
| `Paused` | Not charging (`pausedAt`, `pausedByName`). Mojo Payments pauses a plan when a payment's outcome is unknown. |
| `Completed` | All `totalPayments` were made. |
| `Cancelled` | Cancelled by the merchant or the customer (`cancelledBy`, `cancelReason`). |
| `Failed` | A payment was declined on every try. |

Each entry in `charges` is one try: `period` (which payment), `attempt`, `scheduledFor`, `amount`, `status`
(`Approved`, `Declined` or `Unconfirmed`), the processor's `retRef` and `authCode`, `lastFour` and `message`. A declined
payment is tried again on the merchant's retry days, as a new attempt of the same period.

To hear about changes rather than poll, use [webhooks](https://kb.paymentsmojo.com/developers/webhooks.md): `recurringPlan/created`, and
`recurringPlan/updated` on authorization, every charge, a card change, pause, resume, cancel and completion.

## Pause, resume or cancel

| Call | Does |
| - | - |
| `POST /recurring-plans/{id}/pause` | Stops charging an `Active` plan. Payments due while paused are skipped, not caught up. |
| `POST /recurring-plans/{id}/resume` | Starts a `Paused` plan again from its next payment date on or after today. |
| `POST /recurring-plans/{id}/cancel` | Ends the plan for good, with an optional `{"reason": "…"}`. Payments already made stay made. The customer is told. |

A call that doesn't fit the plan's status (pausing a cancelled plan, say) answers `422` with what's wrong.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.