openapi: 3.0.0 paths: /__lbheartbeat__: get: operationId: AppController___lbheartbeat__ parameters: [] responses: '200': description: Service is reachable summary: Load balancer heartbeat tags: - Health Checks /__heartbeat__: get: operationId: AppController___heartbeat__ parameters: [] responses: '200': description: Service is healthy summary: Service heartbeat tags: - Health Checks /__version__: get: operationId: AppController___version__ parameters: [] responses: '200': description: Returns version info summary: Version information tags: - Health Checks /v1/billing-and-subscriptions: get: description: >- 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. operationId: BillingAndSubscriptionsController_getBillingAndSubscriptions parameters: [] responses: '200': description: Billing details and active subscriptions content: application/json: schema: type: object properties: billing_name: description: >- Name on the payment method, or null/absent if not available anyOf: - type: string - type: 'null' exp_month: description: Card expiration month (1-12) type: number exp_year: description: Card expiration year (e.g. 2026) type: number last4: description: Last four digits of the card number type: string payment_provider: description: Payment provider (e.g. "stripe", "paypal") type: string payment_type: description: Payment method type (e.g. "credit", "debit") type: string paypal_payment_error: description: PayPal billing agreement error, if any type: string brand: description: Card brand (e.g. "visa", "mastercard") type: string subscriptions: type: array items: oneOf: - type: object properties: _subscription_type: type: string const: web description: Discriminator for Stripe web subscriptions created: type: number description: Unix timestamp when the subscription was created current_period_end: type: number description: >- Unix timestamp when the current billing period ends current_period_start: type: number description: >- Unix timestamp when the current billing period started cancel_at_period_end: type: boolean description: >- Whether the subscription will cancel at the end of the current period end_at: anyOf: - type: number - type: 'null' description: >- Unix timestamp when the subscription ended, or null if still active plan_id: type: string description: Stripe price/plan identifier product_id: type: string description: Stripe product identifier priceInfo: type: object properties: amount: anyOf: - type: number - type: 'null' description: >- Price amount in minor units (e.g. cents), or null if free currency: anyOf: - type: string - type: 'null' description: >- ISO 4217 currency code (e.g. "usd"), or null if free interval: type: string description: Billing interval unit (e.g. "month", "year") interval_count: type: number description: Number of intervals between billings required: - amount - currency - interval - interval_count additionalProperties: false status: type: string description: >- Stripe subscription status (e.g. "active", "canceled", "past_due") subscription_id: type: string description: Stripe subscription identifier required: - _subscription_type - created - current_period_end - current_period_start - cancel_at_period_end - end_at - plan_id - product_id - priceInfo - status - subscription_id additionalProperties: false - type: object properties: _subscription_type: type: string const: iap_google description: Discriminator for Google Play IAP subscriptions auto_renewing: type: boolean description: Whether the subscription is set to auto-renew cancel_reason: description: Google Play cancel reason code, if canceled type: number expiry_time_millis: type: number description: Expiration time in milliseconds since epoch package_name: type: string description: Android app package name sku: type: string description: Google Play SKU identifier price_id: type: string description: Internal price identifier product_id: type: string description: Internal product identifier product_name: type: string description: Human-readable product name priceInfo: type: object properties: amount: anyOf: - type: number - type: 'null' description: >- Price amount in minor units (e.g. cents), or null if free currency: anyOf: - type: string - type: 'null' description: >- ISO 4217 currency code (e.g. "usd"), or null if free interval: type: string description: Billing interval unit (e.g. "month", "year") interval_count: type: number description: Number of intervals between billings required: - amount - currency - interval - interval_count additionalProperties: false required: - _subscription_type - auto_renewing - expiry_time_millis - package_name - sku - price_id - product_id - product_name - priceInfo additionalProperties: false - type: object properties: _subscription_type: type: string const: iap_apple description: >- Discriminator for Apple App Store IAP subscriptions app_store_product_id: type: string description: Apple App Store product identifier auto_renewing: type: boolean description: Whether the subscription is set to auto-renew bundle_id: type: string description: iOS app bundle identifier expiry_time_millis: description: Expiration time in milliseconds since epoch type: number is_in_billing_retry_period: description: >- Whether Apple is retrying a failed billing attempt type: boolean price_id: type: string description: Internal price identifier product_id: type: string description: Internal product identifier product_name: type: string description: Human-readable product name priceInfo: type: object properties: amount: anyOf: - type: number - type: 'null' description: >- Price amount in minor units (e.g. cents), or null if free currency: anyOf: - type: string - type: 'null' description: >- ISO 4217 currency code (e.g. "usd"), or null if free interval: type: string description: Billing interval unit (e.g. "month", "year") interval_count: type: number description: Number of intervals between billings required: - amount - currency - interval - interval_count additionalProperties: false required: - _subscription_type - app_store_product_id - auto_renewing - bundle_id - price_id - product_id - product_name - priceInfo additionalProperties: false - type: object properties: _subscription_type: type: string const: free_access current_period_end: type: number description: >- Unix timestamp when the current billing period ends product_id: type: string required: - _subscription_type - current_period_end - product_id additionalProperties: false description: >- All active subscriptions across web, Google IAP, and Apple IAP required: - subscriptions additionalProperties: false '401': description: Unauthorized — missing, expired, or invalid OAuth access token security: - bearer: [] summary: Get billing info and subscriptions for the authenticated user tags: - Billing & Subscriptions /webhooks/strapi/validation: post: operationId: CmsWebhooksController_postStrapiValidation parameters: - name: authorization required: true in: header schema: type: string - name: authorization in: header description: Webhook authorization token required: true schema: type: string responses: '200': description: '' tags: - Webhooks summary: Handle CMS content validation webhook /webhooks/strapi/free-access-program/access: post: operationId: FreeAccessProgramWebhooksController_postAccess parameters: - name: authorization required: true in: header schema: type: string - name: authorization in: header description: Webhook authorization token required: true schema: type: string responses: '200': description: '' tags: - Webhooks summary: >- Refresh the Free Access Program projection cache on a Strapi access change /webhooks/fxa: post: operationId: FxaWebhooksController_postFxaEvent parameters: - name: authorization required: true in: header schema: type: string - name: authorization in: header description: JWT authorization token for FXA events required: true schema: type: string responses: '200': description: '' tags: - Webhooks summary: Handle FXA account event webhook /webhooks/stripe: post: operationId: StripeWebhooksController_postStripe parameters: - name: stripe-signature required: true in: header schema: type: string - name: stripe-signature in: header description: Stripe webhook signature for payload verification required: true schema: type: string responses: '200': description: '' tags: - Webhooks summary: Handle Stripe webhook events /v1/metering/usage: post: description: >- 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. operationId: UsageController_ingest parameters: [] requestBody: required: true content: application/json: schema: type: object properties: id: type: string minLength: 1 maxLength: 256 description: >- Stable idempotency key for this usage event; retries with the same id will not double-count subject: type: string minLength: 1 maxLength: 256 description: >- Subject the usage is attributed to: a user id, device id, or any other key the relying party meters by slug: type: string minLength: 1 maxLength: 128 pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$ description: >- Meter slug identifier (lowercase alphanumeric, hyphens, underscores) amount: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 description: Usage amount to record (must be a positive integer) timestamp: description: >- ISO 8601 timestamp with offset; defaults to server time if omitted type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ required: - id - subject - slug - amount additionalProperties: false responses: '202': description: Usage event accepted for processing '400': description: >- Invalid request body — one or more fields failed validation, or the timestamp is outside the accepted range '401': description: Missing, malformed, or unrecognized bearer token '404': description: The meter slug is not configured '500': description: Unexpected error '503': description: >- The event could not be published — retry with the same id, which is safe security: - bearer: [] summary: Ingest a usage event tags: - Metering /v1/metering/usage/{subject}/{slug}: get: description: >- Returns the current usage, limit, and metering window for a specific subject and meter slug. Requires a valid metering service credential. operationId: UsageController_query parameters: - name: subject required: true in: path description: >- Subject to query usage for: a user id, device id, or any other key the relying party meters by schema: type: string - name: slug required: true in: path description: Meter slug identifier to query usage for schema: type: string responses: '200': description: Current usage data for the requested meter and subject content: application/json: schema: type: object properties: usage: type: number description: Current usage amount within the billing window limit: type: number description: >- Effective usage limit for the current plan, including any active grants grantedAmount: type: number description: >- Additional usage granted on top of the plan limit within the current window unit: type: string description: Unit of measurement (e.g. "requests", "gb") windowStart: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ description: ISO 8601 start of the current metering window windowEnd: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ description: ISO 8601 end of the current metering window required: - usage - limit - grantedAmount - unit - windowStart - windowEnd additionalProperties: false '400': description: Invalid parameters — subject or slug failed validation '401': description: Missing, malformed, or unrecognized bearer token '404': description: The meter slug is not configured '500': description: Unexpected error '503': description: Usage data is temporarily unavailable — retry with backoff security: - bearer: [] summary: Query usage data for a subject and meter tags: - Metering /v1/metering/usage-grants: post: description: >- Grants additional usage against a meter for a subject, raising the effective limit reported by usage queries. Requires a valid metering service credential. operationId: UsageGrantsController_create parameters: [] requestBody: required: true content: application/json: schema: type: object properties: subject: type: string minLength: 1 maxLength: 256 description: Subject the grant applies to slug: type: string minLength: 1 maxLength: 128 pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$ description: Meter slug the grant applies to amount: type: number exclusiveMinimum: 0 description: >- Additional usage to grant on top of the meter limit (must be a positive, finite number) reason: description: Optional human-readable note recorded for audit type: string minLength: 1 maxLength: 1024 lifetime: default: type: unending oneOf: - type: object properties: type: type: string const: unending required: - type additionalProperties: false - type: object properties: type: type: string const: currentWindow required: - type additionalProperties: false - type: object properties: type: type: string const: expires expiresAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ description: >- ISO 8601 timestamp with offset at which the grant expires required: - type - expiresAt additionalProperties: false description: >- When the grant stops applying: unending, the end of the meter’s current window, or an explicit expiry required: - subject - slug - amount - lifetime additionalProperties: false responses: '201': description: The created usage grant content: application/json: schema: type: object properties: id: type: string description: Unique identifier for the grant subject: type: string minLength: 1 maxLength: 256 description: Subject the grant was issued to slug: type: string minLength: 1 maxLength: 128 pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$ description: >- Meter slug identifier (lowercase alphanumeric, hyphens, underscores) amount: type: number description: Additional usage granted on top of the meter limit grantedBy: type: string description: Metering client identifier that created the grant reason: description: Human-readable note recorded for audit type: string createdAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ description: ISO 8601 time the grant was created expiresAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ - type: 'null' description: ISO 8601 expiry, or null when the grant never expires active: type: boolean description: >- Whether the grant currently applies at the time of the query required: - id - subject - slug - amount - grantedBy - createdAt - expiresAt - active additionalProperties: false '400': description: >- Invalid request body — one or more fields failed validation, or a currentWindow lifetime was requested on a non-calendar (sliding or session) meter '401': description: Missing, malformed, or unrecognized bearer token '404': description: The meter slug is not configured '500': description: Unexpected error security: - bearer: [] summary: Grant additional usage to a subject tags: - Metering /v1/metering/usage-grants/{subject}: get: description: >- Returns all usage grants for a subject, 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. operationId: UsageGrantsController_list parameters: - name: subject required: true in: path description: >- Subject whose grants are listed: a user id, device id, or any other key the relying party meters by schema: type: string - name: slug required: false in: query description: Optional meter slug to filter the grants by schema: {} responses: '200': description: The subject’s usage grants content: application/json: schema: type: object properties: grants: type: array items: type: object properties: id: type: string description: Unique identifier for the grant subject: type: string minLength: 1 maxLength: 256 description: Subject the grant was issued to slug: type: string minLength: 1 maxLength: 128 pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$ description: >- Meter slug identifier (lowercase alphanumeric, hyphens, underscores) amount: type: number description: Additional usage granted on top of the meter limit grantedBy: type: string description: Metering client identifier that created the grant reason: description: Human-readable note recorded for audit type: string createdAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ description: ISO 8601 time the grant was created expiresAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ - type: 'null' description: >- ISO 8601 expiry, or null when the grant never expires active: type: boolean description: >- Whether the grant currently applies at the time of the query required: - id - subject - slug - amount - grantedBy - createdAt - expiresAt - active additionalProperties: false description: Grants for the requested subject required: - grants additionalProperties: false '400': description: Invalid parameters — subject or slug failed validation '401': description: Missing, malformed, or unrecognized bearer token '500': description: Unexpected error security: - bearer: [] summary: List a subject’s usage grants tags: - Metering /v1/metering/usage-grants/{grantId}: delete: description: >- 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. operationId: UsageGrantsController_delete parameters: - name: grantId required: true in: path description: Identifier of the grant to delete schema: type: string responses: '204': description: The grant was deleted '400': description: Invalid parameters — grantId failed validation '401': description: Missing, malformed, or unrecognized bearer token '404': description: No grant exists with that id '500': description: Unexpected error security: - bearer: [] summary: Delete a usage grant tags: - Metering info: title: Payments API description: API for billing, subscriptions, metering, and webhook handling version: '1.0' contact: {} tags: - name: Webhooks description: Stripe, CMS, and FXA webhook handlers servers: [] components: securitySchemes: bearer: scheme: bearer bearerFormat: JWT type: http schemas: {}