Vorgio

Clients & external_id

Each Vorgio team has its own list of clients (customers). When your shop's customer makes their first checkout, you create a Vorgio client. On their second checkout you want to re-use the same client, not duplicate it. The external_id field is the bridge.

#How find-or-create works

When you POST /v1/checkouts with client.external_id set, Vorgio:

  1. Looks up an existing client in your team with the same external_id.
  2. If found → updates that client with the fields you supplied (so a name change in your shop propagates) and uses it for the new invoice.
  3. If not found → creates a new client.

The lookup index is (team_id, external_id) — unique per team. This means:

  • A client with external_id = "wc_customer_42" in your team is completely independent of a client with the same external_id in someone else's team.
  • Within your team, two distinct customers must have distinct external_ids.

#What to use as external_id

The shop's own customer ID, prefixed with the platform name to avoid collision if you ever integrate multiple shops with the same Vorgio team:

Source Example external_id
WooCommerce customer ID wc_customer_42
Shopify customer ID shopify_cust_5283
Custom shop, integer ID acme_user_42
Custom shop, UUID acme_user_018f8b3a-…

Max length is 255 characters. Plain ASCII recommended.

#What if the customer is a guest checkout?

If your shop allows guest checkout (no persistent customer record), use a stable identifier you do have — typically the email address with a prefix:

 1external_id = "guest_email_" + sha256(email.lower())[:32]

This deduplicates by email so a returning guest gets the same Vorgio client. If you want each guest checkout to be its own client (no dedup), use the order ID instead: external_id = "guest_order_1234".

#Cross-tenant isolation

external_id collisions across teams are allowed. If two different Vorgio teams (different merchants) both use external_id = "customer_1" for completely unrelated customers, that's fine — the unique constraint is per team. There is no global namespace for external_id.

This means: never assume external_id is unique to your shop. It's unique within your team.

#Updates

When you supply external_id and the client already exists, Vorgio overwrites all the supplied client fields. If you want to keep an existing field unchanged, supply its current value (re-send the same data).

v1 behaviour: all client fields you marked required in the API reference are always required, even on the second-and-later call when the client already exists. We didn't go with partial-update semantics for v1 because shops generally have all the fields anyway, and "always send everything" is much simpler to reason about.

#Looking up a client by your external_id

Use GET /v1/clients?external_id=<value> (the list endpoint accepts a filter). Returns the matching client or an empty list.

For most shops you don't need this — the POST /v1/checkouts response includes the resolved client_id directly.

#When not to use external_id

If your shop is a one-shot quote/proposal tool that issues a Vorgio invoice once and never again per customer, you can omit external_id. Vorgio will create a fresh client per call. Just be aware that the merchant's Vorgio client list grows by one row per checkout — fine if checkouts are infrequent, ugly if they aren't.

#Soft-delete behaviour

If the merchant soft-deletes a client in the Vorgio UI, a subsequent POST /v1/checkouts with the same external_id will... currently create a new client, not resurrect the deleted one. The deleted row keeps its external_id (the unique constraint is on the live row).

This is by design — soft-deleted clients are typically deleted because the merchant wants them gone. Resurrecting on the next webhook would surprise them.

If you have a strong use case for resurrection, open an issue.