Skip to main content
API docs by Redocly

Payments API (1.0)

Download OpenAPI specification:Download

API for billing, subscriptions, metering, and webhook handling

Webhooks

Stripe, CMS, and FXA webhook handlers

Handle CMS content validation webhook

header Parameters
authorization
required
string
authorization
required
string

Webhook authorization token

Responses

Handle FXA account event webhook

header Parameters
authorization
required
string
authorization
required
string

JWT authorization token for FXA events

Responses

Handle Stripe webhook events

header Parameters
stripe-signature
required
string
stripe-signature
required
string

Stripe webhook signature for payload verification

Responses

Health Checks

Load balancer heartbeat

Responses

Service heartbeat

Responses

Version information

Responses

Billing & Subscriptions

Get billing info and subscriptions for the authenticated user

Returns the payment method on file (card or PayPal) and all active subscriptions (Stripe web, Google Play IAP, Apple App Store IAP) for the authenticated user. Requires a valid FxA OAuth access token with appropriate scopes.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
{
  • "billing_name": "string",
  • "exp_month": 0,
  • "exp_year": 0,
  • "last4": "string",
  • "payment_provider": "string",
  • "payment_type": "string",
  • "paypal_payment_error": "string",
  • "brand": "string",
  • "subscriptions": [
    ]
}

Metering

Ingest a usage event

Records a usage event for a metered product. Events are deduplicated by the id field — retries with the same id will not double-count within the retention window. Requires a valid metering service credential.

Authorizations:
bearer
Request Body schema: application/json
required
id
required
string [ 1 .. 256 ] characters

Stable idempotency key for this usage event; retries with the same id will not double-count

userIdentifier
required
string [ 1 .. 256 ] characters

Unique identifier for the user being metered

slug
required
string [ 1 .. 128 ] characters ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$

Meter slug identifier (lowercase alphanumeric, hyphens, underscores)

amount
required
number > 0

Usage amount to record (must be positive)

timestamp
string <date-time> ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[...

ISO 8601 timestamp with offset; defaults to server time if omitted

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "userIdentifier": "string",
  • "slug": "string",
  • "amount": 0,
  • "timestamp": "2019-08-24T14:15:22Z"
}

Query usage data for a user and meter

Returns the current usage, limit, and metering window for a specific user and meter slug. Requires a valid metering service credential.

Authorizations:
bearer
path Parameters
userIdentifier
required
string

Unique identifier for the user being queried

slug
required
string

Meter slug identifier to query usage for

Responses

Response samples

Content type
application/json
{
  • "usage": 0,
  • "limit": 0,
  • "grantedAmount": 0,
  • "unit": "string",
  • "windowStart": "2019-08-24T14:15:22Z",
  • "windowEnd": "2019-08-24T14:15:22Z"
}

Grant additional usage to a user

Grants additional usage against a meter for a user, raising the effective limit reported by usage queries. Requires a valid metering service credential.

Authorizations:
bearer
Request Body schema: application/json
required
userIdentifier
required
string [ 1 .. 256 ] characters

User identifier the grant applies to

slug
required
string [ 1 .. 128 ] characters ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$

Meter slug the grant applies to

amount
required
number > 0

Additional usage to grant on top of the meter limit (must be a positive, finite number)

reason
string [ 1 .. 1024 ] characters

Optional human-readable note recorded for audit

required
object or object or object
Default: {"type":"unending"}

When the grant stops applying: unending, the end of the meter’s current window, or an explicit expiry

Responses

Request samples

Content type
application/json
{
  • "userIdentifier": "string",
  • "slug": "string",
  • "amount": 0,
  • "reason": "string",
  • "lifetime": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "userIdentifier": "string",
  • "slug": "string",
  • "amount": 0,
  • "grantedBy": "string",
  • "reason": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "active": true
}

List a user’s usage grants

Returns all usage grants for a user, optionally filtered by meter slug. Each grant includes an active flag reflecting whether it currently applies. Requires a valid metering service credential. Metering clients are mutually trusted: any authenticated client may read grants created by any other client.

Authorizations:
bearer
path Parameters
userIdentifier
required
string

Unique identifier for the user whose grants are listed

query Parameters
slug
any

Optional meter slug to filter the grants by

Responses

Response samples

Content type
application/json
{
  • "grants": [
    ]
}

Delete a usage grant

Deletes a single usage grant by its identifier. Requires a valid metering service credential. Metering clients are mutually trusted: any authenticated client may delete a grant created by any other client.

Authorizations:
bearer
path Parameters
grantId
required
string

Identifier of the grant to delete

Responses