***

title: Two Invoice IDs
subtitle: Why Gwop invoices have both a merchant ID and a public invoice ID
slug: concepts/two-invoice-ids
------------------------------

Every Gwop invoice has two identifiers because two different parties need to use it for two different jobs.

## The two IDs

| Field             | Format  | Used by            |
| ----------------- | ------- | ------------------ |
| `id`              | UUID    | Your backend       |
| `publicInvoiceId` | `inv_*` | The payer or agent |

Your backend uses `id` for merchant-side concerns like internal references, reconciliation, and canceling an invoice. The payer-facing side uses `publicInvoiceId` to fetch the public invoice view, discover payment methods, and track settlement.

## Why this split exists

The merchant record and the payer-facing checkout are not the same thing.

* the merchant record belongs in your internal model
* the public invoice ID is safe to hand to an agent
* separating them lets your backend keep private state and permissions separate from the public payment flow

The practical rule is simple: store both, but only hand `publicInvoiceId` to the payer.

## What to do in your app

When you create an invoice:

1. store `id` on your internal checkout or order record
2. store `publicInvoiceId` alongside it
3. return `publicInvoiceId` and `agentProtocol` to the agent
4. use both IDs later when correlating public invoice status and webhook events back to your local state

## Related pages

<CardGroup cols={2}>
  <Card title="Create an Invoice" icon="duotone file-invoice-dollar" href="/invoices/create">
    See where both IDs first appear in the create response
  </Card>

  <Card title="Subscription Checkout" icon="duotone cart-shopping" href="/integration-patterns/subscription-checkout">
    See how to carry both IDs through your backend model
  </Card>
</CardGroup>