Merchants can sell their products on your marketplace. Now you want to set up a billing model so that you can charge merchants a sales fee.
In this tutorial, you'll take a fixed fee for each order made in the 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.
What you'll learnAnchor link to section titled "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
RequirementsAnchor link to section titled "Requirements"
- You've completed the tutorial for storing order data.
Step 1: Set up subscription handlersAnchor link to section titled "Step 1: Set up subscription handlers"
To bill merchants for selling on your marketplace, you need to create the mutation that creates subscriptions and usage charges using the Admin API.
server/handlers/mutationscreate a file called
server/handlers/mutations/create-app-subscription.js, add a method that calls the
appSubscriptionCreatemutation 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.
server/handlers/restcreate a file called
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.
server/handlers/index.js, export the newly-created method from the handler module.
Step 2: Add a subscription confirmation URL to the internal APIAnchor link to section titled "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 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.
Create a new sequelize migration that you'll use to add
subscriptionLineItemIdcolumns to your
The command creates a new file in your app's
/migrationsfolder with following name:
Update the migration file to add the columns to your
Add the new attributes to your
Run the migration to write the changes to your database.
server/helpers.js, create a new method called
getNewSubscriptionConfirmationUrlthat creates a new app subscription, saves the details to the database, and returns a confirmation URL.
server/graphql/schema.js, create a new
AdminShopSubscriptiontype that contains fields for the confirmation URL and a Boolean to indicate whether the subscription is accepted.
server/graphql/resolvers.js, add a
subscriptionresolver to the
The resolver returns a confirmation URL for an app subscription, and whether the app subscription is accepted. Since the
adminShopresolver on the
Querytype returns the shop details from the database, you can get the
subscriptionIdfrom the first parameter.
Step 3: Add the subscription to the channel appAnchor link to section titled "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 that they can accept the subscription.
OnboardingInfoCardcomponent to include information about the billing agreement.
The onboarding information card should display information about the billing agreement. The following is an example:
app/src/sections/Onboarding/components/OnboardingChecklistCard.jsx, update the
OnboardingChecklistCardcomponent 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.
app/src/sections/Onboarding/Onboarding.jsxupdate the admin shop query to fetch the subscription details.
Onboardingcomponent to pass the subscription details from the query to the
OnboardingChecklistCardcomponent. The component should also use the
subscriptionAcceptedBoolean 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:
app/src/sections/Settings.jsx, update the query to fetch the subscription details.
Settingscomponent should pass the subscription details from the query into the
SettingsChecklistcomponent should render an item for the billing requirement.
Step 4: Bill a usage feeAnchor link to section titled "Step 4: Bill a usage fee"
After merchants have approved the subscription, you can start billing usage fees for orders placed on your marketplace.
server/handlers/mutationsadd a file called
server/handlers/mutations/create-usage-record.js, add a method that creates a usage charge using the
It should accept the
subscriptionLineItemId, which is stored in your database, and bill a $0.5 usage fee.
createUsageRecordfrom the handlers module.
handleOrderCreatefunction to get the shop’s
subscriptionLineItemIdfrom the database, and call the handler that you created.
- Share feedback on Marketplace Kit.