Charging for your app with the REST Admin API: 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
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/2021-01/application_charges.json
Request:
{ "application_charge": { "name": "App charge", "price": 100.0, "return_url": "http:\/\/super-duper.shopifyapps.com" } }
Response:
{ "application_charge": { "id": 44433414, "name": "App charge", "api_client_id": 1968176, "price": "100.00", "status": "pending", "return_url": "http://super-duper.shopifyapps.com/", "test": true, "created_at": "2018-02-09T14:04:54-05:00", "updated_at": "2018-02-09T14:04:54-05:00", "charge_type": null, "decorated_return_url": "http://super-duper.shopifyapps.com/?charge_id=44433414", "confirmation_url": "https://{shop}.myshopify.com/admin/api/2021-01/charges/44433414/confirm_application_charge?signature=BAhpBAYApgI%3D--b7661dbc3eac11eaeb71b1d0e9b9bcb4b9a531ba" } }
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
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/2021-01/recurring_application_charges.json
Request:
{ "recurring_application_charge": { "name": "Recurring charge", "price": 20.0, "return_url": "http:\/\/super-duper.shopifyapps.com" } }
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
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/2021-01/recurring_application_charges.json
Request:
{ "recurring_application_charge": { "name": "Postcards", "price": 20.0, "return_url": "http:\/\/super-duper.shopifyapps.com", "capped_amount": 100, "terms": "100 Postcards for high order value customers " } }
Create a new UsageCharge for each postcard:
POST
/admin/api/2021-01/recurring_application_charges/#{id}/usage_charges.json
Request:
{ "usage_charge": { "description": "Postcard for high order value customer", "price": 1.0 } }
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
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/2021-01/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.
Next steps
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.
Refund an app payment: Learn how to respond to refund requests from merchants who use your app.