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.
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 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.
# 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
Authorization: Bearer rvly_sk_live_<your-token>
Content-Type: application/json
X-Signature-SHA256: sha256=<hmac-hex>
{
"events": [
{
"eventId": "01HYZ7K2N8V3WXPQ4JCBM5FGTE",
"externalSubscriptionId": "acct_123",
"variableSlug": "api-calls",
"type": "USAGE_REPORTED",
"quantity": 1500,
"reportedAt": "2026-06-14T12:00:00Z"
}
]
}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_<your-token>
{
"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_<your-token>
{
"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_<your-token>
{
"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.