Shopify usage caps are not prepaid credits: how to combine bundles and usage billing

A spending ceiling does not buy a credit balance

On October 13, Shopify Staff member Donal-Shopify answered a developer’s questions about prepaid product-optimization bundles and usage billing. The explanation matches the usage-subscription documentation: cappedAmount is the maximum usage charge within a 30-day billing cycle. It neither collects payment upfront nor creates a balance.

Suppose an app sets a €20 usage cap. Usage charges for that cycle can reach €20, but the merchant has not thereby purchased 100 operations. The €20 and 100-operation bundle came from the community question as a hypothetical offer, not a standard Shopify fee.

Once the cap is reached, further usage charges are blocked until the next cycle or an appropriate cap update takes effect. Explain the current charges and available actions to the merchant. A blocked charge does not create extra prepaid credits.

Check the pricing method before designing the bundle

With Manual Pricing, the app manages billing through the Billing API. The staff-recommended combination uses appPurchaseOneTimeCreate for a one-time credit bundle and a usage-based subscription for uncovered work. Your app tracks the balance and consumption; Shopify does not create a native credit wallet for this model.

Shopify App Pricing instead hosts plan selection and accepts applicable usage through the App Events API. Its current documentation says one-time purchases and usage caps are unsupported. Billing API billing mutations are blocked for enrolled apps, so the Manual Pricing cap and webhook flow below cannot simply be reused.

For new public apps, Shopify App Pricing is the default when it supports the pricing model. The community thread has not answered whether an unlaunched app can switch back to Manual Pricing or how that affects submission and review. A team needing bundles should confirm its own switching conditions with Shopify; this explanation is not review approval.

Keep the bundle purchase and uncovered usage separate

First, create a one-time purchase request under Manual Pricing and obtain merchant approval. When the merchant returns, query and verify the purchase status on your server before granting the credits promised by your plan. A return-page visit alone is insufficient.

Second, create a usage-based subscription with clear terms, usage prices and cappedAmount, and obtain approval. Usage records then use the AppSubscriptionLineItem.id returned for that subscription, rather than the one-time purchase ID.

Third, check and consume your app’s credits for each operation. Use appUsageRecordCreate only for work the bundle does not cover. Associate the purchase, credit changes and charge records in your ledger so one operation does not both consume a credit and incur the full usage charge.

For a hypothetical 100-operation bundle followed by 105 optimizations, the first 100 consume bundle credits and the remaining five follow the approved usage rules. Credit expiry, charging for failed operations and the overage price remain choices your app must explain; cappedAmount does not decide them.

Match EUR to app billing, not the storefront display

In the follow-up for a developer using Admin GraphQL API 2026-07, Donal-Shopify said EUR is supported for a one-time purchase price and a usage cappedAmount. The currencyCode in appUsageRecordCreate must match the parent subscription’s cap, with one currency per subscription.

The same reply recommends shopBillingPreferences for the merchant’s app-billing currency, rather than storefront currency. Check the billing preference and approved subscription before submitting a matching usage record. A euro storefront does not establish that the current app subscription also bills in euros.

An increased cap takes effect after merchant approval

The 2026-07 appSubscriptionLineItemUpdate reference lets an app request a new cappedAmount using the existing usage line-item ID. A new subscription is not required solely for that adjustment. The mutation returns a confirmationUrl where the merchant approves or declines the change.

Check userErrors, then direct the merchant to confirmationUrl. The higher limit does not take effect before approval. After approval, reread the line item on the server and confirm the new cap before recording charges that were previously blocked. A successful mutation response does not substitute for approval.

Use webhooks for synchronization, with reconciliation

For Manual Pricing, monitor APP_SUBSCRIPTIONS_UPDATE, APP_PURCHASES_ONE_TIME_UPDATE and APP_SUBSCRIPTIONS_APPROACHING_CAPPED_AMOUNT. The last notification fires when usage reaches or exceeds 90% of the cap, allowing an earlier warning instead of waiting for a failed charge.

For HTTPS deliveries, verify the HMAC against the raw request body before processing, and handle duplicate deliveries using X-Shopify-Webhook-Id. Shopify documents eight retries over the next four hours after failed HTTPS delivery. Delivery is not always guaranteed, and neither ordering within a topic nor ordering across topics is guaranteed. Reconcile periodically through the API.

That is the Billing API flow. Shopify App Pricing currently uses redirect parameters and Partner API queries rather than these subscription-change webhooks. Historical events explain changes; activeSubscription is the query for the merchant’s current active subscription state.

Reconcile a refund before adjusting credits

Shopify staff recommend the Partner API for reconciling one-time bundle refunds. The 2026-07 Historical Events documentation includes EARNING_REFUND, with Earning fields such as chargeId, grossAmount and netAmount to correlate the purchase and refunded amount.

Historical events must be enabled for the organization, and the API client needs Manage apps permission. Set the query period and complete cursor pagination. Backfilled events may require metadata.legacyChargeId to match the original billing record. Confirm the refund and purchase before adjusting credits under your app’s rules; a partial refund does not automatically justify reversing the entire bundle.

No refund settlement deadline, credit-expiry rule or app-review result is guaranteed here. An authorized team can validate approval, exhausted credits, a reached cap, a declined increase, duplicate notifications and refund reconciliation in development stores. This article has not created charges, changed merchant plans or issued refunds.