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.

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 represents the quantity of usage and must be greater than 0 (for example, 1 SMS sent or 5 orders processed). Billing events have a 24-hour idempotency window — requests with a previously seen idempotency_key within that window are ignored.

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

Anchor to Billing error statesBilling error states

The following errors can occur when processing billing events. These errors appear in the Dev Dashboard:

ErrorDescription
INVALID_ACCOUNTThe app or partner account is invalid or not authorized.
ACCOUNT_FROZENThe partner account is frozen and can't process billing events.
NO_SUBSCRIPTIONThe merchant doesn't have an active subscription to your app.
SUBSCRIPTION_NOT_METEREDThe merchant's subscription doesn't include usage-based pricing.
PERIOD_CLOSEDThe billing period for this event has already closed. The timestamp must fall within the merchant's current billing cycle.
INVALID_TIMESTAMPThe timestamp is missing, malformed, or outside the acceptable range. The timestamp can't be more than 5 minutes in the future, and for billing events it must fall within the merchant's current billing cycle.
IDEMPOTENCY_KEY_ERRORThe idempotency key is missing, already used, or invalid.
INVALID_VALUEThe value in the attributes is invalid (for example, zero, negative, or non-numeric). The value must be greater than 0.
MISSING_VALUE_KEYThe value key is missing from the attributes.

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?