Billing API Set-up for recurring take rate fees

Retired Boards Appdev Billing

Topic summary

A merchant wants to set up 3 billing plans combining a fixed monthly SaaS fee with a percentage-based take rate on GMV (Gross Merchandise Value) generated through their app.

Recommended Approach:

  • Use Shopify’s UsageCharges API (specifically appUsageRecordCreate mutation) to implement the percentage-based GMV component
  • The app developer is responsible for calculating the usage charge amount (GMV × percentage)

Key Technical Details:

  • The price field accepts MoneyInput type, allowing decimal/fractional amounts (not restricted to integers)
  • Amounts should be specified in decimal format

Next Steps:

  • Review Shopify’s tutorial on creating usage-based billing plans for implementation guidance
  • Test the setup across all 3 planned tiers

The discussion confirms this is the standard method for implementing variable pricing tied to merchant performance metrics.

Summarized with AI on November 18. AI used: claude-sonnet-4-5-20250929.
1

We have 3 plans we want to set up - each with the same structure.

Monthly SaaS $ + % of attributable GMV for the App

How should we go about setting that up and testing it.

We found a reference to the following:
"“After creating a recurring application charge that’s required for usage charge recurring_application_charge_id (and/or capped charge amounts) you can create usage charges as a percentage of sales. The price field on UsageCharge is not an integer as suggested in the property doc of the API i.e. you can use fractional amounts as with any other price / money fields.”

Is this the recommended approach or is there a better approach?

2

Hi there :waving_hand:

Using UsageCharges is how you would be able to charge merchants based off something like GMV attributable to your application. You will be responsible for determining what the amount you will be charging in the usage charge, i.e. you will be responsible for determining (% * GMV).

You are correct the price field is of type MoneyInput which allows you to specify the amount in decimal form.

If you haven’t already you can review this tutorial on creating usage based billing plans.