Endpoint

Create a payment link

POST/v1/payment_links

Creates a payment link and returns the payment_link object. Send an Idempotency-Key: a retry with the same key and body gets the first answer again, so it never creates a second payment link.

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

Parameters

Parameters of Create a payment link
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 payment link
Field	Type	Meaning
`name`required	string	Shown as the page title. Up to 200 characters.
`amount_type`	string	Default `fixed`. One of `fixed`, `open`.
`amount`	string	For `fixed` without `line_items`. Pattern `^\d+(\.\d+)?$`.
`currency`required	string	Pricing currency.
`min_amount`	string	For `open`. Default the equivalent of US$1.00. Pattern `^\d+(\.\d+)?$`.
`max_amount`	string	For `open`. Default and ceiling: the tier's per-order maximum. Pattern `^\d+(\.\d+)?$`.
`line_items`	array of values	`[{price, quantity, adjustable_quantity: {enabled, minimum, maximum}}]`, up to 20.
`collect`	object	As on a checkout session.
`success_url`	string	Default: the receipt page.
`allow_publishable_key`	boolean	Lets the embeddable button create sessions for this link with a `pk_` key. Default `true`.
`order_expiry_seconds`	integer	900 to 604,800. Default 3,600.
`max_uses`	integer	Stop after this many paid orders.
`expires_at`	string (date-time)	Stop creating orders after this time.
`metadata`	object	Your own key-value data (rules in Metadata).

Example request

curl

curl https://api.orrerie.com/v1/payment_links \
  -H "Authorization: Bearer $ORRERIE_SECRET_KEY" \
  -H "Idempotency-Key: 8f14e45f-ceea-467f-a9d2-6f1c2b3d4e5a" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ethiopia Yirgacheffe, 1 kg",
  "currency": "USD",
  "line_items": [
    {
      "price": "price_mbk5s5r45kwheaq89dbmk2gz",
      "quantity": 1,
      "adjustable_quantity": {
        "enabled": true,
        "minimum": 1,
        "maximum": 10
      }
    }
  ],
  "success_url": "https://acme.example/thanks"
}'

JavaScript

const response = await fetch("https://api.orrerie.com/v1/payment_links", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ORRERIE_SECRET_KEY}`,
    "Idempotency-Key": "8f14e45f-ceea-467f-a9d2-6f1c2b3d4e5a",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Ethiopia Yirgacheffe, 1 kg",
    "currency": "USD",
    "line_items": [
      {
        "price": "price_mbk5s5r45kwheaq89dbmk2gz",
        "quantity": 1,
        "adjustable_quantity": {
          "enabled": true,
          "minimum": 1,
          "maximum": 10
        }
      }
    ],
    "success_url": "https://acme.example/thanks"
  }),
});
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/payment_links",
    headers={"Authorization": f"Bearer {os.environ['ORRERIE_SECRET_KEY']}", "Idempotency-Key": "8f14e45f-ceea-467f-a9d2-6f1c2b3d4e5a"},
    json={
        "name": "Ethiopia Yirgacheffe, 1 kg",
        "currency": "USD",
        "line_items": [
            {
                "price": "price_mbk5s5r45kwheaq89dbmk2gz",
                "quantity": 1,
                "adjustable_quantity": {
                    "enabled": True,
                    "minimum": 1,
                    "maximum": 10,
                },
            },
        ],
        "success_url": "https://acme.example/thanks",
    },
    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/payment_links');
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([
        'name' => 'Ethiopia Yirgacheffe, 1 kg',
        'currency' => 'USD',
        'line_items' => [
            [
                'price' => 'price_mbk5s5r45kwheaq89dbmk2gz',
                'quantity' => 1,
                'adjustable_quantity' => [
                    'enabled' => true,
                    'minimum' => 1,
                    'maximum' => 10,
                ],
            ],
        ],
        'success_url' => 'https://acme.example/thanks',
    ]),
]);
$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 payment_link object. Headers: Orrerie-Request-Id.

Example response, 201

{
  "id": "plink_gg6as78pk82ndt25m36vjeey",
  "object": "payment_link",
  "livemode": true,
  "created": "2026-09-10T10:05:00.000Z",
  "updated": "2026-09-10T10:05:00.000Z",
  "active": true,
  "name": "Ethiopia Yirgacheffe, 1 kg",
  "url": "https://pay.orrerie.com/l/plink_gg6as78pk82ndt25m36vjeey",
  "amount_type": "fixed",
  "amount": "21.99",
  "currency": "USD",
  "min_amount": null,
  "max_amount": null,
  "line_items": [
    {
      "price": "price_mbk5s5r45kwheaq89dbmk2gz",
      "quantity": 1,
      "adjustable_quantity": {
        "enabled": true,
        "minimum": 1,
        "maximum": 10
      }
    }
  ],
  "collect": {
    "email": "required",
    "name": "optional",
    "shipping_address": "hidden"
  },
  "success_url": "https://acme.example/thanks",
  "allow_publishable_key": true,
  "order_expiry_seconds": 3600,
  "max_uses": null,
  "uses": 0,
  "paid_uses": 0,
  "expires_at": 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

This call has no error of its own. It answers with the errors every call can answer with: a bad key, a missing scope, an object that does not exist, the rate limit. Every error code has its own entry.