Implement your billing model
You can implement your billing model using the ApplicationCharge, RecurringApplicationCharge, and UsageCharge resources. To use any of these resources, you'll also need to implement a merchant trigger for the charge, such as app installation, service plan upgrade, or individual purchase.
Implement the ApplicationCharge resource
Anchor link to section titled "Implement the ApplicationCharge resource"To create a charge using the ApplicationCharge
resource:
Create a new ApplicationCharge. Make sure to include the
return_url
, where the merchant is redirected after accepting the charge. Shopify verifies the charge and returns aconfirmation_url
:POST
/admin/api/2023-04/application_charges.json
Request:
Response:
Redirect the merchant to the
confirmation_url
to accept or decline the charge.When a merchant accepts the charge, they're sent to a
return_url
that you specify. The charge immediately transitions frompending
toactive
. After the charge is activated (the charge is in anactive
state), you get paid.If the charge is declined, then Shopify redirects the merchant and provides a notification message that the app charge was declined.
Implement the RecurringApplicationCharge resource
Anchor link to section titled "Implement the RecurringApplicationCharge resource"To create a charge using the RecurringApplicationCharge
resource:
Create a new RecurringApplicationCharge, including the
return_url
as in ApplicationCharge above. Send a recurring application charge in the body of the request:POST
/admin/api/2023-04/recurring_application_charges.json
Request:
Redirect the merchant to the
confirmation_url
to accept or decline the charge.When a merchant accepts a charge, the charge immediately transitions from
pending
toactive
. After the charge is activated (the charge is in anactive
state), you get paid.If the charge is declined, then Shopify redirects the merchant and provides a notification message that the app charge was declined.
Implement the UsageCharge resource
Anchor link to section titled "Implement the UsageCharge resource"Every UsageCharge is a child of a RecurringApplicationCharge
resource. After you've created a RecurringApplicationCharge
that includes the necessary properties, you can create usage charges associated with it.
For example, you might want to implement a billing model for an app that sends postcards to customers with high order values. You could charge the merchant each time you send a card to one of their customers.
To implement the UsageCharge
resource:
Create a RecurringApplicationCharge that includes the
capped_amount
andterms
properties in the body of the request. Thecapped_amount
is the maximum dollar amount that your app can charge in a 30-day billing cycle. Theterms
property describes the billing conditions.POST
/admin/api/2023-04/recurring_application_charges.json
Request:
Create a new UsageCharge for each postcard:
POST
/admin/api/2023-04/recurring_application_charges/#{id}/usage_charges.json
Request:
Charge variable fees only
Anchor link to section titled "Charge variable fees only"To charge variable fees only, set the RecurringApplicationCharge price
to 0.00
. You can then issue usage charges to charge only on a per-use basis.
Increase the capped amount
Anchor link to section titled "Increase the capped amount"At some point during a merchant's billing cycle, you might want to increase the capped_amount
parameter.
To increase the capped amount:
Send a request to Shopify that specifies the increased amount. The response from Shopify includes the
update_capped_amount_url
parameter. For example, to increase thecapped_amount
to $200 dollars, you would issue the following call:PUT
/admin/api/2023-04/recurring_application_charges/#{id}/customize.json?recurring_application_charge[capped_amount]=200
Redirect the merchant to the
update_capped_amount_url
to approve the increased amount.Until the merchant approves the increase, the
capped_amount
remains at its previous value.
Upgrades and downgrades: Learn how to upgrade or downgrade a merchant's plan.
Offering free trials: Learn about the best way to manage free trials for your app.