Source: https://www.revvly.ai/docs/api/external-references API Reference # Reference resources by *your own* ids. Identify subscriptions and variables with references you already own — or discover Revvly’s ids on demand — so your integration never has to store an internal Mongo id. ## Give this prompt to an integration agent Use this context when an agent needs to connect your own account ids to Revvly metering. ``` You are implementing Revvly usage reporting without storing Revvly ids. At subscription provisioning, set externalId to your own stable account or subscription id via the public createSubscription mutation (WRITE-capable API key) — the internal dashboard GraphQL provisioning flow (createSubscriptionWithPricing) is only needed for migrated or otherwise advanced subscriptions. For later usage, send externalSubscriptionId with a variableSlug; never send both the external and internal identifier for either the subscription or meter. Discover meter slugs through GET https://api.revvly.ai/api/v1/variables and use GET https://api.revvly.ai/api/v1/subscriptions only when you need to sync or inspect ids. Discovery requests use Bearer auth but no HMAC. For POST https://api.revvly.ai/api/v1/events, unresolved references are per-event REJECTED results inside HTTP 202. For https://api.revvly.ai/api/v1/usage mutations, unresolved or invalid reference pairs are normal HTTP errors. Use the event or usage API's required idempotency mechanism; never put API secrets in browser code. ``` ## The recommended flow: reference by your own id Set externalId on the subscription when you create it — use your own account or subscription identifier. It is unique per tenant. From then on, report usage with externalSubscriptionId and identify the metric with variableSlug. You never read or store a Revvly id. i externalId is unique per tenant. Setting it at creation gives you a stable handle for every later usage call — no lookup, no mapping table. ### 1. Create the subscription with your id Pass externalId on the public createSubscription mutation — the same WRITE-capable API key you use for usage reporting can provision the subscription directly, right after creating its client with createClient. The dashboard’s subscription wizard (createSubscriptionWithPricing, on the internal JWT-authed API) remains for migrations and other advanced authoring the public mutation deliberately leaves out — see [the public GraphQL reference](https://www.revvly.ai/docs/api/graphql-public#create-subscription) for what that excludes. You can change externalId later via an update mutation, but the previous value is not kept as an alias — update every sender that reports externalSubscriptionId to the new value before you replace it, or usage against the old id will stop resolving. GraphQL ``` # POST https://api.revvly.ai/api/v1/graphql — public GraphQL, WRITE capability required. mutation CreateSubscription($input: CreateSubscriptionInput!) { createSubscription(input: $input) { id externalId } } { "input": { "clientExternalId": "acct_123", "bundleId": "663b1f2e4a3c2d1e0f8b7a55", "period": "MONTHLY", "startDate": "2026-06-01T00:00:00.000Z", "externalId": "acct_123" } } ``` ### 2. Report usage with your id Now every event references acct_123 and the meter slug api-calls — no Revvly id anywhere. Supply exactly one of subscriptionId / externalSubscriptionId and exactly one of variableId / variableSlug. POST https://api.revvly.ai/api/v1/events ``` POST https://api.revvly.ai/api/v1/events Authorization: Bearer rvly_sk_live_ Content-Type: application/json X-Signature-SHA256: sha256= { "events": [ { "eventId": "01HYZ7K2N8V3WXPQ4JCBM5FGTE", "externalSubscriptionId": "acct_123", "variableSlug": "api-calls", "type": "USAGE_REPORTED", "quantity": 1500, "reportedAt": "2026-06-14T12:00:00Z" } ] } ``` i An externalSubscriptionId or variableSlug that doesn’t resolve to a resource in the API key’s scope yields a per-event REJECTED result on the events batch (and a 404 / 400 on the single-item usage endpoints). See the [Event Ingestion API](https://www.revvly.ai/docs/api/events) for the full payload and signing details. ## Alternative: sync and store Revvly ids If you prefer to keep Revvly’s ids in your own database, read them once and cache them. Use GET https://api.revvly.ai/api/v1/subscriptions to list subscriptions and GET https://api.revvly.ai/api/v1/variables to map your metrics. These are GET requests — Bearer-authenticated but **not** HMAC-signed — and the results are filtered to the API key’s scope. ### List subscriptions Keyset pagination: follow nextCursor until it is absent. limit defaults to 100 and caps at 1 000. ``` GET https://api.revvly.ai/api/v1/subscriptions?status=ACTIVE&limit=100 Authorization: Bearer rvly_sk_live_ { "data": [ { "id": "663b1f2e4a3c2d1e0f8b7a9c", "externalId": "acct_123", "organizationId": "663b1f2e4a3c2d1e0f8b7a01", "status": "ACTIVE", "period": "MONTHLY", "currency": "USD", "startDate": "2026-04-23T00:00:00Z", "endDate": null, "autoRenew": true, "variableComponentIds": ["663b1f2e4a3c2d1e0f8b7b01"], "metadata": { "tier": "pro" } } ], "nextCursor": "eyJpZCI6IjY2M2IxZjJl..." } ``` ### List variables This is how you discover a variableSlug (or the internal variableId) to send on usage events. Pass includeInactive=true to also return deprecated variables. ``` GET https://api.revvly.ai/api/v1/variables Authorization: Bearer rvly_sk_live_ { "data": [ { "id": "663b1f2e4a3c2d1e0f8b7b01", "slug": "api-calls", "displayName": "API calls", "variableType": "api-call", "unitLabel": "call", "isActive": true }, { "id": "663b1f2e4a3c2d1e0f8b7b02", "slug": "seats", "displayName": "User seats", "variableType": "seat", "unitLabel": "seat", "isActive": true } ] } ``` ### List regions Regions carry the currencies a client can be billed in, and pin the currency of the subscriptions you report usage against. Only active regions are returned by default; pass includeInactive=true to also return archived ones. ``` GET https://api.revvly.ai/api/v1/regions Authorization: Bearer rvly_sk_live_ { "data": [ { "id": "663b1f2e4a3c2d1e0f8b7a55", "name": "United States", "code": "US", "description": null, "defaultCurrency": "USD", "supportedCurrencies": ["USD"], "isActive": true } ] } ``` ## Discovery endpoints All are read-only GETs under the same rvly_sk_live_* Bearer auth as the ingestion API. They are not HMAC-signed. Subscription and variable responses are filtered to the API key’s scope; regions are scoped to your tenant. ### [#](#get-subscriptions)List subscriptions GET https://api.revvly.ai/api/v1/subscriptions { data: [...], nextCursor } - **Query params**: organizationId, externalId, status, cursor, limit — all optional. Keyset pagination via cursor / nextCursor; limit defaults to 100, caps at 1 000. - **Response**: data[] of subscription summaries — id, externalId, organizationId, status, period, currency, startDate, endDate, autoRenew, variableComponentIds, metadata — plus nextCursor. ### [#](#get-subscription)Get subscription by id GET https://api.revvly.ai/api/v1/subscriptions/:id one summary - **Path param**: id — the internal Revvly subscription id. - **Response**: A single subscription summary (same shape as a data[] item above). ### [#](#get-subscription-by-external)Get subscription by external id GET https://api.revvly.ai/api/v1/subscriptions/by-external/:externalId one summary - **Path param**: externalId — the reference you set at creation. Resolves the same single subscription summary by your own id. - **Response**: A single subscription summary, or 404 if no subscription in scope carries that externalId. ### [#](#get-variables)List variables GET https://api.revvly.ai/api/v1/variables { data: [...] } - **Query param**: includeInactive — optional; set to true to also return deprecated meters. - **Response**: data[] of meter summaries — id, slug, displayName, variableType, unitLabel, isActive. This is the source for the variableSlug you send on usage events. ### [#](#get-regions)List regions GET https://api.revvly.ai/api/v1/regions { data: [...] } - **Query param**: includeInactive — optional; set to true to also return archived regions. - **Response**: data[] of region summaries — id, name, code, description, defaultCurrency, supportedCurrencies, isActive. The id is a client’s regionId. ## Related - [Event Ingestion API ›](https://www.revvly.ai/docs/api/events) - [Public GraphQL API ›](https://www.revvly.ai/docs/api/graphql-public) - [The Subscription concept ›](https://www.revvly.ai/docs/concepts/subscription)