Skip to main content

​
What is Auto-refill?

When you bill usage against Customer Credits with a prepaid usage price, a customer’s bucket eventually runs dry. Auto-refill is what happens next:
  1. Exhaustion notice. The first settlement that a bucket cannot cover emails the customer and sends you a customer_credits.exhausted webhook, once per exhaustion rather than once per refused request.
  2. Automatic top-up. If the customer has opted in, Creem re-purchases the credit top-up product they chose, using the payment method saved from their earlier checkout. The product’s own fulfilment grants the credits, and settlement resumes.
Both parts are built for a usage flow where thousands of events can arrive between one human action and the next. You do not get a flood of notices, and a customer is never charged twice for one refill.
Auto-refill applies to usage that Creem settles for you through a prepaid usage price, described in Step 5 of Usage-based Billing. Debits you make yourself through the API that exceed the balance simply fail with 422 and the error code insufficient_balance, so your own code decides what to do.

​
Requirements

  • A credit top-up product. A product with a customerCredits feature that grants credits into the bucket your usage price debits. This is the product Creem re-purchases. Its price at the time of the refill is what the customer pays, so re-pricing it applies to future refills automatically.
  • A prepaid usage price on the customer’s plan that debits the same bucket.
  • A previous checkout by the customer on your store. The refill is charged to the payment method saved during that checkout, and the customer’s tax location comes from their most recent checkout as well. Without both, Creem does not attempt a charge.
  • The customer’s consent, described below. Auto-refill is opt-in per customer and per bucket, and never charges anyone who has not agreed to it.

​
Exhaustion Notices

An exhaustion is an episode: the stretch between two grants into a bucket. Within one episode the customer gets one email and you get one customer_credits.exhausted webhook, no matter how many settlements are refused. Any credit that reaches the bucket, whether a top-up purchase, a subscription renewal, an auto-refill, or a grant through the API, ends the episode. If the bucket runs dry again after that, you are notified again. The webhook carries the bucket, the unit label, and shortfall_minor_units, the amount the refused settlement was short. Use it to prompt the customer in your own product, pause the feature that consumes credits, or trigger your own top-up flow. When an auto-refill succeeds, the exhaustion is resolved before any notice goes out, so you receive credits.auto_recharged and credits.granted instead of customer_credits.exhausted. See the payload in the webhook reference. Consent belongs to the customer. It names the credit top-up product to re-purchase and the limits the customer accepts, and the customer can revoke it at any time. Revoking keeps the configured limits, so opting back in does not reset them.
Caps are applied to the product price before tax. Tax depends on the customer’s location rather than on a choice, so a pre-tax cap keeps the same configured number meaning the same amount of credit everywhere. The amount that leaves the customer’s account can be up to their local tax rate higher than the cap.
A refill that would break a guardrail is skipped and nothing is charged. The exhaustion notice still goes out, so the customer knows to top up by hand.
Consent is stored per customer and bucket on Creem. The switch for customers to opt in from the hosted customer portal is not available yet. If you want to offer auto-refill to your customers today, contact support@creem.io.

​
How a Refill Is Charged

A refill is a purchase, not a bare card charge, so it appears in your dashboard, reports, and payouts like any other order.
  1. Nothing is charged without consent and a saved payment method. Both are checked first, along with the guardrails.
  2. Tax is calculated from the customer’s most recent checkout location, and the customer pays the product price plus that tax. The price is the product’s current price, not the price at the time of consent.
  3. An order is opened before the charge and completed only when the payment is confirmed. If a charge ends in an ambiguous state, there is always a record to reconcile against, and the customer is never charged again for the same refill.
  4. The saved payment method is charged off-session. A payment that needs the customer’s confirmation, such as 3-D Secure, is left pending rather than retried.
  5. The product’s fulfilment grants the credits, exactly as it would after a checkout. Settlement of the customer’s usage picks up from there.
Platform fees on a refill are the same as on a checkout payment of the same amount.

​
What You Receive

See the webhook reference for the payloads.

​
When a Refill Fails

In every case the customer can still buy credits through a normal checkout, and any grant ends the exhaustion episode.

Usage-based Billing

Meters, event ingestion, and prepaid usage prices that settle against credits

Transactions

Credit, debit, and reverse balances through the API

Webhooks

Every credits event, with sample payloads

Customer Portal

Where customers manage their purchases and payment methods