Payment-gated commits
Organizations commonly implement a prepaid model for their PLG customers. Customers must pay for usage in advance of using the product and organizations gate access pending successful payment. This can be implemented in Metronome using payment-gated commits. When a payment-gated commit is created, Metronome facilitates the following:
- Metronome immediately triggers a payment attempt based on the invoice amount of the commit.
- If the payment succeeds, Metronome releases the commit and the customer is granted access to the associated balance.
- If the payment fails, Metronome voids the resource and sends a webhook notification.
- If further action is required (e.g. for 2F authentication), Metronome sends a webhook notification.
Add a payment-gated commit to an existing contract
Payment gated commits can only be added to existing contracts. You can create a payment-gated commit by editing the user's contract. Make sure the contract has a valid billing configuration. See below for an example API call:
{
"customer_id": "8cecbf69-960f-4f66-9575-edebb7d95e88",
"contract_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
"add_commits": [
{
"product_id": "d6be3bf4-1669-40c9-a8b1-388bb167ab16",
"type": "prepaid",
"invoice_schedule": {
"schedule_items": [
{
"timestamp": "2025-04-01T00:00:00.000Z",
"amount": 2000
}
]
},
"access_schedule": {
"schedule_items": [
{
"amount": 2000,
"starting_at": "2025-04-01T00:00:00.000Z",
"ending_before": "2026-04-01T00:00:00.000Z"
}
]
},
"payment_gate_config": {
"payment_gate_type": "STRIPE",
"tax_type": "STRIPE"
},
"priority": 100
}
]
}
Manage notifications
Two types of webhook notifications are emitted when creating a payment-gated commit:
payment_gate.payment_status
after payment has been attempted. The status of that payment,paid
orfailed
, is denoted in thepayment_status
field.payment_gate.payment_pending_action_required
if intervention is required to process payment.
Handle failed payments
If payment fails, the associated invoice in Metronome and Stripe is voided and no commit is created. To retry the payment, send a new API request with the relevant commit information.
Metronome does not automatically retry failed payments (as any automatic retries would likely fail, too).