Endpoint

Create a draft invoice

POST/v1/invoices

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

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

Parameters

Parameters of Create a draft invoice
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 draft invoice
Field	Type	Meaning
`customer`required	string	A `cus_` id with an email address.
`currency`required	string	An ISO 4217 code, for example `USD`.
`line_items`required	array of values	1 to 100 items: `{price, quantity}` or `{name, unit_amount, quantity}`.
`discount_amount`	string	Subtracted from the subtotal. Pattern `^\d+(\.\d+)?$`.
`tax_amount`	string	Added to the total. Typed by you. Pattern `^\d+(\.\d+)?$`.
`due_date`required	string (date)	`YYYY-MM-DD`, today or later, in the merchant's time zone.
`memo`	string	Up to 2,000 characters, shown on the invoice.
`footer`	string	Up to 500 characters.
`reminders`	object	`{days_before_due: [..], days_after_due: [..]}`, each up to 3 values of 0 to 30. Default `[3]` and `[1, 7]`.
`metadata`	object	Your own key-value data (rules in Metadata).

Example request

curl

curl https://api.orrerie.com/v1/invoices \
  -H "Authorization: Bearer $ORRERIE_SECRET_KEY" \
  -H "Idempotency-Key: 8f14e45f-ceea-467f-a9d2-6f1c2b3d4e5a" \
  -H "Content-Type: application/json" \
  -d '{
  "customer": "cus_8ea07c40qsvv19f7rgmeb8ha",
  "currency": "USD",
  "due_date": "2026-10-22",
  "line_items": [
    {
      "name": "Wholesale beans, 20 kg",
      "unit_amount": "17.50",
      "quantity": 20
    }
  ],
  "memo": "Thank you for your order.",
  "footer": "Acme Coffee Roasters LLC"
}'

JavaScript

const response = await fetch("https://api.orrerie.com/v1/invoices", {
  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",
    "currency": "USD",
    "due_date": "2026-10-22",
    "line_items": [
      {
        "name": "Wholesale beans, 20 kg",
        "unit_amount": "17.50",
        "quantity": 20
      }
    ],
    "memo": "Thank you for your order.",
    "footer": "Acme Coffee Roasters LLC"
  }),
});
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/invoices",
    headers={"Authorization": f"Bearer {os.environ['ORRERIE_SECRET_KEY']}", "Idempotency-Key": "8f14e45f-ceea-467f-a9d2-6f1c2b3d4e5a"},
    json={
        "customer": "cus_8ea07c40qsvv19f7rgmeb8ha",
        "currency": "USD",
        "due_date": "2026-10-22",
        "line_items": [
            {
                "name": "Wholesale beans, 20 kg",
                "unit_amount": "17.50",
                "quantity": 20,
            },
        ],
        "memo": "Thank you for your order.",
        "footer": "Acme Coffee Roasters LLC",
    },
    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/invoices');
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',
        'currency' => 'USD',
        'due_date' => '2026-10-22',
        'line_items' => [
            [
                'name' => 'Wholesale beans, 20 kg',
                'unit_amount' => '17.50',
                'quantity' => 20,
            ],
        ],
        'memo' => 'Thank you for your order.',
        'footer' => 'Acme Coffee Roasters LLC',
    ]),
]);
$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 invoice object. Headers: Orrerie-Request-Id.

Example response, 201

{
  "id": "inv_sxr44t9zk7krg104gmhsqx2p",
  "object": "invoice",
  "livemode": true,
  "created": "2026-10-08T09:00:00.000Z",
  "updated": "2026-10-08T09:00:00.000Z",
  "number": null,
  "status": "draft",
  "overdue": false,
  "customer": "cus_8ea07c40qsvv19f7rgmeb8ha",
  "order": null,
  "currency": "USD",
  "line_items": [
    {
      "name": "Wholesale beans, 20 kg",
      "quantity": 20,
      "unit_amount": "17.50",
      "amount": "350.00",
      "price": null
    }
  ],
  "subtotal": "350.00",
  "discount_amount": "0.00",
  "tax_amount": "0.00",
  "total": "350.00",
  "amount_paid": "0.00",
  "amount_due": "350.00",
  "due_date": "2026-10-22",
  "memo": "Thank you for your order.",
  "footer": "Acme Coffee Roasters LLC",
  "url": null,
  "pdf": null,
  "reminders": {
    "days_before_due": [
      3
    ],
    "days_after_due": [
      1,
      7
    ]
  },
  "finalized_at": null,
  "sent_at": null,
  "paid_at": null,
  "voided_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.