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:
- Looks up an existing client in your team with the same
external_id. - 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.
- 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 sameexternal_idin 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.