Skip to main content

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.

Anchor to When to use usage-based pricingWhen 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

Anchor to Pricing structuresPricing structures

You can choose from three usage-based pricing structures:

Anchor to Fixed pricingFixed pricing

Charge a uniform price for each billing event. For example, charge $0.01 per SMS sent or $0.50 per order processed.

Anchor to Graduated pricingGraduated 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

Anchor to Volume pricingVolume 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)

Anchor to How usage-based pricing worksHow 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.

Anchor to Step 1: Configure meters in the Partner DashboardStep 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 for the exact format.

Anchor to Step 2: Send events using the App Events APIStep 2: Send events using the App Events API

Once your meters are configured, use the App Events API 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.

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. 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.

Anchor to Step 3: Validate events in the Dev DashboardStep 3: Validate events in the Dev Dashboard

After sending events, verify they're being received and classified correctly in the Dev Dashboard:

  1. Open the Dev Dashboard 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 each event's status is OK

The status of a billing event is OK when Shopify recorded the usage. Otherwise, the status is the event's billing result code.

If an event isn't listed as an App billing event, then the event_handle in your API request doesn't match any meter handle configured in the Partner Dashboard Pricing section. Shopify records a billing result only for events that match a meter. An event that matches no meter isn't billed and is listed only as an App event. The handle must match exactly between your App Events API 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 returns a 202 response when it accepts your request, even if the event later fails billing validation. There is no synchronous billing error response and no webhooks for billing validation failures.

Anchor to Billing error statesBilling error states

The following billing result codes can appear in the Dev Dashboard when Shopify can't record usage for an event. The event isn't billed. For solutions, refer to Troubleshoot billing errors.

ErrorDescription
INVALID_VALUEThe 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. Values can have at most 6 decimal places and at most 15 digits before the decimal point.
MISSING_VALUE_KEYThe value key is missing from the attributes.
INVALID_ACCOUNTShopify couldn't find the store in shop_id, or the store doesn't have a billing account.
NO_SUBSCRIPTIONThe store doesn't have a subscription to your app, or the subscription isn't active.
INVALID_SUBSCRIPTIONThe store's subscription to your app was created with the Billing API, not Shopify App Pricing.
SUBSCRIPTION_NOT_METEREDThe merchant's subscription doesn't include usage-based pricing.
NO_MATCHING_METERThe merchant's subscription includes usage meters, but none of them matches the event's event_handle.
PERIOD_CLOSEDThe billing period for this event has already closed. The timestamp must fall within the merchant's current billing cycle.
INTERNAL_ERRORShopify couldn't process the event because of a problem on Shopify's side. Don't resend the event, including with a new idempotency key. Contact Shopify Partner Support and include the event's idempotency key.

Shopify enables some of these checks gradually, so you might not see every code for your app. Idempotency key problems aren't billing result codes: the App Events API rejects a missing or too-long idempotency_key when you send the request.

Anchor to Step 4: Automated billingStep 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.

Anchor to Combining pricing modelsCombining 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.

Anchor to LimitationsLimitations

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.

Anchor to Next stepsNext steps

Was this page helpful?