Source: https://www.revvly.ai/docs/guides/external-id

Guide

# Reference everything by *your own* id.

Set externalId once at creation — on a client, on a subscription — and every call after that uses your own identifiers. No lookup table, no stored Revvly ids, nothing to keep in sync.

## Give this prompt to an integration agent

```
You are integrating external identifiers with Revvly usage reporting.
Set a client's externalId on createClient and a subscription's externalId on
createSubscription (both public GraphQL, both require the WRITE capability) to the
caller's stable account/subscription id — the dashboard's internal provisioning flow
is only needed for migrated or otherwise advanced subscriptions. Then report usage
using externalSubscriptionId and variableSlug, never both external and internal ids
for one resource. Discover available variable slugs with
GET https://api.revvly.ai/api/v1/variables.
POST https://api.revvly.ai/api/v1/events requires a stable eventId and raw-body HMAC;
duplicate events return DUPLICATE and invalid references are per-event REJECTED results.
REST usage mutations at https://api.revvly.ai/api/v1/usage* require an Idempotency-Key
and return regular HTTP errors for invalid references. Keep credentials server-side.
```

## Why bother

Every resource in Revvly has an internal id, but you already have your own — an account id, a subscription id in your billing system. Setting externalId once lets your integration speak in its own vocabulary from then on, instead of maintaining a lookup table that can drift out of sync with Revvly.

- [Subscription concept ›](https://www.revvly.ai/docs/concepts/subscription)

## Set it on a Client

Pass externalId on createClient (public GraphQL, requires the WRITE capability) — unique per tenant, up to 100 characters. From then on, query client(externalId: "...") instead of client(id: "...") to fetch that client plus its region, subscriptions, invoices, and paymentSummary.

- [Client concept ›](https://www.revvly.ai/docs/concepts/client)

## Set it on a Subscription

Pass externalId on createSubscription (public GraphQL, requires the WRITE capability) — unique per tenant, and editable later if your own identifier ever changes. The same API key you use for usage reporting below can provision the subscription and set its externalId in one call, right after creating the client. The dashboard's subscription wizard (createSubscriptionWithPricing, on the internal JWT-authed API) still exists for migrations and other advanced authoring the public mutation deliberately leaves out — historical backfill, billing schedules, discounts, legacy catalog-version pins.

- [Subscription concept ›](https://www.revvly.ai/docs/concepts/subscription)

## Report usage without ever reading a Revvly id

Usage events accept externalSubscriptionId in place of subscriptionId, and variableSlug in place of variableId — supply exactly one of each pair. Combined with the externalId you set at creation, a usage-reporting integration never has to store a single Revvly-issued id.

- [Subscription Variable Usage concept ›](https://www.revvly.ai/docs/concepts/subscriptionUsage)

## What happens when a reference does not resolve

On the single-item usage endpoints (POST https://api.revvly.ai/api/v1/usage and friends), a bad reference is a normal HTTP error: 404 if the external id or slug does not resolve, 400 if you supply both or neither of a pair, 403 if it resolves but sits outside your key's scope. On the batch event-ingestion endpoint (POST https://api.revvly.ai/api/v1/events) the same failures do not fail the call — each bad event comes back as a per-event REJECTED result inside a 202 response, so one bad reference never blocks the rest. POST https://api.revvly.ai/api/v1/usage/batch is a batch too, but reports per-item outcomes as numeric HTTP-style status codes (200, 400, 404, …) rather than the REJECTED string.

## Prefer to sync Revvly's ids instead

If you would rather cache ids in your own database, GET https://api.revvly.ai/api/v1/subscriptions and GET https://api.revvly.ai/api/v1/variables are Bearer-authenticated discovery endpoints — not HMAC-signed — filtered to your key's scope, with keyset pagination via cursor / nextCursor. GET https://api.revvly.ai/api/v1/subscriptions/by-external/:externalId resolves the same summary by the id you set in step 3, for a one-off lookup instead of a full sync.

A worked example

### Loopline never stores a *Revvly id*.

One account id, set once, carries the whole integration — creation, usage reporting, a typo that fails safely, and two different lookups later.

1. 01Your own account idLoopline, your SaaS, already tracks customers by acct_4471 in its own database. Nothing about Revvly needs to enter that system.
2. 02Create the subscriptionRight after creating the client, the same backend calls createSubscription (public GraphQL) with clientExternalId: 'acct_4471', bundleId, and externalId: 'acct_4471'. Revvly hands back its own id, but your metering integration never has to store it.
3. 03Usage happensA user on that account makes 1,500 API calls. Your metering job reports it with externalSubscriptionId: 'acct_4471' and variableSlug: 'api-calls' — the same two strings you already had.
4. 04A typo in one eventOne event in the batch carries variableSlug: 'api-call' (singular, a typo). It comes back REJECTED in the batch response; the other 1,499 events post normally, and you fix the slug on the next run.
5. 05Support looks it upSomeone needs to check the account's Revvly status without touching your database. GET https://api.revvly.ai/api/v1/subscriptions/by-external/acct_4471 resolves the subscription directly from the id everyone already has memorized.
6. 06The client side, tooThe billing contact for that account is queried the same way — no Revvly id needed: client(externalId: "acct_4471") returns the client, its region, invoices, and outstanding balance in one call.

## Related

- [External References & ID Discovery — full API reference ›](https://www.revvly.ai/docs/api/external-references)
- [Public GraphQL API ›](https://www.revvly.ai/docs/api/graphql-public)
- [The Subscription concept ›](https://www.revvly.ai/docs/concepts/subscription)
- [The Client concept ›](https://www.revvly.ai/docs/concepts/client)