UsageCharge

You can use the UsageCharge resource to add variable usage fees to an existing RecurringApplicationCharge. You can use these resources to support billing plans that vary from month to month, with or without a monthly recurring fee.

Creating usage charges

To use the UsageCharge resource, first create a RecurringApplicationCharge. This returns the id that you'll need to create an associated usage charge.

To create the usage charge, send a POST request, where {id} represents the id of the previously created RecurringApplicationCharge.

POST /admin/recurring_application_charges/{id}]/usage_charges.json

Charging for usage only

A common billing scenario is to only charge usage-based fees, without a flat recurring monthly fee. To only charge usage-based fees, without a recurring monthly fee, first create a RecurringApplicationCharge with price set to $0.00, and then apply the usage charge.

Setting capped amounts

You use the RecurringApplicationCharge resource to specify a capped amount that applies to usage-based billing. This prevents the customer from being charged for any usage over and above the capped amount. To implement capped amount billing, create a RecurringApplicationCharge with the capped dollar amount, and then create the associated usage charge.

Note

Capped amount is applicable on a per billing cycle basis (30 days), and remains in effect unless updated.

For more information, see the Usage app charges guide and the RecurringApplicationCharge API reference.

What you can do with UsageCharge

The Shopify API lets you do the following with the UsageCharge resource. More detailed versions of these general actions may be available:

UsageCharge properties

created_at
"created_at": "2013-06-27T08:48:27-04:00"

The date and time when the usage charge was created. The API returns this value in ISO 8601 format.

description
"description": "Super Mega Plan 1000 emails"

The name of the usage charge.

id
"id": 675931192

A unique numeric identifier for the usage charge.

price
"price": 1

The price of the usage charge.

recurring_application_charge_id
"recurring_application_charge_id": 527669426

The recurring application charge the usage charge belongs to.

updated_at
"updated_at": "2013-06-27T08:48:27-04:00"

The date and time when the usage charge was last updated. The API returns this value in ISO 8601 format.

Endpoints

POST /admin/recurring_application_charges/455696195/usage_charges.json

Create a new charge called 'Super Mega Plan 1000 emails' for $1.00 USD

POST /admin/recurring_application_charges/#{id}/usage_charges.json
{
  "usage_charge": {
    "description": "Super Mega Plan 1000 emails",
    "price": 1.0
  }
}
View Response
HTTP/1.1 201 Created
{
  "usage_charge": {
    "id": 1034618208,
    "description": "Super Mega Plan 1000 emails",
    "price": "1.00",
    "created_at": "2017-11-09T13:20:46-05:00",
    "billing_on": "2017-12-09",
    "balance_used": 11.0,
    "balance_remaining": 89.0,
    "risk_level": 0.08
  }
}

Trying to create a charge without a price and description will return an error

POST /admin/recurring_application_charges/#{id}/usage_charges.json
{
  "usage_charge": {
    "description": ""
  }
}
View Response
HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "description": [
      "can't be blank"
    ],
    "price": [
      "can't be blank"
    ]
  }
}
GET /admin/recurring_application_charges/455696195/usage_charges/1034618210.json
fields

comma-separated list of fields to include in the response

Retrieve a single charge

GET /admin/recurring_application_charges/#{id}/usage_charges/#{id}.json
View Response
HTTP/1.1 200 OK
{
  "usage_charge": {
    "id": 1034618210,
    "description": "Super Mega Plan Add-ons",
    "price": "10.00",
    "created_at": "2017-11-09T13:20:48-05:00",
    "billing_on": "2017-12-09",
    "balance_used": 10.0,
    "balance_remaining": 90.0,
    "risk_level": 0.075
  }
}
GET /admin/recurring_application_charges/455696195/usage_charges.json
All past and present usage charges requests are retrieved by this request.
fields

comma-separated list of fields to include in the response

Retrieving all usage charges

GET /admin/recurring_application_charges/#{id}/usage_charges.json
View Response
HTTP/1.1 200 OK
{
  "usage_charges": [
    {
      "id": 1034618211,
      "description": "Super Mega Plan Add-ons",
      "price": "10.00",
      "created_at": "2017-11-09T13:20:48-05:00",
      "billing_on": "2017-12-09",
      "balance_used": 10.0,
      "balance_remaining": 90.0,
      "risk_level": 0.075
    }
  ]
}