Billing merchants

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

• You've completed the tutorial for storing order data.

To bill merchants for selling on your marketplace, you need to create the mutation 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 the subscription's created using the GraphQL Admin API mutation.

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

In the channel app, you need to redirect merchants to the subscription confirmation page so that 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, then you can create a new subscription.

You'll need to update the Shop data model to store the subscription ID and line item ID, which you can subsequently use to bill merchants usage charges.

1. Create a new sequelize migration that you'll use to add subscriptionId and subscriptionLineItemId columns to your Shop data model.

   The command creates a new file in your app's /migrations folder with following name: {TIMESTAMP}-add-shop-subscription-info.js

2. Update the migration file to add the columns to your Shops data table.

3. Add the new attributes to your Shop data model.

4. Run the migration to write the changes to your database.

5. In server/helpers.js, create a new method called getNewSubscriptionConfirmationUrl that creates a new app subscription, saves the details to the database, and returns a confirmation URL.

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

7. In server/graphql/resolvers.js, add a subscription resolver to the AdminShop type.

   The resolver 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, you can get the subscriptionId from the first parameter.

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 that they can accept the subscription.

1. In app/src/sections/Onboarding/components/OnboardingInfoCard.jsx update the OnboardingInfoCard component to include information about the billing agreement.

   The onboarding information card should display information about the billing agreement. The following is an example:

   

2. In app/src/sections/Onboarding/components/OnboardingChecklistCard.jsx, update the OnboardingChecklistCard component to accept props for the subscription confirmation URL and whether the subscription is accepted.

   The component should render an item for the subscription agreement, which redirects to the confirmation URL on action.

3. In app/src/sections/Onboarding/Onboarding.jsx update the admin shop query to fetch the subscription details.

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

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

   

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

   

4. In app/src/sections/Settings.jsx, update the query to fetch the subscription details.

   The Settings component should pass the subscription details from the query into the SettingsChecklist component. The SettingsChecklist component should render an item for the billing requirement.

   

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.

• Share feedback on Marketplace Kit.