UsageCharge

You can use the UsageCharge resource to add variable usage fees to an existing recurring application charge. 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 recurring application charge. 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 recurring application charge.

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

Charging for usage only

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

Setting capped amounts

You can 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 recurring application charge with the capped dollar amount, and then create the associated usage charge.

Note

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

For step-by-step guidance that walks through this flow using examples, see our implementation guide.

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 (ISO 8601 format) when the usage charge was created.

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

The name of the usage charge.

id
"id": 675931192

The ID of the usage charge.

price
"price": 1

The price of the usage charge.

recurring_application_charge_id
"recurring_application_charge_id": 527669426

The ID of the recurring application charge that the usage charge belongs to.

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

The date and time (ISO 8601 format) when the usage charge was last updated.

Endpoints

POST /admin/recurring_application_charges/455696195/usage_charges.json
Creates a usage charge

Create a new usage charge

POST /admin/recurring_application_charges/#{recurring_application_charge_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": "2018-07-05T13:05:43-04:00",
    "billing_on": "2018-08-04",
    "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/#{recurring_application_charge_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
Retrieves a single charge
fields

A comma-separated list of fields to include in the response.

Retrieve a single charge

GET /admin/recurring_application_charges/#{recurring_application_charge_id}/usage_charges/#{usage_charge_id}.json
View Response
HTTP/1.1 200 OK
{
  "usage_charge": {
    "id": 1034618210,
    "description": "Super Mega Plan Add-ons",
    "price": "10.00",
    "created_at": "2018-07-05T13:05:45-04:00",
    "billing_on": "2018-08-04",
    "balance_used": 10.0,
    "balance_remaining": 90.0,
    "risk_level": 0.075
  }
}
GET /admin/recurring_application_charges/455696195/usage_charges.json
Retrieves a list of usage charges
fields

A comma-separated list of fields to include in the response.

Retrieve all usage charges

GET /admin/recurring_application_charges/#{recurring_application_charge_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": "2018-07-05T13:05:46-04:00",
      "billing_on": "2018-08-04",
      "balance_used": 10.0,
      "balance_remaining": 90.0,
      "risk_level": 0.075
    }
  ]
}

Sign up for a Partner account to get started.

Sign up