Endpoint

Create a subscription

POST/v1/subscriptions

Creates the subscription incomplete with its first order; send the customer the first order's pay link yourself: Orrerie emails no customer yet. It becomes active when that order is paid.

Scope a restricted key needs: subscriptions:write
Publishable key: Not allowed: secret or restricted key only
Idempotency-Key: Recommended. It makes a retry safe.

Parameters

Parameters of Create a subscription
Parameter	Type and place	Meaning
`Orrerie-Version`	stringheader	API version date. Default: the version the key was created with. Example `2026-10-11`.
`Idempotency-Key`	stringheader	Makes a retry safe. Kept 24 hours. 1 to 255 characters.

Request body

A JSON object. The body is required. A field the call does not list is refused with parameter_unknown.

Request body of Create a subscription
Field	Type	Meaning
`customer`required	string	A `cus_` id with an email.
`items`required	array of values	1 to 20 `{price, quantity}`; prices must be `recurring` with the same interval and currency.
`reminder_days`	array of values	Days before the period end, up to 3 values of 0 to 30, largest first. Default `[7, 3, 1]`. The first is when the renewal order is created.
`grace_days`	integer	0 to 30. Default 3.
`prepaid_periods_allowed`	array of values	Choices of periods a customer may pay at once, each 1 to 24. Default `[1, 3, 6, 12]`. `[1]` switches prepaying off.
`proration`	string	Default `none`: an underpaid period order does not advance the period. `proportional`: time is granted in proportion to what was paid, rounded down. One of `none`, `proportional`.
`start`	string (date-time)	When the first period starts. Default: when its order is paid.
`trial_days`	integer	Days of trial before the first period (1 to 90): the subscription starts active, with no first order and no checkout link, and the first period is billed when the trial ends. Not together with start. 1 to 90.
`metadata`	object	Your own key-value data (rules in Metadata).

Example request

curl

curl https://api.orrerie.com/v1/subscriptions \
  -H "Authorization: Bearer $ORRERIE_SECRET_KEY" \
  -H "Idempotency-Key: 8f14e45f-ceea-467f-a9d2-6f1c2b3d4e5a" \
  -H "Content-Type: application/json" \
  -d '{
  "customer": "cus_8ea07c40qsvv19f7rgmeb8ha",
  "items": [
    {
      "price": "price_s5n6hhtmyv5erqb81efqgjy6",
      "quantity": 1
    }
  ]
}'

JavaScript

const response = await fetch("https://api.orrerie.com/v1/subscriptions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ORRERIE_SECRET_KEY}`,
    "Idempotency-Key": "8f14e45f-ceea-467f-a9d2-6f1c2b3d4e5a",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "customer": "cus_8ea07c40qsvv19f7rgmeb8ha",
    "items": [
      {
        "price": "price_s5n6hhtmyv5erqb81efqgjy6",
        "quantity": 1
      }
    ]
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
console.log(result);

Python

import os
import requests

response = requests.post(
    "https://api.orrerie.com/v1/subscriptions",
    headers={"Authorization": f"Bearer {os.environ['ORRERIE_SECRET_KEY']}", "Idempotency-Key": "8f14e45f-ceea-467f-a9d2-6f1c2b3d4e5a"},
    json={
        "customer": "cus_8ea07c40qsvv19f7rgmeb8ha",
        "items": [
            {
                "price": "price_s5n6hhtmyv5erqb81efqgjy6",
                "quantity": 1,
            },
        ],
    },
    timeout=30,
)
result = response.json()
if not response.ok:
    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")
print(result)

PHP

<?php
$request = curl_init('https://api.orrerie.com/v1/subscriptions');
curl_setopt_array($request, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('ORRERIE_SECRET_KEY'),
        'Idempotency-Key: 8f14e45f-ceea-467f-a9d2-6f1c2b3d4e5a',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'customer' => 'cus_8ea07c40qsvv19f7rgmeb8ha',
        'items' => [
            [
                'price' => 'price_s5n6hhtmyv5erqb81efqgjy6',
                'quantity' => 1,
            ],
        ],
    ]),
]);
$body = curl_exec($request);
if ($body === false) {
    throw new RuntimeException(curl_error($request));
}
$result = json_decode($body, true);
if (curl_getinfo($request, CURLINFO_HTTP_CODE) >= 400) {
    throw new RuntimeException($result['error']['code'] . ': ' . $result['error']['message']);
}
print_r($result);

Responses

`201` Created

The answer is the subscription object. Headers: Orrerie-Request-Id.

Example response, 201

{
  "id": "sub_9q5v9rq2naessbxsrec2tsw0",
  "object": "subscription",
  "livemode": true,
  "created": "2026-10-01T08:05:00.000Z",
  "updated": "2026-10-01T08:05:00.000Z",
  "status": "incomplete",
  "customer": "cus_8ea07c40qsvv19f7rgmeb8ha",
  "items": [
    {
      "price": "price_s5n6hhtmyv5erqb81efqgjy6",
      "quantity": 1
    }
  ],
  "amount": "18.00",
  "currency": "USD",
  "interval": "month",
  "interval_count": 1,
  "reminder_days": [
    7,
    3,
    1
  ],
  "grace_days": 3,
  "prepaid_periods_allowed": [
    1,
    3,
    6,
    12
  ],
  "proration": "none",
  "current_period_start": null,
  "current_period_end": null,
  "prepaid_until": null,
  "latest_order": "ord_ayyh1f26ajmj807xjy6ezyfd",
  "renewal": {
    "order": "ord_ayyh1f26ajmj807xjy6ezyfd",
    "checkout_url": "https://pay.orrerie.com/c/cs_7e3kh8bs5dfg9zenk3mkvt28",
    "opens_at": "2026-10-01T08:05:00.000Z",
    "due_at": "2026-10-02T08:05:00.000Z",
    "grace_ends_at": "2026-10-02T08:05:00.000Z"
  },
  "cancel_at_period_end": false,
  "cancelled_at": null,
  "paused_at": null,
  "ended_at": null,
  "cancellation_reason": null,
  "metadata": {}
}

Any other status: an error

A status of 400 or above answers with the error object. Branch on its code, never on its message.

Errors

Beside the errors every call can answer with (a bad key, a missing scope, the rate limit), this call answers with:

Errors of Create a subscription
Code	HTTP	Meaning
`price_not_recurring`	409	A subscription item names a `one_time` price, or items mix intervals or currencies.
`customer_email_required`	409	The customer or order has no email address.
`merchant_closing`	403	The business is closing: new orders, payment links and invoices are off, and money goes out only to its own saved addresses. Reads, exports and withdrawals to saved addresses work until it closes.