--- title: Setup usage charges description: Set up usage-based pricing with Shopify App Pricing. source_url: html: >- https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/subscription-billing/setup-usage-charges md: >- https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/subscription-billing/setup-usage-charges.md --- # Setup usage charges Usage-based pricing lets you charge merchants based on their actual usage of your app's features. This pricing model is ideal for apps where costs scale with usage, such as messaging apps, email marketing tools, or apps that process transactions. Usage-based pricing accounts for over 60% of revenue from top-earning apps on the Shopify App Store. *** ## When to use usage-based pricing Consider usage-based pricing if your app: * **Sends messages or emails**: Charge per SMS sent, email delivered, or notification pushed * **Processes transactions**: Charge based on order volume, revenue generated, or items sold * **Uses external APIs**: Pass through costs for third-party services like shipping carriers or payment processors * **Provides compute-intensive features**: Charge for AI processing, image optimization, or data analysis * **Offers variable-value features**: Align costs with the value merchants receive *** ## Pricing structures You can choose from three usage-based pricing structures: ### Fixed pricing Charge a uniform price for each billing event. For example, charge $0.01 per SMS sent or $0.50 per order processed. ### Graduated pricing Price tiers based on cumulative usage. As merchants use more, they pay different rates for usage in each tier. The final charge is the sum of all tiers. For example, with tiers set as: * 1-100 units at $10 per unit * 101-200 units at $9 per unit * 201+ units at $8 per unit If a merchant uses 150 units, they pay: (100 × $10) + (50 × $9) = $1,450 ### Volume pricing Price tiers based on total usage volume. The rate for the entire quantity is determined by which tier the total usage falls into. For example, with the same tier structure: * 1-100 units at $10 per unit * 101-200 units at $9 per unit * 201+ units at $8 per unit If a merchant uses 150 units, they pay: 150 × $9 = $1,350 (using the 101-200 tier rate) *** ## How usage-based pricing works Usage-based pricing requires you to configure meters in the Partner Dashboard and then send billing events to Shopify using the [App Events API](https://shopify.dev/docs/api/app-events). ### Step 1: Configure meters in the Partner Dashboard In your app's submission page, define the usage meters you want to track: 1. Navigate to your app in the Partner Dashboard 2. Go to the **Pricing** section 3. Create a usage meter and give it an `event_handle` (for example, `sms_sent`, `email_delivered`, `order_processed`) 4. Configure your pricing structure (fixed, graduated, or volume) for each meter 5. Set your pricing tiers and rates You can create up to five usage meters per plan to track different types of usage. Whether a meter tracks whole units (such as messages or orders) or fractional units (such as gigabytes or compute hours) is set by the `value` you send in each event, not by a separate meter option. Send whole units as integers, and fractional units as decimal amounts in a quoted string. See [Understand the request fields](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/subscription-billing/build-billing-event#understand-the-request-fields) for the exact format. ### Step 2: Send events using the App Events API Once your meters are configured, use the [App Events API](https://shopify.dev/docs/api/app-events) to send billing events to Shopify as they occur in your app. The `event_handle` in each request must match the meter handle you defined in the Partner Dashboard. ```bash curl -X POST "https://api.shopify.com/app/unstable/events" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer {access_token}" \ -d '{ "shop_id": "gid://shopify/Shop/12345678", "event_handle": "sms_sent", "timestamp": "2026-01-27T14:30:00Z", "idempotency_key": "sms_12345_1706365800", "attributes": { "value": 1 } }' ``` The `event_handle` must match the meter handle you configured in the Partner Dashboard. The `value` in the `attributes` object is a non-zero quantity of usage. For details see [Understand the request fields](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/subscription-billing/build-billing-event#understand-the-request-fields). Idempotency is enforced permanently for billing events, always use a new `idempotency_key` for each distinct charge or reversal. **Caution:** Don't include any data that, alone or in combination with other data, could identify an individual. This includes any merchant or buyer information, such as name, email address, phone number, and other identifiable data points. Use anonymized identifiers and aggregated metrics instead. For detailed implementation instructions, see [Build a billing event](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/subscription-billing/build-billing-event). ### Step 3: Validate events in the Dev Dashboard After sending events, verify they're being received and classified correctly in the [Dev Dashboard](https://shopify.dev/docs/apps/build/dev-dashboard/monitoring-and-logs): 1. Open the [Dev Dashboard](https://dev.shopify.com) and navigate to your app 2. Go to the **Logs** section 3. Under the **Type** filter, select **App Billing Event** to see only events tied to your pricing meters 4. Verify that your events appear as billable and are associated with the correct meters If an event doesn't appear under **App Billing Event**, the `event_handle` in your API request doesn't match the meter handle configured in the Partner Dashboard **Pricing** section. The handle must match exactly between your [App Events API](https://shopify.dev/docs/api/app-events) request and your pricing configuration. If an event fails validation, review the error details and update your implementation accordingly. **Info:** The Dev Dashboard is the only place to see billing errors for your events. The App Events API always returns a `202` response when it receives your request, even if the event fails billing validation. There is no synchronous billing error response and no webhooks for billing validation failures. In the dashboard, events are marked as successful or failed, and labeled as billable or non-billable. #### Billing error states The following errors can occur when processing billing events. These errors appear in the Dev Dashboard: | Error | Description | | - | - | | `INVALID_ACCOUNT` | The app or partner account is invalid or not authorized. | | `ACCOUNT_FROZEN` | The partner account is frozen and can't process billing events. | | `NO_SUBSCRIPTION` | The merchant doesn't have an active subscription to your app. | | `SUBSCRIPTION_NOT_METERED` | The merchant's subscription doesn't include usage-based pricing. | | `PERIOD_CLOSED` | The billing period for this event has already closed. The timestamp must fall within the merchant's current billing cycle. | | `IDEMPOTENCY_KEY_ERROR` | The idempotency key is missing, already used, or invalid. | | `INVALID_VALUE` | The `value` in the attributes is zero, or isn't a valid number. Use a non-zero number: send a negative value to reverse usage, and send fractional values as a quoted string, such as `"1.5"`. Unquoted floating-point numbers are rejected. | | `MISSING_VALUE_KEY` | The `value` key is missing from the attributes. | ### Step 4: Automated billing Once events are validated and accepted, Shopify automatically: 1. Aggregates usage for each merchant based on your configured meters 2. Applies your pricing structure (fixed, graduated, or volume) 3. Adds the calculated charges to the merchant's monthly bill **Info:** After a merchant uninstalls your app, you have 24 hours to submit any remaining billing events for usage that occurred before the uninstall. After 24 hours, the billing period closes and new events are rejected with a `PERIOD_CLOSED` error. Make sure your app sends any pending billing events promptly when you receive an [app uninstalled webhook](https://shopify.dev/docs/apps/build/compliance/privacy-law-compliance). *** ## Combining pricing models You can combine recurring charges with usage-based pricing to create hybrid pricing plans: * **Base fee + usage**: Charge a monthly subscription fee plus usage-based charges (for example, $29/month + $0.01 per SMS) * **Usage only**: Uncheck the subscription fee and charge only for usage * **Tiered plans with usage**: Offer different base tiers with varying usage rates or included usage allowances You can't currently combine usage-based pricing with yearly-only plans. Usage charges must be tied to a monthly billing cycle. Learn more about [combining time and usage](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/subscription-billing/combined-subscription-and-usage). *** ## Limitations Usage-based pricing has the following limitations: * You can create up to five active usage meters per plan * You can define up to six pricing tiers per usage meter * Usage charges must be billed monthly (can't be combined with yearly-only plans) * Usage caps aren't currently supported * After a merchant uninstalls your app, you have 24 hours to submit any remaining billing events. After 24 hours, the billing period is closed and new events are rejected. *** ## Next steps * [Build a billing event](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/subscription-billing/build-billing-event) to start sending usage data * Explore the [App Events API reference](https://shopify.dev/docs/api/app-events) for implementation details * Learn about [time-based subscriptions](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/subscription-billing/setup-subscription-charges) * [Combine time and usage](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/subscription-billing/combined-subscription-and-usage) for hybrid pricing * Offer [free trials](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/subscription-billing/offer-free-trials) to increase conversions ***