UsageCharge

Usage charges are part of Shopify's application billing API. The usage_charge endpoint allows your apps to charge a variable monthly fee for an app or a service. You should use this API to charge merchants for your product when the fees are recurring, but vary from month to month.

You can find general information about Shopify's billing APIs here:

Reminder

Test or demo shops may not be charged.

What can you 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": 1034618207,
    "description": "Super Mega Plan 1000 emails",
    "price": "1.00",
    "billing_on": "2016-06-20",
    "balance_used": 11.0,
    "balance_remaining": 89.0,
    "risk_level": 0.0
  }
}

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/1034618208.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": 1034618208,
    "description": "Super Mega Plan Add-ons",
    "price": "10.00",
    "billing_on": "2016-06-20",
    "balance_used": 10.0,
    "balance_remaining": 90.0,
    "risk_level": 0.0
  }
}
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": 1034618209,
      "description": "Super Mega Plan Add-ons",
      "price": "10.00",
      "billing_on": "2016-06-20",
      "balance_used": 10.0,
      "balance_remaining": 90.0,
      "risk_level": 0.0
    }
  ]
}