Implement your billing model

To create a charge using the ApplicationCharge resource:

1. 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 a confirmation_url:

   POST /admin/api/2023-01/application_charges.json

   Request:

   Response:

2. 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 from pending to active. After the charge is activated (the charge is in an active 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.

To create a charge using the RecurringApplicationCharge resource:

1. 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-01/recurring_application_charges.json

   Request:

2. 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 to active. After the charge is activated (the charge is in an active 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.

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:

1. Create a RecurringApplicationCharge that includes the capped_amount and terms properties in the body of the request. The capped_amount is the maximum dollar amount that your app can charge in a 30-day billing cycle. The terms property describes the billing conditions.

   POST /admin/api/2023-01/recurring_application_charges.json

   Request:

2. Create a new UsageCharge for each postcard:

   POST /admin/api/2023-01/recurring_application_charges/#{id}/usage_charges.json

   Request:

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.

At some point during a merchant's billing cycle, you might want to increase the capped_amount parameter.

To increase the capped amount:

1. 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 the capped_amount to $200 dollars, you would issue the following call:

   PUT /admin/api/2023-01/recurring_application_charges/#{id}/customize.json?recurring_application_charge[capped_amount]=200

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

• Refund an app payment: Learn how to respond to refund requests from merchants who use your app.