Ask for an invitation
Menu

Endpoint

Send an invoice by email

POST/v1/invoices/{id}/send

Sends (or sends again) the invoice email with its pay link from the fixed Orrerie sender. At most 5 sends per invoice per 24 hours. In this release payer email is off: the call answers 403 payer_email_off (a permission_error: do not retry) after its own checks, and nothing is sent.

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 Send an invoice by email
ParameterType and placeMeaning
idrequiredstringpathThe id of the invoice.
Orrerie-VersionstringheaderAPI version date. Default: the version the key was created with. Example 2026-10-11.
Idempotency-KeystringheaderMakes a retry safe. Kept 24 hours. 1 to 255 characters.

Request body

A JSON object. The body may be left out. A field the call does not list is refused with parameter_unknown.

Request body of Send an invoice by email
FieldTypeMeaning
tostringOverride the recipient for this send.

Example request

Refused in this release

Every request to this call is answered 403 with payer_email_off. Payer email is off in this release: give the customer the invoice's pay link yourself. Retrying does not change this.

curl

curl https://api.orrerie.com/v1/invoices/inv_sxr44t9zk7krg104gmhsqx2p/send \
  -H "Authorization: Bearer $ORRERIE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

JavaScript

const response = await fetch("https://api.orrerie.com/v1/invoices/inv_sxr44t9zk7krg104gmhsqx2p/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ORRERIE_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
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/inv_sxr44t9zk7krg104gmhsqx2p/send",
    headers={"Authorization": f"Bearer {os.environ['ORRERIE_SECRET_KEY']}"},
    json={},
    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/inv_sxr44t9zk7krg104gmhsqx2p/send');
curl_setopt_array($request, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('ORRERIE_SECRET_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(new stdClass()),
]);
$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

200 OK

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

Example response, 200

{
  "id": "inv_sxr44t9zk7krg104gmhsqx2p",
  "object": "invoice",
  "livemode": true,
  "created": "2026-10-08T09:00:00.000Z",
  "updated": "2026-10-08T09:02:00.000Z",
  "number": "INV-0042",
  "status": "open",
  "overdue": false,
  "customer": "cus_8ea07c40qsvv19f7rgmeb8ha",
  "order": "ord_18ayqdcy8s50t2dp5r257ep3",
  "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": "https://pay.orrerie.com/i/inv_sxr44t9zk7krg104gmhsqx2p",
  "pdf": "file_jgxe7twfcheqtdha9pafpnc3",
  "reminders": {
    "days_before_due": [
      3
    ],
    "days_after_due": [
      1,
      7
    ]
  },
  "finalized_at": "2026-10-08T09:02:00.000Z",
  "sent_at": "2026-10-09T09:00:00.000Z",
  "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

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

Errors of Send an invoice by email
CodeHTTPMeaning
invoice_not_open409Only an open invoice can be sent or voided.
email_limit_reached429More than 5 sends of the same invoice or receipt in 24 hours.
payer_email_off403Orrerie does not email payers in this release, so nothing was sent. Give the customer the link yourself; retrying does not change this. Answered by POST /v1/invoices/{id}/send, POST /v1/receipts/{id}/send and an invoice's finalize with send: true.