Payment gate a subscription

This page describes how to require payment before granting access to a subscription or its recurring credits. Payment gating lets Metronome track the paid subscription quantity, release attached credits according to payment status, and notify your application when the entitlement state changes.

Private previewThis page documents a private preview. Contact your Metronome representative to confirm access before using these provisional fields and endpoints. The API can change during the preview.

Use payment gating to reduce fraud risk and ensure that you collect payment before granting customers access to your products or credits. This is especially important for AI companies, where unpaid usage can incur substantial compute costs. For example, if you sell a $10 monthly subscription that includes 100 AI credits, payment gating lets you easily withhold credit access until the initial payment succeeds and after each corresponding renewal invoice is paid.

How payment-gated subscriptions work

Payment-gated subscriptions introduce a status field that reflects subscription payment outcomes and helps your application manage entitlements. Metronome handles invoicing, payment-status tracking, and linked credit releases. Metronome also releases webhooks to enable you to grant or revoke access to your product.

Metronome initiates payment. On the scheduled invoice date, Metronome creates and finalizes the subscription invoice, sends it to Stripe Invoicing, and triggers an immediate payment attempt.
Metronome updates the subscription state. If payment succeeds, Metronome sets the subscription status to ACTIVE, updates the paid quantity of the subscription, sends a subscription.payment_gate_status webhook, and releases linked recurring credits according to their access policy. If payment fails, Metronome withholds credit release and sends a corresponding webhook.
Your application updates entitlements. Use Metronome webhooks and status reads to grant access for the paid quantity or block or suspend access after payment failure. Metronome updates the subscription’s billing state; it doesn’t directly enable or disable users in your application. Listen to Stripe webhooks for detailed payment failure reasons.

Before you begin

Set up your subscription pricing.
Configure your Stripe integration. Payment-gated subscriptions currently support only Stripe Invoicing. Ensure that each Stripe customer has a default payment method and a valid stored customer address. Without these, payment attempts fail.
Set up your webhook listeners. Listen for Metronome subscription status webhooks to manage entitlements. Also listen to Stripe webhooks for detailed PaymentIntent actions, such as 3DS authentication, and payment failure details.

Configure payment gating

For a hybrid pricing model that combines a subscription with recurring credits, configure two parts:

Subscription payment gate: Set payment_gate_config on the subscription. Metronome automatically tracks payment status on the subscription invoice and updates the subscription status so your application can manage access and quantity changes. You can configure a subscription payment gate with or without recurring credits.
Recurring credit access policy: Set subscription_config.access_policy on the linked recurring credit. Metronome manages credit releases based on subscription payment status and the policy you choose: require payment for each billing period, only the initial billing period, or neither. The linked subscription must have a payment gate configured.

Create a payment-gated subscription

Create a payment-gated subscription in the Metronome app or through the API, either when creating a new contract or when adding a subscription to an existing contract. Ensure that both the customer and the contract in Metronome have a valid Stripe billing provider configuration or subscription creation will fail. Consider an AI company that offers a $10 monthly subscription with 100 AI credits included. The company bills the subscription at the start of each month and grants that month’s credits only after payment succeeds. The following API call creates a contract for a new customer with a payment-gated subscription and linked recurring credits.

cURL

curl --request POST \
  --url https://api.metronome.com/v1/contracts/create \
  --header "Authorization: Bearer $METRONOME_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "customer_id": "4c09936b-455d-4c72-a120-d71b600a7546",
    "rate_card_id": "740a2ca1-64f6-417d-807a-05f154b3b1fe",
    "starting_at": "2026-10-01T00:00:00Z",
    "billing_provider_configuration": {
      "billing_provider_configuration_id": "e045c62b-65e7-4e84-a924-3f06f8b621d0"
    },
    "subscriptions": [
      {
        "temporary_id": "ai_starter_monthly",
        "name": "AI Starter",
        "collection_schedule": "advance",
        "initial_quantity": 1,
        "subscription_rate": {
          "billing_frequency": "monthly",
          "product_id": "ed518bcb-acc1-4cd8-85dd-880c2eb38994"
        },
        "proration": {
          "invoice_behavior": "bill_immediately",
          "is_prorated": true
        },
        "payment_gate_config": {
          "payment_gate_type": "STRIPE",
          "tax_type": "STRIPE"
        }
      }
    ],
    "recurring_credits": [
      {
        "access_amount": {
          "credit_type_id": "d3cb2827-dcb5-44af-9354-947a7197b9a6",
          "unit_price": 100
        },
        "subscription_config": {
          "subscription_id": "ai_starter_monthly",
          "access_policy": "BILLING_PERIOD_PAID"
        }
      }
    ]
  }'

Metronome creates and finalizes the subscription invoice and sends it to Stripe for a payment attempt. Metronome updates the subscription status when the payment succeeds or fails. While payment is pending or in flight, the subscription status remains unchanged. Use the getSubscriptionStatus API to inspect pending updates in open_invoices. Don’t grant access based on invoice creation or an in-progress payment. See Manage entitlements for more detail.

Choose when to release recurring credits

As shown in the API call above, attach a recurring credit or commit through subscription_config.subscription_id. When you create the subscription and credit in the same request, use the subscription’s temporary_id. Set subscription_config.access_policy to control whether payment gates the credit release. This field is required when the recurring credit or commit is linked to a payment-gated subscription.

Access policy	Definition	Use when
`BILLING_PERIOD_PAID`	Metronome releases each period’s credits after payment for that period succeeds. The initial payment and every renewal gate their corresponding credits.	Use if you are a company with high fraud risk and need to ensure payment each billing period regardless of customer history.
`INITIAL_BILLING_PERIOD_PAID_ONLY`	Metronome releases credits after the initial subscription payment succeeds. Later releases don’t wait for renewal payment.	Use when the highest risk vector is on initial sign-up or when you want to to avoid disruptive product experiences upon payment failure for customers with an existing payment history.

First-of-month processingA recurring credit gated on billing-period payment can take several hours to release when many subscriptions renew on the first day of the month. Gate only on initial billing period if you want to customers to have access to credits immediately when the new billing period begins.

Change subscription quantity

Suppose the AI company above adds a team plan where each seat costs $10 per month and includes 100 AI credits. A customer with one paid seat requests a second seat halfway through the month. Use the edit contract API to increase the subscription quantity by one, as shown below. See Manage seats for more information about quantity changes and linked credit behavior. Metronome creates an invoice for the additional seat and triggers payment in Stripe. With the example’s proration settings, the charge is prorated for the remaining billing period. While payment is pending, paid_quantity remains 1; don’t grant access to the additional seat yet.

cURL

curl --request POST \
  --url https://api.metronome.com/v2/contracts/edit \
  --header "Authorization: Bearer $METRONOME_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "customer_id": "4c09936b-455d-4c72-a120-d71b600a7546",
    "contract_id": "7f865c1b-1c08-40e8-9c09-b3238fd3b50d",
    "update_subscriptions": [
      {
        "subscription_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
        "quantity_updates": [
          {
            "quantity_delta": 1,
            "starting_at": "2026-10-15T12:00:00Z"
          }
        ]
      }
    ]
  }'

If payment succeeds, Metronome automatically updates the subscription quantity and releases additional linked credits. Metronome sends a webhook that your application can use to grant access to the second seat. If payment fails, Metronome automatically voids the quantity-change invoices in both Stripe and Metronome and doesn’t apply the seat increase. The original paid seat remains available. After the customer resolves the payment issue, retry by requesting the additional seat again; Metronome creates a new invoice and payment attempt.

One pending quantity change at a timeOnly one quantity change can be pending for a subscription at a time. While it is pending, no further changes are allowed except removing the pending change or ending the subscription. If a pending quantity change is not paid within one hour, Metronome automatically rolls back the quantity change and voids the corresponding invoices.

Manage entitlements

Use subscription status and paid quantity to determine product access, and use webhooks to keep your application’s entitlements up to date.

Subscription statuses

Status	Definition	Entitlement behavior
`NOT_STARTED`	The subscription hasn’t reached its start date or its initial payment hasn’t completed.	Don’t grant access.
`INCOMPLETE`	The initial subscription payment failed. No new invoices will be generated and subscription quantity cannot be changed.	Don’t grant access, potentially kick-off additional fraud prevention flows.
`ACTIVE`	The latest subscription-cycle payment succeeded. Pending quantity increases don’t change the paid quantity until payment succeeds.	Grant access for `paid_quantity`.
`UNPAID`	A recurring subscription payment failed. If subscription is not ended, renewal invoices will continue to be generated, but subscription quantity cannot be changed.	Revoke or suspend access according to your product policy. If the latest renewal invoice is paid, access can be regranted for the current billing period.
`ENDED`	The subscription has ended. This status is terminal.	Revoke access. Create a new subscription or contract if the customer restarts.

Handle subscription webhooks

Use Metronome webhooks to understand when payment is updated and manage product access. Metronome sends subscription.payment_gate_status whenever the paid quantity, subscription status, or external invoice is updated, except for the transition to ENDED. This includes successful renewals and quantity changes even when the subscription remains ACTIVE. Enable lifecycle events separately to handle subscription endings. Treat Metronome as the source of truth for entitlement state and Stripe as the source of truth for payment actions.

Listen for subscription.payment_gate_status and enabled lifecycle events.
Read the updated status and paid_quantity to determine the customer’s entitlement.
Grant or update access for the paid quantity when the subscription is ACTIVE.
Block or suspend access after an unsuccessful initial or renewal payment, according to your product policy. Remove access when the subscription ends.
Make webhook handlers idempotent and use webhook delivery retries to recover from failed processing.

The following example shows a successful payment for an initial sign-up of one subscription seat.

{
  "id": "dba7c77a-4ccb-4280-a45b-8d43fc6ae3d0",
  "type": "subscription.payment_gate_status",
  "properties": {
    "customer_id": "4c09936b-455d-4c72-a120-d71b600a7546",
    "contract_id": "7f865c1b-1c08-40e8-9c09-b3238fd3b50d",
    "subscription_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
    "status": "ACTIVE",
    "paid_quantity": 1,
    "invoice_id": "0f159078-7915-4b3c-97ea-9a6bb7a8d638",
    "changes": [
      "status",
      "paid_quantity",
      "invoice_id",
      "external_invoice.invoice_id",
      "external_invoice.external_status",
      "external_invoice.payment_intent_id"
    ],
    "external_invoice": {
      "invoice_id": "in_123",
      "payment_intent_id": "pi_123",
      "external_status": "PAID"
    }
  }
}

Use changes to understand why an event arrived, but use the updated status and paid_quantity to set entitlements. Note that a successful renewal can update the invoice fields without changing the subscription’s status or paid quantity.

Enable lifecycle eventsLifecycle events aren’t enabled automatically. Enable them for your webhook destination. An ENDED subscription doesn’t produce a subscription.payment_gate_status event. Use lifecycle events to remove access at the subscription end date.

Read subscription state through the API

Use the getSubscriptionStatus API to programmatically view subscription state, reconcile entitlements, or check whether a payment is still pending. Pending or in-flight payments don’t update subscription status; inspect open_invoices for payable invoices and pending quantity changes. Don’t grant access based on an entry in open_invoices. The response includes the following fields:

status represents the subscription’s current payment-backed lifecycle state.
paid_quantity is the quantity your application can entitle. During a pending quantity increase, it remains at the last successfully paid quantity.
latest_cycle_invoice describes the latest subscription-cycle invoice with a conclusive payment outcome, whether successful or unsuccessful. It doesn’t represent a mid-period quantity-change invoice.
open_invoices lists payable subscription-cycle and quantity-change invoices that haven’t reached a terminal state. Use this field for diagnostics, not to grant access.

cURL

curl --request POST \
  --url https://api.metronome.com/v1/subscriptions/getStatus \
  --header "Authorization: Bearer $METRONOME_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "customer_id": "4c09936b-455d-4c72-a120-d71b600a7546",
    "contract_id": "7f865c1b-1c08-40e8-9c09-b3238fd3b50d",
    "subscription_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2"
  }'

For example, a customer has paid for one seat and requests a second seat. While payment for the additional seat is pending, the response shows the original paid quantity and an open quantity-change invoice:

{
  "status": "ACTIVE",
  "paid_quantity": 1,
  "latest_cycle_invoice": {
    "id": "0f159078-7915-4b3c-97ea-9a6bb7a8d638",
    "starting_at": "2026-10-01T00:00:00Z",
    "ending_before": "2026-11-01T00:00:00Z",
    "quantity": 1,
    "external_invoice": {
      "invoice_id": "in_123",
      "external_status": "PAID"
    }
  },
  "open_invoices": [
    {
      "id": "7f7c8958-83c6-4efa-91fd-593a50c9e196",
      "starting_at": "2026-10-15T12:00:00Z",
      "ending_before": "2026-11-01T00:00:00Z",
      "quantity": 1,
      "reason": "subscription_quantity_update",
      "external_invoice": {
        "invoice_id": "in_seat_upgrade_123",
        "external_status": "OPEN"
      }
    }
  ]
}

In the preceding response, a subscription quantity-update invoice is still in flight. Metronome has sent it to Stripe, but payment hasn’t succeeded, so the Stripe invoice status remains OPEN.

Handle payment failures

Listen to Stripe invoice and PaymentIntent webhooks to handle detailed payment failures and customer actions such as 3DS authentication. For example, invoice.payment_action_required indicates that the customer must complete an authentication action. Use Metronome subscription webhooks to manage product access and Stripe webhooks to guide the customer through resolving the payment issue.

Recover initial and renewal payments

Initial and renewal invoices have a 13-day payment window to accommodate payment methods such as ACH and give you time to handle payment recovery. This window isn’t an entitlement grace period: a failed payment still updates subscription status so your application can block or suspend access. Unlike failed quantity-change invoices, initial and renewal invoices remain payable during this window. For example, if a renewal payment fails:

Metronome sends a subscription.payment_gate_status webhook with status UNPAID. Your application suspends access according to your product policy.
Stripe sends a payment-failure notification. Your application prompts the customer to update their payment method or complete a required authentication action.
The customer resolves the issue and the invoice is paid within the payment window.
Metronome updates the subscription to ACTIVE, sends a webhook, and releases credits as applicable. Your application restores access for paid_quantity.

If an initial payment fails, the same recovery flow applies with status INCOMPLETE instead of UNPAID.

Invoice expiration

If payment doesn’t succeed within 13 days, Metronome automatically voids the Stripe invoice, which also voids the corresponding Metronome invoice. All open invoices expire at the end of their billing period, even if the 13-day window hasn’t elapsed. The effective deadline is the earlier of the 13-day payment deadline and the billing-period end. Your Stripe payment recovery settings, including Smart Retries, continue to apply automatically while the invoice remains open. Use Stripe webhooks to handle payment recovery actions. Failed quantity-change invoices don’t use this recovery window: retry those by requesting the seat increase again.

Private preview limits

The following configuration limits apply during the private preview:

Quantity-based subscriptions only. Seat-based subscriptions that track individual seat IDs aren’t supported yet.
Payment gated subscriptions must be billed in-advance (collection_schedule: "advance") and quantity updates billed immediately (proration.invoice_behavior: "bill_immediately").
Stripe Tax and Stripe Invoicing are the only supported downstream tax and invoicing systems.
Invoice placement must be set on the scheduled invoice and cannot be combined with usage invoices.

GET STARTED

IMPLEMENT METRONOME

EVENTS

PRICING & PACKAGING

CUSTOMERS & BILLING

INVOICING

REPORTING & INSIGHTS

PLATFORM CONFIGURATION

Payment gate a subscription

How payment-gated subscriptions work

Before you begin

Configure payment gating

Create a payment-gated subscription

Choose when to release recurring credits

Change subscription quantity

Manage entitlements

Subscription statuses

Handle subscription webhooks

Read subscription state through the API

Handle payment failures

Recover initial and renewal payments

Invoice expiration

Private preview limits

​How payment-gated subscriptions work

​Before you begin

​Configure payment gating

​Create a payment-gated subscription

​Choose when to release recurring credits

​Change subscription quantity

​Manage entitlements

​Subscription statuses

​Handle subscription webhooks

​Read subscription state through the API

​Handle payment failures

​Recover initial and renewal payments

​Invoice expiration

​Private preview limits

How payment-gated subscriptions work

Before you begin

Configure payment gating

Create a payment-gated subscription

Choose when to release recurring credits

Change subscription quantity

Manage entitlements

Subscription statuses

Handle subscription webhooks

Read subscription state through the API

Handle payment failures

Recover initial and renewal payments

Invoice expiration

Private preview limits