Skip to main content

Build a Billing Event

Usage-based billing for Shopify apps relies on two systems working together:

  • Shopify App Pricing: Defines your pricing plans, billing meters, and pricing structures in the Partner Dashboard. Shopify App Pricing handles plan selection, merchant approval, and automatic charge calculation.
  • App Events API: Reports billing events from your app to Shopify. When an event's handle matches a billing meter defined in Shopify App Pricing, Shopify automatically counts it toward the merchant's usage charges.

In this tutorial, you'll build an SMS messaging app that charges merchants per message sent. You'll use Shopify App Pricing to configure a plan with a usage meter, then use the App Events API to report each SMS as a billing event. Shopify handles everything in between — plan selection, charge approval, usage tracking, and invoicing.

Anchor to What you'll learnWhat you'll learn

In this tutorial, you'll learn how to do the following tasks:

  • Use Shopify App Pricing to create a plan with usage-based billing meters
  • Configure a welcome link and redirect merchants to the plan selection page
  • Authenticate with the App Events API
  • Send billing events that match your Shopify App Pricing meters
  • Verify that Shopify App Pricing correctly processes your billing events in the Dev Dashboard

Anchor to RequirementsRequirements

Anchor to Step 1: Configure usage-based pricing with Shopify App PricingStep 1: Configure usage-based pricing with Shopify App Pricing

Before you can send billing events through the App Events API, you need to use Shopify App Pricing to create a pricing plan and define a billing meter. The meter's handle is what connects your API requests to the pricing configuration — when an event's event_handle matches a meter handle, Shopify knows to bill for it.

Anchor to Create a plan with usage-based pricingCreate a plan with usage-based pricing

  1. From the Partner Dashboard, click Apps > All Apps and click your app's name.
  2. Click Distribution.
  3. Beside Shopify App Store listing, click Manage listing.
  4. Under Published languages, click Edit for the locale you want to update.
  5. Under Pricing content, click Manage to open the Pricing index page.
  6. Under Public plans, click Add to open the plan editor.
  7. Under Billing, select Monthly as the billing period.
  8. Under Monthly charge, enter 9.99 as the base subscription fee.

The base fee gives merchants access to your app. Usage-based charges for SMS messages are added on top of this fee.

Anchor to Add a usage meter for SMSAdd a usage meter for SMS

Usage meters track specific types of usage in your app. Each meter has a handle that you'll reference when sending billing events through the API.

  1. In your plan editor, click Add usage meter.

  2. Configure the meter with the following values:

    FieldValue
    NameSMS messages sent
    Handlesms_sent
    Pricing structureFixed
    Unit price$0.01
    Included units100

In this configuration, each merchant gets 100 free SMS messages per month. After that, each additional message costs $0.01. Shopify App Pricing automatically handles the calculation and adds the charges to the merchant's monthly bill.

Warning

The event_handle you send through the App Events API must exactly match the meter handle you define in Shopify App Pricing. Handles are case-sensitive. A mismatched handle causes the event to be marked as non-billable in the Dev Dashboard.

Anchor to Configure the welcome linkConfigure the welcome link

The welcome link is where merchants are redirected after they approve your plan charge. Use it to guide merchants into your app's onboarding experience.

  1. In the plan editor, find the Welcome link field.

  2. Enter a redirect path or URL:

    • Apps with a landing page in App Home: Specify a relative path to your app root, such as /welcome. Your plan_handle URL parameter is appended to all redirect URLs which is a plan that merchant is subscribed to.
    • Apps without a landing page in App Home: Redirect to a valid URL (including the http or https protocol). URL parameters for the plan_handle and the merchant shop domain are appended to redirect URLs.

  3. Click Save to save the plan.

Info

After a merchant is redirected to your welcome link, query the Active Subscription API on the Partner API to verify the subscription status before granting access to paid features.

Anchor to Add plan descriptionsAdd plan descriptions

Plans need a display name and feature list for each language your app listing supports. A plan only displays to merchants if it has a description for their language.

  1. From the Partner Dashboard, navigate back to your app's Pricing content.
  2. Find the plan you created.
  3. Under Display name, enter a name like SMS Pro.
  4. Under Top features, list the features included in the plan. For example:
    • Send SMS messages to customers
    • 100 free messages per month
    • $0.01 per additional message
  5. Click Save.
  6. Repeat for each published language in your app listing.

Anchor to Step 2: Redirect merchants to the Shopify App Pricing plan selection pageStep 2: Redirect merchants to the Shopify App Pricing plan selection page

Shopify App Pricing hosts the plan selection page for your app. When merchants install your app or need to select a plan, redirect them to this page. It displays the plans you configured in Step 1 and handles the approval flow.

Anchor to Build the redirect in your appBuild the redirect in your app

Your app's plan selection page URL follows this pattern:

https://admin.shopify.com/store/:store_handle/charges/:app_handle/pricing_plans

In your app's root route loader, check whether the merchant has an active subscription using the Active Subscription API on the Partner API. If not, redirect them to the plan selection page:

app/routes/app.jsx

export const loader = async ({ request }) => {
const appHandle = "YOUR_APP_HANDLE";

const { authenticate } = await import("../shopify.server");
const { admin, redirect, session } = await authenticate.admin(request);

// Get the store handle from the session and the shop GID from the Admin API
const storeHandle = session.shop.replace(".myshopify.com", "");
const shopResponse = await admin.graphql(`{ shop { id } }`);
const { data: { shop: { id: shopId } } } = await shopResponse.json();

// Check subscription status via the Partner API
const subscription = await fetchActiveSubscription(shopId);

if (!subscription) {
return redirect(
`https://admin.shopify.com/store/${storeHandle}/charges/${appHandle}/pricing_plans`,
{ target: "_top" }
);
}

return { apiKey: process.env.SHOPIFY_API_KEY || "" };
};

async function fetchActiveSubscription(shopId) {
// The Partner API uses a static access token created in the Partners Dashboard
// under Settings > Partner API clients. Store it as SHOPIFY_PARTNER_API_ACCESS_TOKEN.
const res = await fetch(
`https://partners.shopify.com/${process.env.SHOPIFY_PARTNER_ORG_ID}/api/unstable/graphql.json`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Shopify-Access-Token": process.env.SHOPIFY_PARTNER_API_ACCESS_TOKEN,
},
body: JSON.stringify({
query: `query ($appId: ID!, $shopId: ID!) {
activeSubscription(appId: $appId, shopId: $shopId) { billingPeriod }
}`,
variables: {
appId: process.env.SHOPIFY_APP_GID,
shopId,
},
}),
}
);
const { data } = await res.json();
return data?.activeSubscription ?? null;
}

Replace YOUR_APP_HANDLE with the app_handle value from your shopify.app.toml file. The target: "_top" option is required for apps with a landing page in App Home because the plan selection page is outside the app's iframe.

Anchor to Test the plan approval flowTest the plan approval flow

  1. Install your app on your development store.
  2. Confirm that your app redirects to the plan selection page.
  3. Select the SMS Pro plan and approve the charge.
  4. Verify that you're redirected to your welcome link with the plan_handle parameter.
Info

On development stores, merchants aren't actually charged. You can test the full billing flow without any real payments. If you don't want to publish a public plan yet, Shopify App Pricing includes a $0 private test plan that you can use to configure and test your meters during development.

Anchor to Step 3: Authenticate with the App Events APIStep 3: Authenticate with the App Events API

The App Events API uses JWT tokens for authentication. Generate a token using your app's client credentials from the Dev Dashboard.

When you create an API key in the Dev Dashboard, you automatically receive permissions to write to App Events. No additional configuration is required.

Use your app's client ID and client secret to request an access token:

POST

/auth/access_token

const response = await fetch("https://api.shopify.com/auth/access_token", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
client_id: "{your_client_id}",
client_secret: "{your_client_secret}",
grant_type: "client_credentials",
}),
});

const data = await response.json();

The response includes an access_token, the granted scope, and an expires_in value in seconds:

{} Response

{
"access_token": "f8563253df0bf277ec9ac6f649fc3f17",
"scope": "write_global_api_app_events",
"expires_in": 3599
}

Store this token securely in your app. You'll include it as an Authorization: Bearer header on every App Events API request. Tokens expire after 60 minutes — refresh them before they expire.

Anchor to Step 4: Send a billing event through the App Events APIStep 4: Send a billing event through the App Events API

After your app sends an SMS message for a merchant, use the App Events API to report the usage to Shopify. The event_handle must match the sms_sent meter handle you configured in Shopify App Pricing in Step 1. This is how the two systems connect — the App Events API reports the event, and Shopify App Pricing uses the matching meter to calculate the charge. To learn more about using App Events, see About App Events.

Anchor to Send a single SMS eventSend a single SMS event

async function reportSmsSent(shopId, accessToken) {
const response = await fetch(
"https://api.shopify.com/app/unstable/events",
{
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${accessToken}`,
},
body: JSON.stringify({
shop_id: shopId,
event_handle: "sms_sent",
timestamp: new Date().toISOString(),
idempotency_key: `sms_${shopId}_${Date.now()}`,
attributes: {
value: 1,
},
}),
}
);

if (!response.ok) {
console.error("Failed to report SMS event:", response.status);
}
}

Report usage promptly to ensure accurate billing data. You can queue events in your app and send them sequentially to stay within rate limits.

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.

Anchor to Understand the request fieldsUnderstand the request fields

FieldValueDescription
shop_id"gid://shopify/Shop/23423423"The Shopify shop ID of the merchant the SMS was sent for. Accepts a GID (shown) or a numeric shop ID as a string.
event_handlesms_sentMust exactly match the billing meter handle from your Shopify App Pricing configuration.
timestamp2026-01-27T14:30:00ZThe ISO 8601 time when the SMS was actually sent, not when you reported it. Must fall within the merchant's current billing cycle and can't be more than 5 minutes in the future.
idempotency_keysms_23423423_1706365800A unique key that prevents duplicate charges if you retry the request. Maximum 64 characters. Billing idempotency keys are enforced permanently.
attributes.value1The number of units to add to the meter. Must be greater than 0. Use 1 for a single SMS.

Anchor to Report batch usageReport batch usage

If your app sends multiple messages in a campaign, you can report the total in a single event:

const response = await fetch("https://api.shopify.com/app/unstable/events", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: "Bearer {access_token}",
},
body: JSON.stringify({
shop_id: "gid://shopify/Shop/23423423",
event_handle: "sms_sent",
timestamp: "2026-01-27T15:00:00Z",
idempotency_key: "sms_campaign_abc123",
attributes: {
value: 5,
},
}),
});

const data = await response.json();

Setting value: 5 adds five units to the merchant's sms_sent meter for the billing period.

Info

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. Always verify your events in the Dev Dashboard under Logs with the App Billing Event type filter.

Anchor to Step 5: Verify billing events in the Dev DashboardStep 5: Verify billing events in the Dev Dashboard

After sending billing events through the App Events API, use the Dev Dashboard to confirm that Shopify App Pricing is processing them correctly.

Anchor to View your billing eventsView your billing events

  1. Go to the Dev Dashboard and select your app.
  2. Click Logs in the sidebar.
  3. Set the Type filter to App Event to show only app events.
  4. Look for your sms_sent events in the list.

Each event displays:

  • Status: Whether the event was successfully processed (200) or failed (4xx, 5xx).
  • Event handle: The meter handle from your request (sms_sent).
  • Shop: The merchant's shop domain.
  • Timestamp: When the event was sent.

Anchor to Confirm the event is billableConfirm the event is billable

In the logs, billing events are labeled to distinguish them from custom events:

  • Billable: The App Events API matched the event to the sms_sent billing meter in Shopify App Pricing. The usage counts toward the merchant's charges.
  • Non-billable: The event was received by the App Events API but didn't match any billing meter in Shopify App Pricing.

If an event shows as non-billable, verify that the event_handle in your App Events API request exactly matches the meter handle in your Shopify App Pricing configuration. Handles are case-sensitive.

Anchor to Troubleshoot billing errorsTroubleshoot billing errors

The following errors can appear in the Dev Dashboard for billing events:

ErrorCauseSolution
NO_SUBSCRIPTIONThe merchant doesn't have an active Shopify App Pricing subscriptionConfirm the merchant installed your app and approved the pricing plan
ACCOUNT_FROZENThe partner account is frozen and can't process billable eventsContact Shopify Partner Support to resolve your account status
SUBSCRIPTION_NOT_METEREDThe Shopify App Pricing subscription doesn't include usage-based pricingVerify the merchant is on a plan that includes usage meters
INVALID_TIMESTAMPThe timestamp is missing, malformed, more than 5 minutes in the future, or falls outside the merchant's current billing cycleUse an ISO 8601 timestamp within the merchant's current billing cycle that isn't more than 5 minutes in the future
IDEMPOTENCY_KEY_ERRORThe key is missing, already used, or invalidUse a unique idempotency key for each distinct billable action
INVALID_VALUEThe value is zero, negative, or non-numericSend a value greater than 0 for the value field
MISSING_VALUE_KEYThe value key is missing from the attributesInclude "value" in the attributes object
PERIOD_CLOSEDThe billing period for this timestamp has already closed. This also occurs more than 24 hours after a merchant uninstalls your appSend events within the current billing cycle. After a merchant uninstalls, you have 24 hours to submit remaining usage
INVALID_ACCOUNTThe app or partner account isn't authorizedVerify your app credentials and partner account status

Anchor to Monitor billing healthMonitor billing health

Use the event graph in the Logs view to monitor billing event volume over time:

  • Consistent volume: Billing events should correlate with your app's SMS sending patterns.
  • Error spikes: Sudden increases in failed events might indicate a configuration issue or expired credentials.
  • Missing events: Gaps in expected billing events could mean your app isn't reporting usage correctly.

Check the Dev Dashboard regularly, especially after deploying changes to your billing integration.

Anchor to Next stepsNext steps

Was this page helpful?