Metadata
Every POST /v1/checkouts accepts an optional metadata object. Vorgio stores it on the invoice (in the invoices.metadata JSON column), echoes it on every webhook payload, and returns it on GET /v1/invoices/{id}. It's the recommended way to correlate Vorgio events back to your shop's records.
#Schema
- Free-form JSON object (not array, not scalar).
- Top-level keys must be strings.
- Values can be any JSON-encodable type.
- ≤ 16 KB serialized.
1"metadata": {
2 "shop_order_id": "1234",
3 "channel": "web",
4 "customer_segment": "returning",
5 "tags": ["bday-promo"]
6}
#The canonical pattern: shop order ID
The single most useful key is the shop's own order ID, as a string:
1"metadata": {
2 "shop_order_id": "1234"
3}
When the invoice.paid webhook arrives later, your handler does:
1$shopOrderId = $event['metadata']['shop_order_id'] ?? null;
2if (! $shopOrderId) {
3 Log::warning('Vorgio webhook missing shop_order_id', ['event' => $event['id']]);
4 return response('', 200); // ack so Vorgio doesn't retry
5}
6$order = Order::find($shopOrderId);
7$order->markPaid();
Always string-encode IDs even if your shop uses integers — JSON doesn't distinguish 1234 from "1234" after a round-trip through some intermediate systems, but PHP/JS/Python === does.
#Multi-key patterns
For shops that need richer correlation:
1"metadata": {
2 "shop": "wc",
3 "order_id": "1234",
4 "checkout_id": "abc-…",
5 "promo_codes": ["SUMMER10"],
6 "fulfillment_method": "shipping"
7}
These are passed straight through. Vorgio doesn't interpret any of them.
#What metadata is not for
- Not for sensitive data. Stored in plaintext in the Vorgio DB, visible to anyone with access to the merchant's team. Don't put PII you wouldn't put on the invoice itself.
- Not for query filters. You can't
GET /v1/invoices?metadata.shop_order_id=1234— metadata isn't queryable. If you need to look up an invoice by your shop order ID, you have two options: (a) store the Vorgioinvoice_idin your shop's order record at checkout time (recommended), or (b) iterateGET /v1/invoicesand filter client-side. - Not for retry coordination. Use the
Idempotency-Keyheader for that. - Not editable once finalised.
PATCH /v1/invoices/{id}can changemetadataon a draft, an offer or a recurring template. It replaces the whole object, so a body withoutmetadataclears it. On a finalised invoice it returns422 invoice-not-editable. The invoice a checkout issues is finalised, so setmetadataat checkout time.
#Worked example: WooCommerce
1$payload = [
2 // … client, invoice, send …
3 'metadata' => [
4 'shop_order_id' => (string) $order->get_id(),
5 'shop_order_key' => $order->get_order_key(), // for /my-account/view-order/<id>?key=…
6 'shop_admin_url' => admin_url('post.php?post=' . $order->get_id() . '&action=edit'),
7 ],
8];
The shop_admin_url is convenient — when the merchant looks at the invoice in Vorgio, they can click straight through to the matching WC order in their WP admin (the Vorgio WP plugin renders a link from metadata.shop_admin_url if present).