Bill merchants

Merchants can sell their products on your marketplace. Now you want to set up a billing model so that you can charge a fee for selling on your marketplace.

In this tutorial, you'll take a fixed fee per order from your marketplace. You'll use a capped amount of $20 and charge a $0.5 fee for each order. This provides an approachable billing structure for merchants. It's similar to a monthly subscription of $20, but the merchant doesn’t pay unless your marketplace has provided them with orders.

A gif of the channel app onboarding flow with a billing agreement

What you'll learn

After finishing this tutorial, you'll know how to do the following:

  • Create a usage plan for billing merchants who make sales on your marketplace

  • Add a monthly subscription plan for the marketplace

  • Bill merchants a usage fee


Step 1: Set up subscription handlers

To bill merchants for selling on your marketplace, you need to create the mutations that creates subscriptions and usage charges using the Admin API.

  1. In server/handlers/mutations create a file called create-app-subscription.js.

  2. In server/handlers/mutations/create-app-subscription.js, add a method that calls the appSubscriptionCreate mutation and creates a subscription with a usage pricing plan.

    The plan requires terms that tell merchants how you will be billing them, as well as a capped amount which is the maximum amount that you can charge the merchant per month. It also requires a return URL, which redirects the merchant back to your app after accepting the subscription in the Shopify admin. The method should return the subscription ID, confirmation URL, and line item ID.

  3. In server/handlers/rest create a file called get-app-subscription.js.

  4. In server/handlers/rest/get-app-subscription.js, export a method that gets the recurring application charge information given a subscription ID.

    You can use this to get the app subscription details after it's created using the mutations that you created.

  5. In server/handlers/index.js, export the newly-created method from the handler module.

Step 2: Add a subscription confirmation URL to the internal API

In the channel app, you need to redirect merchants to the subscription confirmation page so they can accept the subscription.

The confirmation URL is returned when you create the subscription, and expires after two days if the merchant has not approved the subscription. You can check the status of the confirmation URL by fetching the app subscription status. If it's stale, you can create a new subscription.

  1. Update the shop data model to store the subscription related information.

    You should add new subscriptionId and subscriptionLineItemId string attributes to your data model. These attributes store a reference to the subscription and the line item, which you can subsequently use to bill usage charges.

  2. In server/helpers.js create a new method called getNewSubscriptionConfirmationUrl which will create a new app subscription, save the details to the database, and return the confirmation url.

  3. In server/graphql/schema.js create a new AdminShopSubscription type that contains fields for the confirmation URL and a Boolean to indicate whether the subscription is accepted.

  4. In server/graphql/resolvers.js add a subscription resolver to the AdminShop type, which returns a confirmation URL for an app subscription, and whether the app subscription is accepted.

    Since the adminShop resolver on the Query type returns the shop details from the database, it can access the subscription ID from the first parameter.

Step 3: Add the subscription to the channel app

You can update the merchant onboarding page to surface information about the billing agreement that you added to the internal GraphQL API.

If the subscription is accepted, then mark the item in the onboarding checklist as completed. Otherwise, you'll redirect the merchant to the subscriptionConfirmationUrl so they can accept the subscription.

  1. In adminComponents/checklist.js update the Checklist component to include an item for the subscription agreement, which redirects to the confirmation URL on action.

  2. In pages/admin/onboarding.js update the OnboardingInfoCard to contain information about the billing agreement.

    The onboarding information card should display information about the billing agreement.

    An image of the onboarding information card that shows billing agreement information

  3. In pages/admin/onboarding.js update the OnboardingChecklistCard component to accept props for the subscription confirmation URL and whether the subscription is accepted, passing them through to the Checklist component.

  4. Update the admin shop query to fetch the subscription details.

    The Onboarding component should pass the subscription details from the query into the OnboardingChecklistCard component. It should also use the subscription accepted Boolean to determine whether the shop meets marketplace requirements.

    The onboarding page checklist should now include an item for the subscription billing agreement:

    An image of the onboarding requirements checkist that shows an item for the subscription billing agreement

    Clicking on the billing agreement requirement link should redirect to a subscription approval page:

    An image of the subscription approval page

  5. In pages/admin/settings.js update the query to fetch the subscription details.

    The Settings component should pass the subscription details from the query into the Checklist component.

    An image of the settings page with a requirements checkist that shows a completed item for the subscription billing agreement

Step 4: Bill usage fee when orders are created

After merchants have approved the subscription, you can start billing usage fees for orders placed on your marketplace.

  1. In server/handlers/mutations add a file called create-usage-record.js.

  2. In server/handlers/mutations/create-usage-record.js, add a method that creates a usage charge using the appUsageRecordCreate mutation.

    It should accept the subscriptionLineItemId, which is stored in your database, and bill a $0.5 usage fee.

  3. In server/handlers/index.js export createUsageRecord from the handlers module.

  4. In server/handlers/webhooks/orders.js update the handleOrderCreate function to get the shop’s subscriptionLineItemId from the database, and call the handler that you created.