RecurringApplicationCharge

Request to charge a shop a recurring fee (every 30 days) by issuing this call with the name the charge should appear under (on the shop owner’s invoice), the price your application is charging, and a return_url to where Shopify will redirect the shop owner to after they have accepted or declined the charge.

Setting the test flag to true will set the RecurringApplicationCharge to not actually charge the credit card it otherwise would.

After this request returns, an RecurringApplicationCharge has been created, but is held in a pending state until the shop owner has accepted or declined it.

Proceed by redirecting the shop owner to the confirmation_url set in the response where they may accept or decline the charge.

After the charge has been accepted or declined, Shopify redirects the shop owner to the return_url set in the request. At this point the shop is either in an accepted or declined state. In order to actually receive payment for this charge it must be activated by your application.

Updating

Each shop may have only one recurring charge per application.

When a new RecurringApplicationCharge is activated for a shop that already has a recurring charge for that application, the existing recurring charge will be cancelled and replaced by the new charge. The new recurring charge will then activate.

This means that upgrading and downgrading a user’s recurring charge or plan is straightforward; just change their plan, have them accept, and Shopify takes care of the rest.

Reminder

Test or demo shops may not be charged.

What can you do with RecurringApplicationCharge?

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

RecurringApplicationCharge Properties

activated_on
{ "activated_on" : null }

The date and time when the customer activated the recurring application charge. The API returns this value in ISO 8601 format.
Note: The recurring application charge must be activated or the returning value will be "null".

billing_on
{ "billing_on" : null }

The date and time when the customer will be billed. The API returns this value in ISO 8601 format.
Note: The recurring application charge must be accepted or the returning value will be "null".

cancelled_on
{ "cancelled_on" : null }

The date and time when the customer cancelled their recurring application charge. The API returns this value in ISO 8601 format.
Note: If the recurring application charge is not cancelled it will default to "null".

capped_amount
{ "capped_amount" : "100" }

The capped amount is the limit a customer can be charged for usage based billing. Please see usage charges for more information.

confirmation_url
{ "confirmation_url" : "https://apple.myshopify.com/admin/charges/confirm_recurring_application_charge?id=654381177&signature=BAhpBHkQASc%3D--374c02da2ea0371b23f40781b8a6d5f4a520e77b" }

The URL that the customer is taken to, to accept or decline the recurring application charge.

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

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

id
{ "id" : 675931192 }

A unique numeric identifier for the recurring application charge.

name
{ "name" : "Super Duper Expensive action" }

The name of the recurring application charge.

price
{ "price" : "100.00" }

The price of the recurring application charge.

return_url
{ "return_url" : "http://super-duper.shopifyapps.com" }

The URL the customer is sent to once they accept/decline a charge.

status
{ "status" : "accepted" }

The status of the recurring charge. Valid values are:

  • pending: The recurring charge is pending.
  • accepted: The recurring charge has been accepted.
  • active: The recurring charge is activated. This is the only status that actually causes a merchant to be charged. An accepted charge is transitioned to active via the activate endpoint.
  • declined: The recurring charge has been declined.
  • expired: The recurring charge was not accepted within 2 days of being created.

terms
{ "terms" : "$1 for 1000 emails" }

States the terms and conditions of usage based billing charges. Must be present in order to create usage charges. These are presented to the merchant when they approve the usage charges for your app.

test
{ "test" : null }

States whether or not the application charge is a test transaction. Valid values are "true" or "null".

trial_days
{ "trial_days" : 0 }

Number of days that the customer is eligible for a free trial.

trial_ends_on
{ "trial_ends_on" : null }

The date and time when the free trial ends. The API returns this value in ISO 8601 format.

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

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

Endpoints

POST/admin/recurring_application_charges.json

Create a new charge with terms and a capped amount

POST /admin/recurring_application_charges.json
{
  "recurring_application_charge": {
    "name": "Super Duper Plan",
    "price": 10.0,
    "return_url": "http:\/\/super-duper.shopifyapps.com",
    "capped_amount": 100,
    "terms": "$1 for 1000 emails"
  }
}
View Response
HTTP/1.1 201 Created
{
  "recurring_application_charge": {
    "id": 1029266956,
    "name": "Super Duper Plan",
    "api_client_id": 755357713,
    "price": "10.00",
    "status": "pending",
    "return_url": "http:\/\/super-duper.shopifyapps.com\/",
    "billing_on": null,
    "created_at": "2016-07-27T16:50:39-04:00",
    "updated_at": "2016-07-27T16:50:39-04:00",
    "test": null,
    "activated_on": null,
    "trial_ends_on": null,
    "cancelled_on": null,
    "trial_days": 0,
    "capped_amount": "100.00",
    "balance_used": 0.0,
    "balance_remaining": 100.0,
    "risk_level": 0.0,
    "decorated_return_url": "http:\/\/super-duper.shopifyapps.com\/?charge_id=1029266956",
    "confirmation_url": "https:\/\/apple.myshopify.com\/admin\/charges\/1029266956\/confirm_recurring_application_charge?signature=BAhpBAxeWT0%3D--9f0cb58720b2c93e16684f3f48889d170a02c925"
  }
}

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

POST /admin/recurring_application_charges.json
{
  "recurring_application_charge": {
    "name": ""
  }
}
View Response
HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "price": [
      "must be greater than zero"
    ],
    "name": [
      "can't be blank"
    ]
  }
}

Create a recurring test charge that will not cause a credit card to be charged

POST /admin/recurring_application_charges.json
{
  "recurring_application_charge": {
    "name": "Super Duper Plan",
    "price": 10.0,
    "return_url": "http:\/\/super-duper.shopifyapps.com",
    "test": true
  }
}
View Response
HTTP/1.1 201 Created
{
  "recurring_application_charge": {
    "id": 1029266958,
    "name": "Super Duper Plan",
    "api_client_id": 755357713,
    "price": "10.00",
    "status": "pending",
    "return_url": "http:\/\/super-duper.shopifyapps.com\/",
    "billing_on": null,
    "created_at": "2016-07-27T16:50:40-04:00",
    "updated_at": "2016-07-27T16:50:40-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=1029266958",
    "confirmation_url": "https:\/\/apple.myshopify.com\/admin\/charges\/1029266958\/confirm_recurring_application_charge?signature=BAhpBA5eWT0%3D--62e654618d90d1e2ca83c685c373b8f51c1f0b03"
  }
}

Create a new charge called 'Super Duper Plan' for $10.00 USD per month

POST /admin/recurring_application_charges.json
{
  "recurring_application_charge": {
    "name": "Super Duper Plan",
    "price": 10.0,
    "return_url": "http:\/\/super-duper.shopifyapps.com"
  }
}
View Response
HTTP/1.1 201 Created
{
  "recurring_application_charge": {
    "id": 1029266960,
    "name": "Super Duper Plan",
    "api_client_id": 755357713,
    "price": "10.00",
    "status": "pending",
    "return_url": "http:\/\/super-duper.shopifyapps.com\/",
    "billing_on": null,
    "created_at": "2016-07-27T16:50:42-04:00",
    "updated_at": "2016-07-27T16:50:42-04:00",
    "test": null,
    "activated_on": null,
    "trial_ends_on": null,
    "cancelled_on": null,
    "trial_days": 0,
    "decorated_return_url": "http:\/\/super-duper.shopifyapps.com\/?charge_id=1029266960",
    "confirmation_url": "https:\/\/apple.myshopify.com\/admin\/charges\/1029266960\/confirm_recurring_application_charge?signature=BAhpBBBeWT0%3D--3160fa927a1c6e3c9f42fbe9edafbe6ebf189ae4"
  }
}

Create a new charge with a trial period. The trial period will go into effect at the time the recurring charge is activated.

POST /admin/recurring_application_charges.json
{
  "recurring_application_charge": {
    "name": "Super Duper Plan",
    "price": 10.0,
    "return_url": "http:\/\/super-duper.shopifyapps.com",
    "trial_days": 5
  }
}
View Response
HTTP/1.1 201 Created
{
  "recurring_application_charge": {
    "id": 1029266962,
    "name": "Super Duper Plan",
    "api_client_id": 755357713,
    "price": "10.00",
    "status": "pending",
    "return_url": "http:\/\/super-duper.shopifyapps.com\/",
    "billing_on": null,
    "created_at": "2016-07-27T16:50:43-04:00",
    "updated_at": "2016-07-27T16:50:43-04:00",
    "test": null,
    "activated_on": null,
    "trial_ends_on": null,
    "cancelled_on": null,
    "trial_days": 5,
    "decorated_return_url": "http:\/\/super-duper.shopifyapps.com\/?charge_id=1029266962",
    "confirmation_url": "https:\/\/apple.myshopify.com\/admin\/charges\/1029266962\/confirm_recurring_application_charge?signature=BAhpBBJeWT0%3D--1b74dfe4e9aa19fd8da9fffb5161af772576d673"
  }
}
GET/admin/recurring_application_charges/455696195.json
fields

comma-separated list of fields to include in the response

Retrieve a single charge

GET /admin/recurring_application_charges/#{id}.json
View Response
HTTP/1.1 200 OK
{
  "recurring_application_charge": {
    "id": 455696195,
    "name": "Super Mega Plan",
    "api_client_id": 755357713,
    "price": "15.00",
    "status": "pending",
    "return_url": "http:\/\/yourapp.com",
    "billing_on": "2016-07-27",
    "created_at": "2016-07-27T16:49:16-04:00",
    "updated_at": "2016-07-27T16:49:16-04:00",
    "test": null,
    "activated_on": null,
    "trial_ends_on": null,
    "cancelled_on": null,
    "trial_days": 0,
    "decorated_return_url": "http:\/\/yourapp.com?charge_id=455696195",
    "confirmation_url": "https:\/\/apple.myshopify.com\/admin\/charges\/455696195\/confirm_recurring_application_charge?signature=BAhpBENfKRs%3D--a911ece9470850c96f6c7735c684b8a3f6869594"
  }
}
GET/admin/recurring_application_charges.json

All past and present recurring charge requests are retrieved by this request.

since_id

Restrict results to after the specified ID

fields

comma-separated list of fields to include in the response

Retrieving all recurring charges since a specified ID

GET /admin/recurring_application_charges.json?since_id=455696195
View Response
HTTP/1.1 200 OK
{
  "recurring_application_charges": [
    {
      "id": 1029266955,
      "name": "Super Duper Plan",
      "api_client_id": 755357713,
      "price": "10.00",
      "status": "pending",
      "return_url": "http:\/\/super-duper.shopifyapps.com\/",
      "billing_on": null,
      "created_at": "2016-07-27T16:50:38-04:00",
      "updated_at": "2016-07-27T16:50:38-04:00",
      "test": null,
      "activated_on": null,
      "trial_ends_on": null,
      "cancelled_on": null,
      "trial_days": 0,
      "decorated_return_url": "http:\/\/super-duper.shopifyapps.com\/?charge_id=1029266955",
      "confirmation_url": "https:\/\/apple.myshopify.com\/admin\/charges\/1029266955\/confirm_recurring_application_charge?signature=BAhpBAteWT0%3D--b6039e1a027c1340bafaf79b10915ebad89f4771"
    }
  ]
}

Retrieving all recurring charges

GET /admin/recurring_application_charges.json
View Response
HTTP/1.1 200 OK
{
  "recurring_application_charges": [
    {
      "id": 455696195,
      "name": "Super Mega Plan",
      "api_client_id": 755357713,
      "price": "15.00",
      "status": "accepted",
      "return_url": "http:\/\/yourapp.com",
      "billing_on": "2016-07-27",
      "created_at": "2016-07-27T16:49:16-04:00",
      "updated_at": "2016-07-27T16:50:41-04:00",
      "test": null,
      "activated_on": null,
      "trial_ends_on": null,
      "cancelled_on": null,
      "trial_days": 0,
      "decorated_return_url": "http:\/\/yourapp.com?charge_id=455696195"
    }
  ]
}
POST/admin/recurring_application_charges/455696195/activate.json

Activate a previously accepted recurring application charge.

Activate a recurring charge

POST /admin/recurring_application_charges/#{id}/activate.json
{
  "recurring_application_charge": {
    "id": 455696195,
    "name": "Super Mega Plan",
    "api_client_id": 755357713,
    "price": "15.00",
    "status": "accepted",
    "return_url": "http:\/\/yourapp.com",
    "billing_on": "2016-07-27",
    "created_at": "2016-07-27T16:49:16-04:00",
    "updated_at": "2016-07-27T16:50:42-04:00",
    "test": null,
    "activated_on": null,
    "trial_ends_on": null,
    "cancelled_on": null,
    "trial_days": 0,
    "decorated_return_url": "http:\/\/yourapp.com?charge_id=455696195"
  }
}
View Response
HTTP/1.1 200 OK
{
  "recurring_application_charge": {
    "id": 455696195,
    "name": "Super Mega Plan",
    "api_client_id": 755357713,
    "price": "15.00",
    "status": "active",
    "return_url": "http:\/\/yourapp.com",
    "billing_on": "2016-07-27",
    "created_at": "2016-07-27T16:49:16-04:00",
    "updated_at": "2016-07-27T16:50:42-04:00",
    "test": null,
    "activated_on": "2016-07-27",
    "trial_ends_on": "2016-07-27",
    "cancelled_on": null,
    "trial_days": 0,
    "decorated_return_url": "http:\/\/yourapp.com?charge_id=455696195"
  }
}
DELETE/admin/recurring_application_charges/455696195.json

Errata

Cancelled plans are not pro-rated.

Cancel the current recurring charge for a shop

DELETE /admin/recurring_application_charges/#{id}.json
View Response
HTTP/1.1 200 OK
PUT/admin/recurring_application_charges/455696195/customize.json

Change the capped amount of an active recurring application charge

Increase the capped amount for a shop

PUT /admin/recurring_application_charges/#{id}/customize.json?recurring_application_charge[capped_amount]=200
View Response
HTTP/1.1 200 OK
{
  "recurring_application_charge": {
    "id": 455696195,
    "name": "Super Mega Plan",
    "api_client_id": 755357713,
    "price": "15.00",
    "status": "active",
    "return_url": "http:\/\/yourapp.com",
    "billing_on": "2016-07-27",
    "created_at": "2016-07-27T16:49:16-04:00",
    "updated_at": "2016-07-27T16:50:38-04:00",
    "test": null,
    "activated_on": "2016-07-27",
    "trial_ends_on": "2016-07-27",
    "cancelled_on": null,
    "trial_days": 0,
    "capped_amount": "100.00",
    "balance_used": 0.0,
    "balance_remaining": 100.0,
    "risk_level": 0.075,
    "decorated_return_url": "http:\/\/yourapp.com?charge_id=455696195",
    "update_capped_amount_url": "https:\/\/apple.myshopify.com\/admin\/charges\/455696195\/confirm_update_capped_amount?signature=BAhpBENfKRs%3D--d19a9a6c0570bd65d09a6fe4c5f73f95d3d6c946"
  }
}