Vorgio

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 Vorgio invoice_id in your shop's order record at checkout time (recommended), or (b) iterate GET /v1/invoices and filter client-side.
  • Not for retry coordination. Use the Idempotency-Key header for that.
  • Not editable once finalised. PATCH /v1/invoices/{id} can change metadata on a draft, an offer or a recurring template. It replaces the whole object, so a body without metadata clears it. On a finalised invoice it returns 422 invoice-not-editable. The invoice a checkout issues is finalised, so set metadata at 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).