All Tutorials

Charging for your app with the REST Admin API: Implement your billing model

All Tutorials

Charging for your app with the REST Admin API: Implement your billing model

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:

  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/2021-04/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-04/charges/44433414/confirm_application_charge?signature=BAhpBAYApgI%3D--b7661dbc3eac11eaeb71b1d0e9b9bcb4b9a531ba"
        }
    }
  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.

Implement the RecurringApplicationCharge resource

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/2021-04/recurring_application_charges.json

    Request:

    {
    "recurring_application_charge": {
      "name": "Recurring charge",
      "price": 20.0,
      "return_url": "http:\/\/super-duper.shopifyapps.com"
      }
    }
  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.

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:

  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/2021-04/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 "
      }
    }
  2. Create a new UsageCharge for each postcard:

    POST /admin/api/2021-04/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:

  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/2021-04/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.

Next steps