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

On this page

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/2020-01/application_charges.json

    Request body:

    {
  "application_charge": {
    "name": "App charge",
    "price": 100.0,
    "return_url": "http:\/\/super-duper.shopifyapps.com"
  }
}

    Response from Shopify:

    {
    "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/2020-01/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 user accepts the charge they are sent to a return_url that you specify. The decorated_return_url property contains the charge_id that you'll need to activate the charge. If the status property is set to accepted, then you can activate the charge. If the charge is declined, then Shopify redirects the merchant and provides a notification message that the app charge was declined.

  3. To activate the charge, send a POST request to the application charge activate endpoint using the charge_id returned by Shopify:

    POST /admin/api/2020-01/application_charges/{charge_id}/activate.json

    Request body:

    {
  "application_charge": {
    "id": 675931192,
    "name": "iPod Cleaning",
    "api_client_id": 755357713,
    "price": "5.00",
    "status": "accepted",
    "return_url": "http:\/\/google.com",
    "created_at": "2017-07-19T12:24:00-04:00",
    "updated_at": "2017-07-19T12:24:00-04:00",
    "test": null,
    "charge_type": null,
    "decorated_return_url": "http:\/\/google.com?charge_id=675931192"
  }
}

    In response, Shopify returns the ApplicationCharge object with status set to active.

After the charge is activated, you'll get paid. Shop owners are charged immediately upon accepting an application charge, but you'll still need to activate the charge to get paid.

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

    Request body:

    {
"recurring_application_charge": {
  "name": "Recurring charge",
  "price": 20.0,
  "return_url": "http:\/\/super-duper.shopifyapps.com"
  }
}

    In the response, the decorated_return_url property contains the charge_id that you need to use to activate the charge.

  2. Redirect the merchant to the confirmation_url to accept or decline the charge. If the charge is declined, then Shopify redirects the merchant and provides a notification message that the app charge was declined.

  3. To activate the charge, send a POST request to the recurring application charge activate endpoint using the charge_id returned by Shopify.

    POST /admin/api/2020-01/recurring_application_charges/{charge_id}/activate.json

    Request body:

    {
"recurring_application_charge": {
    "id": 2575433784,
    "name": "Recurring charge",
    "api_client_id": 1424810,
    "price": "20.00",
    "status": "accepted",
    "return_url": "http://super-duper.shopifyapps.com/",
    "billing_on": null,
    "created_at": "2018-04-30T15:04:02-04:00",
    "updated_at": "2018-04-30T15:09:14-04:00",
    "test": true,
    "activated_on": null,
    "trial_ends_on": null,
    "cancelled_on": null,
    "trial_days": 0,
    "decorated_return_url": "http://super-duper.shopifyapps.com/?charge_id=2575433784"
  }
}

If you don't activate the charge, then the charge does not appear on the store owner's invoice, and you won't be paid.

Implementing the UsageCharge resource

Every UsageCharge is a child of a RecurringApplicationCharge resource. After you've created and activated a RecurringApplicationCharge that includes the necessary properties, you can create usage charges associated with it.

For example, imagine you'd like to implement a billing model for an app that sends postcards to customers with high order values; you'd like to bill merchants every time a card is sent out.

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; terms describes the billing conditions:

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

    Request body:

    {
  "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/2020-01/recurring_application_charges/#{id}/usage_charges.json

    Request body:

    {
  "usage_charge": {
    "description": "Postcard for high order value customer",
    "price": 1.0
  }
}

Charging variable fees only

To charge variable fees only, you can set the RecurringApplicationCharge price to 0.00. Then you can issue usage charges to charge only on a per-use basis.

Increasing 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 will include the update_capped_amount_url parameter. By way of example, to increase the capped_amount to $200 dollars, you would issue the following call:

    PUT /admin/api/2020-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.