POST /v1/checkouts
The single call your shop server makes per checkout. It composes three things into one atomic, idempotent operation:
- Find-or-create the client in your Vorgio team, keyed on
client.external_id. - Create a numbered invoice for that client with the positions and tax rate you supplied.
- Queue the invoice email to the client's address (rendered in the client's language).
After the DB transaction commits, Vorgio dispatches the InvoiceSent event, which fires your invoice.sent webhook subscribers (see Webhooks).
Endpoint shape, validation rules, and exact response keys are auto-generated and live at /api-reference. This page is the narrative — the why, the worked examples, the gotchas. Use both side by side.
#Authentication and headers
| Header | Required | Notes |
|---|---|---|
Authorization: Bearer <token> |
yes | Token must have the checkouts:write ability. |
Content-Type: application/json |
yes | |
Idempotency-Key: <unique-string> |
yes | A stable identifier for this checkout. Best practice: derive from the shop's order ID, e.g. wc-order-1234. Reusing a key with the same body returns the original response with Idempotency-Replay: true in the headers. Reusing it with a different body returns 409 Conflict. |
#Request body
Three required nested objects (client, invoice, send) plus optional metadata:
1{
2 "client": {
3 "external_id": "shop_customer_42", // recommended — without it every call creates a new client
4 "name": "Erika Mustermann",
5 "name_addition": null, // optional 2nd line
6 "address": "Musterstraße 1",
7 "address_addition": null, // optional 2nd address line
8 "zip": "10115",
9 "city": "Berlin",
10 "country": "DE", // ISO 3166-1 alpha-2
11 "email": "erika@example.com", // required to send the invoice email
12 "email_cc": [], // optional list
13 "language": "de", // de | en — drives the email + PDF language
14 "rate": 0, // hourly rate in cents (0 if you don't bill by the hour)
15 "vat": 19.0, // default VAT for this client (the per-invoice tax_rate overrides)
16 "default_position_mode": "fixed" // hourly | fixed
17 },
18 "invoice": {
19 "tax_rate": 19.0, // VAT % applied to this invoice
20 "billing_date": "2026-05-10", // optional, defaults to today
21 "due_offset_days": 14, // due_at = billing_date + this
22 "subject": "Order #1234", // optional — appears at the top of the PDF
23 "description": null, // optional long text above the positions
24 "note": null, // optional footer below totals
25 "positions": [
26 {
27 "id": "0193f7b0-1b8a-7b7d-9ad0-0c7b5b1d5f3e",
28 "date": "2026-05-10",
29 "mode": "fixed", // fixed → amount_cents required
30 "description": "1× Widget Pro",
31 "amount_cents": 4990 // €49.90 in cents
32 },
33 {
34 "id": "0193f7b0-1b8a-7b7d-9ad0-0c7b5b1d5f40",
35 "date": "2026-05-10",
36 "mode": "hourly", // hourly → hours required, amount derived from client.rate
37 "description": "Setup support",
38 "hours": 0.5
39 }
40 ]
41 },
42 "send": { // optional — omit entirely to use Vorgio's localized default templates
43 "subject": "Your invoice from Acme Shop", // optional
44 "body": "Hi {client.name}, your invoice {invoice.number} is attached. — Acme Shop", // optional
45 "cc": [] // optional CC list
46 },
47 "metadata": { // optional, free-form, ≤ 16KB JSON
48 "shop_order_id": "1234"
49 }
50}
#What Vorgio computes for you
You don't supply (and shouldn't try to):
client_id— Vorgio derives this fromexternal_id(find-or-create within your team).invoice.number— gapless sequential per(team, type)per German tax-authority rules ("fortlaufende Nummer").invoice.amount_net,tax_amount,amount_total— computed from the positions andtax_rate.invoice.billing_date— defaults to today if you don't supply it (checkouts always issue immediately).invoice.due_at—billing_date + due_offset_daysif you don't supply it.position.amount_centsfor hourly rows —hours × client.rate.send.subject/send.body— if omitted, Vorgio falls back to its localized default templates (language picked fromclient.language). Supply only what you want to override.
#Body templating in send.body
The send.body string supports a small set of placeholders that are substituted per recipient at send time:
{client.name}→ the client's name{invoice.number}→ the issued invoice number (e.g.2026-0042){invoice.amount_total}→ formatted total in the client's locale (e.g.59,38 €){invoice.due_at}→ due date in the client's locale (e.g.24.05.2026)
#Response
201 Created with:
1{
2 "data": {
3 "client_id": "0193f7b0-1b8a-7b7d-9ad0-0c7b5b1d5f3e",
4 "invoice": {
5 "id": "0193f7b0-1b8a-7b7d-9ad0-0c7b5b1d5f99",
6 "number": "1",
7 "amount_total": 5938,
8 "metadata": { "shop_order_id": "1234" }
9 // … full InvoiceResource shape; see /api-reference
10 },
11 "mail_event_id": "12345"
12 }
13}
Plus a Location header pointing at GET /v1/invoices/{id} for follow-up reads.
#Worked examples
#PHP (raw HTTP, no SDK)
1$response = (new GuzzleHttp\Client)->post('https://app.vorgio.example/api/v1/checkouts', [
2 'headers' => [
3 'Authorization' => 'Bearer ' . getenv('VORGIO_TOKEN'),
4 'Idempotency-Key' => 'wc-order-' . $order->get_id(),
5 'Accept' => 'application/json',
6 ],
7 'json' => [
8 'client' => [
9 'external_id' => 'wc_customer_' . $order->get_customer_id(),
10 'name' => $order->get_billing_first_name() . ' ' . $order->get_billing_last_name(),
11 'address' => $order->get_billing_address_1(),
12 'zip' => $order->get_billing_postcode(),
13 'city' => $order->get_billing_city(),
14 'country' => $order->get_billing_country(),
15 'email' => $order->get_billing_email(),
16 'language' => 'de',
17 'rate' => 0,
18 'vat' => 19.0,
19 'default_position_mode' => 'fixed',
20 ],
21 'invoice' => [
22 'tax_rate' => 19.0,
23 'due_offset_days' => 14,
24 'subject' => 'Bestellung #' . $order->get_id(),
25 'positions' => array_map(function ($item) {
26 return [
27 'id' => Ramsey\Uuid\Uuid::uuid4()->toString(),
28 'date' => date('Y-m-d'),
29 'mode' => 'fixed',
30 'description' => $item->get_name() . ' × ' . $item->get_quantity(),
31 'amount_cents' => (int) round($item->get_total() * 100),
32 ];
33 }, $order->get_items()),
34 ],
35 'send' => [
36 'subject' => 'Ihre Rechnung — Bestellung #' . $order->get_id(),
37 'body' => "Hallo {client.name},\n\nanbei Ihre Rechnung {invoice.number}.\n\n— Acme Shop",
38 ],
39 'metadata' => [
40 'shop_order_id' => (string) $order->get_id(),
41 ],
42 ],
43]);
#Node.js / TypeScript
1import { randomUUID } from 'node:crypto';
2
3const response = await fetch('https://app.vorgio.example/api/v1/checkouts', {
4 method: 'POST',
5 headers: {
6 'Authorization': `Bearer ${process.env.VORGIO_TOKEN}`,
7 'Content-Type': 'application/json',
8 'Idempotency-Key': `order-${order.id}-checkout`,
9 },
10 body: JSON.stringify({
11 client: { /* … */ },
12 invoice: {
13 tax_rate: 19,
14 due_offset_days: 14,
15 positions: order.lineItems.map(item => ({
16 id: randomUUID(),
17 date: new Date().toISOString().slice(0, 10),
18 mode: 'fixed',
19 description: `${item.quantity}× ${item.name}`,
20 amount_cents: Math.round(item.totalCents),
21 })),
22 },
23 send: { subject: 'Your invoice', body: 'Hi {client.name}, …' },
24 metadata: { shop_order_id: String(order.id) },
25 }),
26});
27
28if (!response.ok) {
29 const err = await response.json();
30 throw new Error(`Vorgio ${response.status}: ${err.title} — ${err.detail}`);
31}
#Python
1import os, requests, uuid, datetime as dt
2
3resp = requests.post(
4 "https://app.vorgio.example/api/v1/checkouts",
5 headers={
6 "Authorization": f"Bearer {os.environ['VORGIO_TOKEN']}",
7 "Idempotency-Key": f"order-{order.id}-checkout",
8 },
9 json={
10 "client": { ... },
11 "invoice": {
12 "tax_rate": 19.0,
13 "due_offset_days": 14,
14 "positions": [
15 {
16 "id": str(uuid.uuid4()),
17 "date": dt.date.today().isoformat(),
18 "mode": "fixed",
19 "description": f"{item.qty}× {item.name}",
20 "amount_cents": int(round(item.total_cents)),
21 }
22 for item in order.line_items
23 ],
24 },
25 "send": {"subject": "Your invoice", "body": "Hi {client.name}, …"},
26 "metadata": {"shop_order_id": str(order.id)},
27 },
28 timeout=15,
29)
30resp.raise_for_status()
#Common gotchas
- Always supply
client.external_id. Without it, every call creates a brand-new Vorgio client even if the same person ordered yesterday — your client list will balloon. See Clients & external_id. - Generate a fresh UUID for each
position.id. They don't have to be UUIDv7 / sortable —uuid4()is fine. They're stored on the invoice and used by the UI for editing. - Don't put cents amounts as floats.
49.90 * 100 = 4989.999999999999in IEEE 754. Alwaysint(round(value * 100))(Python) or(int) round($value * 100)(PHP). send.bodyis plain text, not HTML. The mail template wraps it. If you need formatting, use blank lines for paragraphs.- Idempotency keys are scoped per-team and live for 24h. Reusing the same key in the same team within 24h after the original request will replay the response, even after the original side-effects are complete. Pick keys that are stable per logical checkout (an order ID is perfect) and don't recycle them.
- Recurring invoices are not supported on
/v1/checkouts. This endpoint is for one-off shop checkouts. For recurring billing usePOST /v1/invoicesdirectly withevery: monthlyetc. — see the /api-reference.