# Create a subscription

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

- Sandbox: `POST https://sandbox.payme.io/api/generate-subscription`
- Production: `POST https://live.payme.io/api/generate-subscription`

## Credentials

- Request body field `seller_payme_id` (required): The seller's MPL. Must be in the JSON body on this endpoint.
- Request body field `payme_client_key` (optional): Partners only: your partner key. You can send it in the `PayMe-Partner-Key` header instead. A seller authenticates with `seller_payme_id` alone.

## Overview

Creates a subscription that charges the buyer once per iteration. A new subscription is in status `1` (Initial), and the response returns `sub_url`, the hosted page where the buyer enters a card. To skip that page, send a permanent `buyer_key`: the card is attached at once and the subscription is created in status `2` (Active).

- Each iteration is charged separately: for 50.00 a month over 12 months, each month is charged 50.00.
- Nothing is charged in this call, even with `buyer_key`. A background job that runs once a minute makes every charge, including the first: it runs within about a minute after `sub_start_date` (default: today) once a card is attached.
- If the card check fails when the buyer pays on `sub_url`, the subscription moves to status `4` (Failed) and PayMe sends `sub-failure`. It isn't canceled and isn't retried: the buyer can pay again.
- 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, move to status `5` (Canceled) and send `sub-cancel` instead.
- The response and the callbacks never contain the `buyer_key`. Read it with [Get buyer key](/payments/tokenization/post-get-buyer-key) and `sub_payme_id`.
- `subscription_id` isn't unique: sending the same value twice creates two subscriptions.

To share one payment link with many buyers, send `sub_type` `10` (template). Each buyer who pays it gets their own subscription.

Lifecycle, retries, callbacks and price changes: [Subscriptions overview](/payments/subscriptions) and [Saved cards & recurring](/payments/saved-cards-recurring). 

## Authentication

Send `seller_payme_id` (the seller's MPL) in the JSON body: on this endpoint the `PayMe-Merchant-Key` header alone isn't enough. Partners also send `payme_client_key`, in the body or the `PayMe-Partner-Key` header.

## Errors

Errors return `status_code` `1` with HTTP 500 unless the table says otherwise.

| HTTP | Code | When |
|---|---|---|
| 500 | `1` | A required field is missing. `status_additional_info` names it. |
| 500 | `24` | `sub_type` isn't `1` or `10` (for example the text `template`). |
| 500 | `251` | The `seller_payme_id` matches no seller. |
| 500 | `252` | The seller can't use `sub_currency`. |
| 500 | `352` | `sub_price` is outside your account's range. |
| 500 | `372` | `sub_iteration_type` isn't between `1` and `5`. |
| 500 | `373` | `sub_iterations` isn't `-1` or between 1 and 54. |
| 500 | `374` | `sub_start_date` is before today. |
| 500 | `375` | A monthly subscription starts after the 28th of the month. |
| 500 | `376` | `buyer_key` is a one-time token or can't be used, or `sub_payment_method` needs a `buyer_key`. |

## Parameters

This endpoint takes no path, query or header parameters.

## Request body

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_payme_id` | string | yes | The seller's MPL. Must be in the JSON body on this endpoint. |
| `payme_client_key` | string | no | Partners only: your partner key. You can send it in the `PayMe-Partner-Key` header instead. A seller authenticates with `seller_payme_id` alone. |
| `sub_price` | integer | yes | Price of one iteration, in minor units (`5075` = 50.75). Default range 500–4,000,000; your account may have different limits. Out of range returns error `352`. |
| `sub_currency` | string | yes | ISO 4217 currency code, for example `ILS`. The seller must be allowed to use it (error `252`). |
| `sub_description` | string | yes | What the buyer is paying for. Up to 300 characters. |
| `sub_iteration_type` | integer | yes | Billing interval: `1` Daily, `2` Weekly, `3` Monthly, `4` Yearly, `5` Quarterly. Other values return error `372`. See [Subscription iteration types](/payments/codes-statuses/subscription-iteration-types). |
| `sub_start_date` | string | no | Date of the first charge, `DD/MM/YYYY` or epoch seconds. Default: today. Must be today or later (error `374`). For a monthly subscription the day must be between 1 and 28 (error `375`). Nothing is charged before this date: use it for "charge now, then monthly" after a one-off sale with the same `buyer_key`. |
| `sub_iterations` | integer | no | Number of iterations. `-1` (default) means unlimited; otherwise 1–54. Other values return error `373`. |
| `sub_type` | integer | no | `1` Regular (default) or `10` Template: one shareable payment link, where each buyer who pays gets their own subscription. Send the number: the text `template` is rejected with error `24`. |
| `buyer_key` | string | no | A permanent buyer token to attach instead of sending the buyer to `sub_url` (create it with `buyer_is_permanent: true` on [capture-buyer-token](/payments/tokenization/post-capture-buyer-token)). The subscription is then active at once; the first charge still runs in the background. A one-time token returns error `376`. Don't combine it with `sub_type` `10`. |
| `buyer_business_name` | string | no | With `buyer_key`: the buyer's business name. Send it together with `buyer_business_code`. |
| `buyer_business_code` | string | no | With `buyer_key`: the buyer's business registration number. |
| `sub_payment_method` | string | no | Payment method. Default: `credit-card`. A method other than `credit-card` or `multi` needs a `buyer_key` (error `376`). With `buyer_key` this field is ignored and the token's method is used. |
| `subscription_id` | string | no | Your own reference, up to 50 characters. Not unique: a repeated value creates a second subscription. [List subscriptions](/payments/query-apis/post-get-subscriptions) accepts it as a filter. |
| `sub_callback_url` | string | no | URL that receives the subscription callbacks (`sub-create`, `sub-active`, `sub-iteration-success`, `sub-failure` and the others listed on [Callbacks](/payments/getting-started/callbacks#subscriptions)). Default: your partner's default callback URL, if one is set. No call changes it later. |
| `sub_return_url` | string | no | Where the buyer is sent after paying on `sub_url`. PayMe adds `payme_status`, `payme_signature`, `sub_payme_id`, `subscription_id`, `transaction_id`, `price`, `currency` and `is_foreign_card` to the query string. |
| `sub_indicative_name` | string | no | The buyer's name, stored on the subscription. |
| `sub_email_address` | string | no | Buyer email for subscription emails. When a card is attached, the card holder's email replaces it. |
| `sub_indicative_mobile` | string | no | Buyer mobile number, stored for reference. When a card is attached, the card holder's phone replaces it. |
| `sub_send_notification` | boolean | no | `true` emails the payment link to `sub_email_address` when the subscription is created. Default: `false`. |
| `language` | string | no | Language of the payment page, buyer emails and error messages: `he` (default), `en`, `es`, `ru` or `ar`. |

### Request example

```json
{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "sub_price": 5000,
  "sub_currency": "ILS",
  "sub_description": "Monthly plan",
  "sub_iteration_type": 3,
  "sub_iterations": 12,
  "sub_start_date": "01/12/2026",
  "subscription_id": "order-1001",
  "sub_callback_url": "https://www.example.com/payment/callback",
  "sub_return_url": "https://www.example.com/payment/success",
  "language": "en"
}
```

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/generate-subscription' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "sub_price": 5000,
  "sub_currency": "ILS",
  "sub_description": "Monthly plan",
  "sub_iteration_type": 3,
  "sub_iterations": 12,
  "sub_start_date": "01/12/2026",
  "subscription_id": "order-1001",
  "sub_callback_url": "https://www.example.com/payment/callback",
  "sub_return_url": "https://www.example.com/payment/success",
  "language": "en"
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/generate-subscription", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
    "sub_price": 5000,
    "sub_currency": "ILS",
    "sub_description": "Monthly plan",
    "sub_iteration_type": 3,
    "sub_iterations": 12,
    "sub_start_date": "01/12/2026",
    "subscription_id": "order-1001",
    "sub_callback_url": "https://www.example.com/payment/callback",
    "sub_return_url": "https://www.example.com/payment/success",
    "language": "en"
  }),
});

console.log(await response.text());
```

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/generate-subscription",
    json={
        "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
        "sub_price": 5000,
        "sub_currency": "ILS",
        "sub_description": "Monthly plan",
        "sub_iteration_type": 3,
        "sub_iterations": 12,
        "sub_start_date": "01/12/2026",
        "subscription_id": "order-1001",
        "sub_callback_url": "https://www.example.com/payment/callback",
        "sub_return_url": "https://www.example.com/payment/success",
        "language": "en",
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "sub_price": 5000,
  "sub_currency": "ILS",
  "sub_description": "Monthly plan",
  "sub_iteration_type": 3,
  "sub_iterations": 12,
  "sub_start_date": "01/12/2026",
  "subscription_id": "order-1001",
  "sub_callback_url": "https://www.example.com/payment/callback",
  "sub_return_url": "https://www.example.com/payment/success",
  "language": "en"
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/generate-subscription');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
```

## Responses

### 200 — The subscription was created. (success)

| Field | Type | Description |
| --- | --- | --- |
| `sub_url` | string | The hosted payment page where the buyer enters a card. For a template, the shareable link. |
| `status_code` | integer | `0` on success. |
| `payme_status` | string | `success`. |
| `status_error_code` | integer | `0` on success. |
| `seller_payme_id` | string | The seller's MPL. |
| `seller_id` | string | The partner's own reference for the seller, if the partner set one. Otherwise `null`. |
| `sub_payme_id` | string | PayMe's subscription ID (`SUB…`). Use it in every other subscription call. |
| `sub_payme_code` | integer | PayMe's numeric subscription ID. |
| `subscription_id` | string | Your own reference, as sent when the subscription was created. `null` if you didn't send one. |
| `sub_created` | string | When the subscription was created, `YYYY-MM-DD HH:MM:SS`. |
| `sub_start_date` | string | Date of the first charge, `YYYY-MM-DD HH:MM:SS`. |
| `sub_prev_date` | string | When the last successful charge ran. `null` until the first charge. |
| `sub_next_date` | string | When the next charge is due. Ignore it on a canceled or completed subscription. |
| `sub_status` | integer | Current status. See [Subscription statuses](/payments/codes-statuses/subscription-statuses). |
| `sub_iteration_type` | integer | Billing interval. See [Subscription iteration types](/payments/codes-statuses/subscription-iteration-types). |
| `sub_currency` | string | ISO 4217 currency code, e.g. `ILS`. |
| `sub_price` | integer | Price of one iteration, in minor units (`5000` = 50.00). |
| `sub_description` | string | What the buyer is paying for. |
| `sub_iterations` | integer | Total number of iterations. `-1` means unlimited. |
| `sub_iterations_completed` | integer | Iterations charged successfully. |
| `sub_iterations_skipped` | integer | Iterations skipped while the subscription was paused. They are never charged. |
| `sub_iterations_left` | integer | `sub_iterations` minus completed and skipped iterations. `-1` when unlimited. |
| `sub_paid` | boolean | `true` once a card (buyer token) is attached to the subscription. It does not mean the current iteration was charged. |
| `sub_error_text` | string | The last failure, pause or cancel reason. `null` if there is none. Reasons that PayMe writes are in Hebrew. |
| `sub_payment_date` | string | Returned only when a card is attached: when the card was attached. |
| `buyer_card_mask` | string | Returned only when a card is attached: the masked card number. |
| `buyer_card_exp` | string | Returned only when a card is attached: card expiry, `MMYY`. |
| `buyer_name` | string | Returned only when a card is attached: the card holder's name. |
| `buyer_email` | string | Returned only when a card is attached: the card holder's email. |
| `buyer_phone` | string | Returned only when a card is attached: the card holder's phone, or `null`. |
| `buyer_social_id` | string | Returned only when a card is attached: the card holder's national ID, or `null`. |

```json
{
  "sub_url": "https://sandbox.payme.io/subscription/generate/SUB16885-68336QPL-UQSSS1CC-SYKXI53N",
  "status_code": 0,
  "payme_status": "success",
  "status_error_code": 0,
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "seller_id": null,
  "sub_payme_id": "SUB16885-68336QPL-UQSSS1CC-SYKXI53N",
  "sub_payme_code": 477004,
  "subscription_id": "order-1001",
  "sub_created": "2026-11-09 10:15:00",
  "sub_start_date": "2026-12-01 00:00:00",
  "sub_prev_date": null,
  "sub_next_date": "2026-12-01 00:00:00",
  "sub_status": 1,
  "sub_iteration_type": 3,
  "sub_currency": "ILS",
  "sub_price": 5000,
  "sub_description": "Monthly plan",
  "sub_iterations": 12,
  "sub_iterations_completed": 0,
  "sub_iterations_skipped": 0,
  "sub_iterations_left": 12,
  "sub_paid": false,
  "sub_error_text": null
}
```

### 500 — The request was refused. See the error table. (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `1` on failure. |
| `status_error_details` | string | What went wrong, in the language you asked for (Hebrew by default). |
| `status_additional_info` | string | The field or value concerned. Can be `null`. |
| `status_error_code` | integer | PayMe error code. See the error table above and [Errors](/payments/getting-started/errors). |
| `session` | string | PayMe session ID. Quote it when you contact support. |

```json
{
  "status_code": 1,
  "status_error_details": "Required parameter is missing",
  "status_additional_info": "seller_payme_id",
  "status_error_code": 1,
  "session": "FhT3aXe7"
}
```