RecurringApplicationCharge
The RecurringApplicationCharge resource facilitates a fixed-value, 30-day recurring charge. You can create an application charge by sending a request with the name the charge should appear under, the price your app is charging, and a return URL where Shopify redirects the merchant after the charge is accepted. After you've created the charge, redirect the merchant to the confirmation URL returned by Shopify. If the charge is declined, then Shopify redirects the merchant and provides a notification message that the app charge was declined. For step-by-step guidance that walks through this flow using examples, see our implementation guide.
Note
For testing purposes you can include "test": true
when creating the charge. This prevents the credit card from being charged.
Test shops and demo shops cannot be charged.
Updating an application charge
Each shop can have only one recurring charge per app. When a new recurring application charge is activated for a shop that already has one, the existing recurring charge is canceled and replaced by the new charge. The new recurring charge is then activated.
For example, if you want to offer discounted pricing to a specific merchant, then you can create a new application charge for the shop. This will prompt the shop to accept the new charge in order to continue using the app. The new charge replaces the old billing going forward.
What you can 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:
- POST /admin/api/2019-10/recurring_application_charges.json Creates a recurring application charge
- GET /admin/api/2019-10/recurring_application_charges/{recurring_application_charge_id}.json Retrieves a single charge
- GET /admin/api/2019-10/recurring_application_charges.json Retrieves a list of recurring application charges
- POST /admin/api/2019-10/recurring_application_charges/{recurring_application_charge_id}/activate.json Removed in version 2021-01. Activates a recurring application charge.
- DELETE /admin/api/2019-10/recurring_application_charges/{recurring_application_charge_id}.json Cancels a recurring application charge
- PUT /admin/api/2019-10/recurring_application_charges/{recurring_application_charge_id}/customize.json?recurring_application_charge[capped_amount]=200 Updates the capped amount of a recurring application charge
RecurringApplicationCharge properties
activated_on |
The date and time (ISO 8601 format) when the customer activated the recurring application charge. |
billing_on |
The date and time (ISO 8601 format) when the customer is billed. |
cancelled_on |
The date and time (ISO 8601 format) when the merchant canceled their recurring application charge. |
capped_amount |
The limit a customer can be charged for usage based billing. If this property is provided, then you must also provide the |
confirmation_url |
The URL where the merchant accepts or declines the recurring application charge. |
created_at |
The date and time (ISO 8601 format) when the recurring application charge was created. |
id |
The ID of the recurring application charge. |
name |
The name of the recurring application charge. |
price |
The price of the recurring application charge. The maximum price is 10,000. |
return_url |
The URL where the merchant is redirected after accepting the charge. |
status |
The status of the recurring charge. Valid values:
|
terms |
The terms and conditions of usage based billing charges. Must be present in order to create usage charges, for example when the |
test |
Whether the application charge is a test transaction. Valid values: |
trial_days |
The number of days that the customer is eligible for a free trial. |
trial_ends_on |
The date and time (ISO 8601 format) when the free trial ends. |
updated_at |
The date and time (ISO 8601 format) when the recurring application charge was last updated. |
Endpoints
Create a recurring application charge
POST /admin/api/2019-10/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": 1029266954,
"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": "2021-04-01T16:06:29-04:00",
"updated_at": "2021-04-01T16:06:29-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"decorated_return_url": "http://super-duper.shopifyapps.com/?charge_id=1029266954",
"confirmation_url": "https://apple.myshopify.com/admin/charges/1029266954/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBApeWT06EmF1dG9fYWN0aXZhdGVU--623b148570b432d8164c7737e647b596a9d68b79"
}
}
Create a new charge with terms and a capped amount
POST /admin/api/2019-10/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": 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": "2021-04-01T16:06:33-04:00",
"updated_at": "2021-04-01T16:06:33-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"capped_amount": "100.00",
"trial_ends_on": null,
"balance_used": 0.0,
"balance_remaining": 100.0,
"risk_level": 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=BAh7BzoHaWRpBAteWT06EmF1dG9fYWN0aXZhdGVU--ebcaabe65d3e99236a2d2097a8d3ea592fc61966"
}
}
Create a recurring test charge that will not cause a credit card to be charged
POST /admin/api/2019-10/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": 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": "2021-04-01T16:06:35-04:00",
"updated_at": "2021-04-01T16:06:35-04:00",
"test": true,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"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=BAh7BzoHaWRpBAxeWT06EmF1dG9fYWN0aXZhdGVU--cfac91d852547dd7084a2f19bede87a443c1bdf1"
}
}
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/api/2019-10/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": 1029266957,
"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": "2021-04-01T16:06:36-04:00",
"updated_at": "2021-04-01T16:06:36-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 5,
"trial_ends_on": null,
"decorated_return_url": "http://super-duper.shopifyapps.com/?charge_id=1029266957",
"confirmation_url": "https://apple.myshopify.com/admin/charges/1029266957/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBA1eWT06EmF1dG9fYWN0aXZhdGVU--52bcabc865b37121c7d531889002022d35fa5902"
}
}
Trying to create a charge without a price and name will return an error
POST /admin/api/2019-10/recurring_application_charges.json
{
"recurring_application_charge": {
"name": ""
}
}
View Response
HTTP/1.1 422 Unprocessable Entity
{
"errors": {
"name": [
"can't be blank"
],
"price": [
"must be greater than zero"
]
}
}
fields
|
A comma-separated list of fields to include in the response. |
Retrieve a single charge
GET /admin/api/2019-10/recurring_application_charges/455696195.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": "2021-04-01",
"created_at": "2021-04-01T15:57:26-04:00",
"updated_at": "2021-04-01T15:57:26-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"decorated_return_url": "http://yourapp.com?charge_id=455696195",
"confirmation_url": "https://apple.myshopify.com/admin/charges/455696195/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBENfKRs6EmF1dG9fYWN0aXZhdGVG--679000481979aae18d5e349f712aab6fb053a1ff"
}
}
since_id
|
Restrict results to after the specified ID. |
fields
|
A comma-separated list of fields to include in the response. |
Retrieve all recurring application charges
GET /admin/api/2019-10/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": "2021-04-01",
"created_at": "2021-04-01T15:57:26-04:00",
"updated_at": "2021-04-01T16:05:02-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"decorated_return_url": "http://yourapp.com?charge_id=455696195"
}
]
}
Retrieve all recurring charges since a specified ID
GET /admin/api/2019-10/recurring_application_charges.json?since_id=455696195
View Response
HTTP/1.1 200 OK
{
"recurring_application_charges": [
{
"id": 1029266950,
"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": "2021-04-01T16:05:16-04:00",
"updated_at": "2021-04-01T16:05:16-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"decorated_return_url": "http://super-duper.shopifyapps.com/?charge_id=1029266950",
"confirmation_url": "https://apple.myshopify.com/admin/charges/1029266950/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBAZeWT06EmF1dG9fYWN0aXZhdGVG--1945df3b51ef83c9e056d4300b113d4b07c97616"
}
]
}
Activate a recurring application charge
POST /admin/api/2019-10/recurring_application_charges/455696195/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": "2021-04-01",
"created_at": "2021-04-01T15:57:26-04:00",
"updated_at": "2021-03-31T20:00:00-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"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": "2021-05-01",
"created_at": "2021-04-01T15:57:26-04:00",
"updated_at": "2021-03-31T20:00:00-04:00",
"test": null,
"activated_on": "2021-04-01",
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": "2021-04-01",
"decorated_return_url": "http://yourapp.com?charge_id=455696195"
}
}
Cancel the current recurring charge for a shop
DELETE /admin/api/2019-10/recurring_application_charges/455696195.json
View Response
HTTP/1.1 200 OK
Increase the capped amount for a shop
PUT /admin/api/2019-10/recurring_application_charges/455696195/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": "2018-09-04",
"created_at": "2021-04-01T15:57:26-04:00",
"updated_at": "2021-04-01T16:05:52-04:00",
"test": null,
"activated_on": "2021-04-01",
"cancelled_on": null,
"trial_days": 0,
"capped_amount": "100.00",
"trial_ends_on": "2021-04-01",
"balance_used": 0.0,
"balance_remaining": 100.0,
"risk_level": 0,
"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=BAh7BzoHaWRpBENfKRs6EmF1dG9fYWN0aXZhdGVG--349388d4ae4b654f135ece8631fd2df1b0cda01c"
}
}
The RecurringApplicationCharge resource facilitates a fixed-value, 30-day recurring charge. You can create an application charge by sending a request with the name the charge should appear under, the price your app is charging, and a return URL where Shopify redirects the merchant after the charge is accepted. After you've created the charge, redirect the merchant to the confirmation URL returned by Shopify. If the charge is declined, then Shopify redirects the merchant and provides a notification message that the app charge was declined. For step-by-step guidance that walks through this flow using examples, see our implementation guide.
Note
For testing purposes you can include "test": true
when creating the charge. This prevents the credit card from being charged.
Test shops and demo shops cannot be charged.
Updating an application charge
Each shop can have only one recurring charge per app. When a new recurring application charge is activated for a shop that already has one, the existing recurring charge is canceled and replaced by the new charge. The new recurring charge is then activated.
For example, if you want to offer discounted pricing to a specific merchant, then you can create a new application charge for the shop. This will prompt the shop to accept the new charge in order to continue using the app. The new charge replaces the old billing going forward.
What you can 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:
- POST /admin/api/2020-01/recurring_application_charges.json Creates a recurring application charge
- GET /admin/api/2020-01/recurring_application_charges/{recurring_application_charge_id}.json Retrieves a single charge
- GET /admin/api/2020-01/recurring_application_charges.json Retrieves a list of recurring application charges
- POST /admin/api/2020-01/recurring_application_charges/{recurring_application_charge_id}/activate.json Removed in version 2021-01. Activates a recurring application charge.
- DELETE /admin/api/2020-01/recurring_application_charges/{recurring_application_charge_id}.json Cancels a recurring application charge
- PUT /admin/api/2020-01/recurring_application_charges/{recurring_application_charge_id}/customize.json?recurring_application_charge[capped_amount]=200 Updates the capped amount of a recurring application charge
RecurringApplicationCharge properties
activated_on |
The date and time (ISO 8601 format) when the customer activated the recurring application charge. |
billing_on |
The date and time (ISO 8601 format) when the customer is billed. |
cancelled_on |
The date and time (ISO 8601 format) when the merchant canceled their recurring application charge. |
capped_amount |
The limit a customer can be charged for usage based billing. If this property is provided, then you must also provide the |
confirmation_url |
The URL where the merchant accepts or declines the recurring application charge. |
created_at |
The date and time (ISO 8601 format) when the recurring application charge was created. |
id |
The ID of the recurring application charge. |
name |
The name of the recurring application charge. |
price |
The price of the recurring application charge. The maximum price is 10,000. |
return_url |
The URL where the merchant is redirected after accepting the charge. |
status |
The status of the recurring charge. Valid values:
|
terms |
The terms and conditions of usage based billing charges. Must be present in order to create usage charges, for example when the |
test |
Whether the application charge is a test transaction. Valid values: |
trial_days |
The number of days that the customer is eligible for a free trial. |
trial_ends_on |
The date and time (ISO 8601 format) when the free trial ends. |
updated_at |
The date and time (ISO 8601 format) when the recurring application charge was last updated. |
Endpoints
Create a recurring application charge
POST /admin/api/2020-01/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": 1029266954,
"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": "2021-04-01T16:06:29-04:00",
"updated_at": "2021-04-01T16:06:29-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"decorated_return_url": "http://super-duper.shopifyapps.com/?charge_id=1029266954",
"confirmation_url": "https://apple.myshopify.com/admin/charges/1029266954/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBApeWT06EmF1dG9fYWN0aXZhdGVU--623b148570b432d8164c7737e647b596a9d68b79"
}
}
Create a new charge with terms and a capped amount
POST /admin/api/2020-01/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": 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": "2021-04-01T16:06:33-04:00",
"updated_at": "2021-04-01T16:06:33-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"capped_amount": "100.00",
"trial_ends_on": null,
"balance_used": 0.0,
"balance_remaining": 100.0,
"risk_level": 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=BAh7BzoHaWRpBAteWT06EmF1dG9fYWN0aXZhdGVU--ebcaabe65d3e99236a2d2097a8d3ea592fc61966"
}
}
Create a recurring test charge that will not cause a credit card to be charged
POST /admin/api/2020-01/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": 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": "2021-04-01T16:06:35-04:00",
"updated_at": "2021-04-01T16:06:35-04:00",
"test": true,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"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=BAh7BzoHaWRpBAxeWT06EmF1dG9fYWN0aXZhdGVU--cfac91d852547dd7084a2f19bede87a443c1bdf1"
}
}
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/api/2020-01/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": 1029266957,
"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": "2021-04-01T16:06:36-04:00",
"updated_at": "2021-04-01T16:06:36-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 5,
"trial_ends_on": null,
"decorated_return_url": "http://super-duper.shopifyapps.com/?charge_id=1029266957",
"confirmation_url": "https://apple.myshopify.com/admin/charges/1029266957/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBA1eWT06EmF1dG9fYWN0aXZhdGVU--52bcabc865b37121c7d531889002022d35fa5902"
}
}
Trying to create a charge without a price and name will return an error
POST /admin/api/2020-01/recurring_application_charges.json
{
"recurring_application_charge": {
"name": ""
}
}
View Response
HTTP/1.1 422 Unprocessable Entity
{
"errors": {
"name": [
"can't be blank"
],
"price": [
"must be greater than zero"
]
}
}
fields
|
A comma-separated list of fields to include in the response. |
Retrieve a single charge
GET /admin/api/2020-01/recurring_application_charges/455696195.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": "2021-04-01",
"created_at": "2021-04-01T15:57:26-04:00",
"updated_at": "2021-04-01T15:57:26-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"decorated_return_url": "http://yourapp.com?charge_id=455696195",
"confirmation_url": "https://apple.myshopify.com/admin/charges/455696195/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBENfKRs6EmF1dG9fYWN0aXZhdGVG--679000481979aae18d5e349f712aab6fb053a1ff"
}
}
since_id
|
Restrict results to after the specified ID. |
fields
|
A comma-separated list of fields to include in the response. |
Retrieve all recurring application charges
GET /admin/api/2020-01/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": "2021-04-01",
"created_at": "2021-04-01T15:57:26-04:00",
"updated_at": "2021-04-01T16:05:02-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"decorated_return_url": "http://yourapp.com?charge_id=455696195"
}
]
}
Retrieve all recurring charges since a specified ID
GET /admin/api/2020-01/recurring_application_charges.json?since_id=455696195
View Response
HTTP/1.1 200 OK
{
"recurring_application_charges": [
{
"id": 1029266950,
"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": "2021-04-01T16:05:16-04:00",
"updated_at": "2021-04-01T16:05:16-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"decorated_return_url": "http://super-duper.shopifyapps.com/?charge_id=1029266950",
"confirmation_url": "https://apple.myshopify.com/admin/charges/1029266950/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBAZeWT06EmF1dG9fYWN0aXZhdGVG--1945df3b51ef83c9e056d4300b113d4b07c97616"
}
]
}
Activate a recurring application charge
POST /admin/api/2020-01/recurring_application_charges/455696195/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": "2021-04-01",
"created_at": "2021-04-01T15:57:26-04:00",
"updated_at": "2021-03-31T20:00:00-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"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": "2021-05-01",
"created_at": "2021-04-01T15:57:26-04:00",
"updated_at": "2021-03-31T20:00:00-04:00",
"test": null,
"activated_on": "2021-04-01",
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": "2021-04-01",
"decorated_return_url": "http://yourapp.com?charge_id=455696195"
}
}
Cancel the current recurring charge for a shop
DELETE /admin/api/2020-01/recurring_application_charges/455696195.json
View Response
HTTP/1.1 200 OK
Increase the capped amount for a shop
PUT /admin/api/2020-01/recurring_application_charges/455696195/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": "2018-09-04",
"created_at": "2021-04-01T15:57:26-04:00",
"updated_at": "2021-04-01T16:05:52-04:00",
"test": null,
"activated_on": "2021-04-01",
"cancelled_on": null,
"trial_days": 0,
"capped_amount": "100.00",
"trial_ends_on": "2021-04-01",
"balance_used": 0.0,
"balance_remaining": 100.0,
"risk_level": 0,
"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=BAh7BzoHaWRpBENfKRs6EmF1dG9fYWN0aXZhdGVG--349388d4ae4b654f135ece8631fd2df1b0cda01c"
}
}
The RecurringApplicationCharge resource facilitates a fixed-value, 30-day recurring charge. You can create an application charge by sending a request with the name the charge should appear under, the price your app is charging, and a return URL where Shopify redirects the merchant after the charge is accepted. After you've created the charge, redirect the merchant to the confirmation URL returned by Shopify. If the charge is declined, then Shopify redirects the merchant and provides a notification message that the app charge was declined. For step-by-step guidance that walks through this flow using examples, see our implementation guide.
Note
For testing purposes you can include "test": true
when creating the charge. This prevents the credit card from being charged.
Test shops and demo shops cannot be charged.
Updating an application charge
Each shop can have only one recurring charge per app. When a new recurring application charge is activated for a shop that already has one, the existing recurring charge is canceled and replaced by the new charge. The new recurring charge is then activated.
For example, if you want to offer discounted pricing to a specific merchant, then you can create a new application charge for the shop. This will prompt the shop to accept the new charge in order to continue using the app. The new charge replaces the old billing going forward.
What you can 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:
- POST /admin/api/2020-04/recurring_application_charges.json Creates a recurring application charge
- GET /admin/api/2020-04/recurring_application_charges/{recurring_application_charge_id}.json Retrieves a single charge
- GET /admin/api/2020-04/recurring_application_charges.json Retrieves a list of recurring application charges
- POST /admin/api/2020-04/recurring_application_charges/{recurring_application_charge_id}/activate.json Removed in version 2021-01. Activates a recurring application charge.
- DELETE /admin/api/2020-04/recurring_application_charges/{recurring_application_charge_id}.json Cancels a recurring application charge
- PUT /admin/api/2020-04/recurring_application_charges/{recurring_application_charge_id}/customize.json?recurring_application_charge[capped_amount]=200 Updates the capped amount of a recurring application charge
RecurringApplicationCharge properties
activated_on |
The date and time (ISO 8601 format) when the customer activated the recurring application charge. |
billing_on |
The date and time (ISO 8601 format) when the customer is billed. |
cancelled_on |
The date and time (ISO 8601 format) when the merchant canceled their recurring application charge. |
capped_amount |
The limit a customer can be charged for usage based billing. If this property is provided, then you must also provide the |
confirmation_url |
The URL where the merchant accepts or declines the recurring application charge. |
created_at |
The date and time (ISO 8601 format) when the recurring application charge was created. |
id |
The ID of the recurring application charge. |
name |
The name of the recurring application charge. |
price |
The price of the recurring application charge. The maximum price is 10,000. |
return_url |
The URL where the merchant is redirected after accepting the charge. |
status |
The status of the recurring charge. Valid values:
|
terms |
The terms and conditions of usage based billing charges. Must be present in order to create usage charges, for example when the |
test |
Whether the application charge is a test transaction. Valid values: |
trial_days |
The number of days that the customer is eligible for a free trial. |
trial_ends_on |
The date and time (ISO 8601 format) when the free trial ends. |
updated_at |
The date and time (ISO 8601 format) when the recurring application charge was last updated. |
Endpoints
Create a recurring application charge
POST /admin/api/2020-04/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": 1029266954,
"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": "2021-04-01T16:06:29-04:00",
"updated_at": "2021-04-01T16:06:29-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"decorated_return_url": "http://super-duper.shopifyapps.com/?charge_id=1029266954",
"confirmation_url": "https://apple.myshopify.com/admin/charges/1029266954/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBApeWT06EmF1dG9fYWN0aXZhdGVU--623b148570b432d8164c7737e647b596a9d68b79"
}
}
Create a new charge with terms and a capped amount
POST /admin/api/2020-04/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": 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": "2021-04-01T16:06:33-04:00",
"updated_at": "2021-04-01T16:06:33-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"capped_amount": "100.00",
"trial_ends_on": null,
"balance_used": 0.0,
"balance_remaining": 100.0,
"risk_level": 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=BAh7BzoHaWRpBAteWT06EmF1dG9fYWN0aXZhdGVU--ebcaabe65d3e99236a2d2097a8d3ea592fc61966"
}
}
Create a recurring test charge that will not cause a credit card to be charged
POST /admin/api/2020-04/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": 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": "2021-04-01T16:06:35-04:00",
"updated_at": "2021-04-01T16:06:35-04:00",
"test": true,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"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=BAh7BzoHaWRpBAxeWT06EmF1dG9fYWN0aXZhdGVU--cfac91d852547dd7084a2f19bede87a443c1bdf1"
}
}
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/api/2020-04/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": 1029266957,
"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": "2021-04-01T16:06:36-04:00",
"updated_at": "2021-04-01T16:06:36-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 5,
"trial_ends_on": null,
"decorated_return_url": "http://super-duper.shopifyapps.com/?charge_id=1029266957",
"confirmation_url": "https://apple.myshopify.com/admin/charges/1029266957/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBA1eWT06EmF1dG9fYWN0aXZhdGVU--52bcabc865b37121c7d531889002022d35fa5902"
}
}
Trying to create a charge without a price and name will return an error
POST /admin/api/2020-04/recurring_application_charges.json
{
"recurring_application_charge": {
"name": ""
}
}
View Response
HTTP/1.1 422 Unprocessable Entity
{
"errors": {
"name": [
"can't be blank"
],
"price": [
"must be greater than zero"
]
}
}
fields
|
A comma-separated list of fields to include in the response. |
Retrieve a single charge
GET /admin/api/2020-04/recurring_application_charges/455696195.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": "2021-04-01",
"created_at": "2021-04-01T15:57:26-04:00",
"updated_at": "2021-04-01T15:57:26-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"decorated_return_url": "http://yourapp.com?charge_id=455696195",
"confirmation_url": "https://apple.myshopify.com/admin/charges/455696195/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBENfKRs6EmF1dG9fYWN0aXZhdGVG--679000481979aae18d5e349f712aab6fb053a1ff"
}
}
since_id
|
Restrict results to after the specified ID. |
fields
|
A comma-separated list of fields to include in the response. |
Retrieve all recurring application charges
GET /admin/api/2020-04/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": "2021-04-01",
"created_at": "2021-04-01T15:57:26-04:00",
"updated_at": "2021-04-01T16:05:02-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"decorated_return_url": "http://yourapp.com?charge_id=455696195"
}
]
}
Retrieve all recurring charges since a specified ID
GET /admin/api/2020-04/recurring_application_charges.json?since_id=455696195
View Response
HTTP/1.1 200 OK
{
"recurring_application_charges": [
{
"id": 1029266950,
"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": "2021-04-01T16:05:16-04:00",
"updated_at": "2021-04-01T16:05:16-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"decorated_return_url": "http://super-duper.shopifyapps.com/?charge_id=1029266950",
"confirmation_url": "https://apple.myshopify.com/admin/charges/1029266950/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBAZeWT06EmF1dG9fYWN0aXZhdGVG--1945df3b51ef83c9e056d4300b113d4b07c97616"
}
]
}
Activate a recurring application charge
POST /admin/api/2020-04/recurring_application_charges/455696195/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": "2021-04-01",
"created_at": "2021-04-01T15:57:26-04:00",
"updated_at": "2021-03-31T20:00:00-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"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": "2021-05-01",
"created_at": "2021-04-01T15:57:26-04:00",
"updated_at": "2021-03-31T20:00:00-04:00",
"test": null,
"activated_on": "2021-04-01",
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": "2021-04-01",
"decorated_return_url": "http://yourapp.com?charge_id=455696195"
}
}
Cancel the current recurring charge for a shop
DELETE /admin/api/2020-04/recurring_application_charges/455696195.json
View Response
HTTP/1.1 200 OK
Increase the capped amount for a shop
PUT /admin/api/2020-04/recurring_application_charges/455696195/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": "2018-09-04",
"created_at": "2021-04-01T15:57:26-04:00",
"updated_at": "2021-04-01T16:05:52-04:00",
"test": null,
"activated_on": "2021-04-01",
"cancelled_on": null,
"trial_days": 0,
"capped_amount": "100.00",
"trial_ends_on": "2021-04-01",
"balance_used": 0.0,
"balance_remaining": 100.0,
"risk_level": 0,
"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=BAh7BzoHaWRpBENfKRs6EmF1dG9fYWN0aXZhdGVG--349388d4ae4b654f135ece8631fd2df1b0cda01c"
}
}
The RecurringApplicationCharge resource facilitates a fixed-value, 30-day recurring charge. You can create an application charge by sending a request with the name the charge should appear under, the price your app is charging, and a return URL where Shopify redirects the merchant after the charge is accepted. After you've created the charge, redirect the merchant to the confirmation URL returned by Shopify. If the charge is declined, then Shopify redirects the merchant and provides a notification message that the app charge was declined. For step-by-step guidance that walks through this flow using examples, see our implementation guide.
Note
For testing purposes you can include "test": true
when creating the charge. This prevents the credit card from being charged.
Test shops and demo shops cannot be charged.
Updating an application charge
Each shop can have only one recurring charge per app. When a new recurring application charge is activated for a shop that already has one, the existing recurring charge is canceled and replaced by the new charge. The new recurring charge is then activated.
For example, if you want to offer discounted pricing to a specific merchant, then you can create a new application charge for the shop. This will prompt the shop to accept the new charge in order to continue using the app. The new charge replaces the old billing going forward.
What you can 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:
- POST /admin/api/2020-07/recurring_application_charges.json Creates a recurring application charge
- GET /admin/api/2020-07/recurring_application_charges/{recurring_application_charge_id}.json Retrieves a single charge
- GET /admin/api/2020-07/recurring_application_charges.json Retrieves a list of recurring application charges
- POST /admin/api/2020-07/recurring_application_charges/{recurring_application_charge_id}/activate.json Removed in version 2021-01. Activates a recurring application charge.
- DELETE /admin/api/2020-07/recurring_application_charges/{recurring_application_charge_id}.json Cancels a recurring application charge
- PUT /admin/api/2020-07/recurring_application_charges/{recurring_application_charge_id}/customize.json?recurring_application_charge[capped_amount]=200 Updates the capped amount of a recurring application charge
RecurringApplicationCharge properties
activated_on |
The date and time (ISO 8601 format) when the customer activated the recurring application charge. |
billing_on |
The date and time (ISO 8601 format) when the customer is billed. |
cancelled_on |
The date and time (ISO 8601 format) when the merchant canceled their recurring application charge. |
capped_amount |
The limit a customer can be charged for usage based billing. If this property is provided, then you must also provide the |
confirmation_url |
The URL where the merchant accepts or declines the recurring application charge. |
created_at |
The date and time (ISO 8601 format) when the recurring application charge was created. |
id |
The ID of the recurring application charge. |
name |
The name of the recurring application charge. |
price |
The price of the recurring application charge. The maximum price is 10,000. |
return_url |
The URL where the merchant is redirected after accepting the charge. |
status |
The status of the recurring charge. Valid values:
|
terms |
The terms and conditions of usage based billing charges. Must be present in order to create usage charges, for example when the |
test |
Whether the application charge is a test transaction. Valid values: |
trial_days |
The number of days that the customer is eligible for a free trial. |
trial_ends_on |
The date and time (ISO 8601 format) when the free trial ends. |
updated_at |
The date and time (ISO 8601 format) when the recurring application charge was last updated. |
Endpoints
Create a recurring application charge
POST /admin/api/2020-07/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": 1029266954,
"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": "2021-04-01T16:06:29-04:00",
"updated_at": "2021-04-01T16:06:29-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"decorated_return_url": "http://super-duper.shopifyapps.com/?charge_id=1029266954",
"confirmation_url": "https://apple.myshopify.com/admin/charges/1029266954/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBApeWT06EmF1dG9fYWN0aXZhdGVU--623b148570b432d8164c7737e647b596a9d68b79"
}
}
Create a new charge with terms and a capped amount
POST /admin/api/2020-07/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": 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": "2021-04-01T16:06:33-04:00",
"updated_at": "2021-04-01T16:06:33-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"capped_amount": "100.00",
"trial_ends_on": null,
"balance_used": 0.0,
"balance_remaining": 100.0,
"risk_level": 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=BAh7BzoHaWRpBAteWT06EmF1dG9fYWN0aXZhdGVU--ebcaabe65d3e99236a2d2097a8d3ea592fc61966"
}
}
Create a recurring test charge that will not cause a credit card to be charged
POST /admin/api/2020-07/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": 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": "2021-04-01T16:06:35-04:00",
"updated_at": "2021-04-01T16:06:35-04:00",
"test": true,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"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=BAh7BzoHaWRpBAxeWT06EmF1dG9fYWN0aXZhdGVU--cfac91d852547dd7084a2f19bede87a443c1bdf1"
}
}
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/api/2020-07/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": 1029266957,
"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": "2021-04-01T16:06:36-04:00",
"updated_at": "2021-04-01T16:06:36-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 5,
"trial_ends_on": null,
"decorated_return_url": "http://super-duper.shopifyapps.com/?charge_id=1029266957",
"confirmation_url": "https://apple.myshopify.com/admin/charges/1029266957/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBA1eWT06EmF1dG9fYWN0aXZhdGVU--52bcabc865b37121c7d531889002022d35fa5902"
}
}
Trying to create a charge without a price and name will return an error
POST /admin/api/2020-07/recurring_application_charges.json
{
"recurring_application_charge": {
"name": ""
}
}
View Response
HTTP/1.1 422 Unprocessable Entity
{
"errors": {
"name": [
"can't be blank"
],
"price": [
"must be greater than zero"
]
}
}
fields
|
A comma-separated list of fields to include in the response. |
Retrieve a single charge
GET /admin/api/2020-07/recurring_application_charges/455696195.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": "2021-04-01",
"created_at": "2021-04-01T15:57:26-04:00",
"updated_at": "2021-04-01T15:57:26-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"decorated_return_url": "http://yourapp.com?charge_id=455696195",
"confirmation_url": "https://apple.myshopify.com/admin/charges/455696195/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBENfKRs6EmF1dG9fYWN0aXZhdGVG--679000481979aae18d5e349f712aab6fb053a1ff"
}
}
since_id
|
Restrict results to after the specified ID. |
fields
|
A comma-separated list of fields to include in the response. |
Retrieve all recurring application charges
GET /admin/api/2020-07/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": "2021-04-01",
"created_at": "2021-04-01T15:57:26-04:00",
"updated_at": "2021-04-01T16:05:02-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"decorated_return_url": "http://yourapp.com?charge_id=455696195"
}
]
}
Retrieve all recurring charges since a specified ID
GET /admin/api/2020-07/recurring_application_charges.json?since_id=455696195
View Response
HTTP/1.1 200 OK
{
"recurring_application_charges": [
{
"id": 1029266950,
"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": "2021-04-01T16:05:16-04:00",
"updated_at": "2021-04-01T16:05:16-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"decorated_return_url": "http://super-duper.shopifyapps.com/?charge_id=1029266950",
"confirmation_url": "https://apple.myshopify.com/admin/charges/1029266950/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBAZeWT06EmF1dG9fYWN0aXZhdGVG--1945df3b51ef83c9e056d4300b113d4b07c97616"
}
]
}
Activate a recurring application charge
POST /admin/api/2020-07/recurring_application_charges/455696195/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": "2021-04-01",
"created_at": "2021-04-01T15:57:26-04:00",
"updated_at": "2021-03-31T20:00:00-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"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": "2021-05-01",
"created_at": "2021-04-01T15:57:26-04:00",
"updated_at": "2021-03-31T20:00:00-04:00",
"test": null,
"activated_on": "2021-04-01",
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": "2021-04-01",
"decorated_return_url": "http://yourapp.com?charge_id=455696195"
}
}
Cancel the current recurring charge for a shop
DELETE /admin/api/2020-07/recurring_application_charges/455696195.json
View Response
HTTP/1.1 200 OK
Increase the capped amount for a shop
PUT /admin/api/2020-07/recurring_application_charges/455696195/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": "2018-09-04",
"created_at": "2021-04-01T15:57:26-04:00",
"updated_at": "2021-04-01T16:05:52-04:00",
"test": null,
"activated_on": "2021-04-01",
"cancelled_on": null,
"trial_days": 0,
"capped_amount": "100.00",
"trial_ends_on": "2021-04-01",
"balance_used": 0.0,
"balance_remaining": 100.0,
"risk_level": 0,
"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=BAh7BzoHaWRpBENfKRs6EmF1dG9fYWN0aXZhdGVG--349388d4ae4b654f135ece8631fd2df1b0cda01c"
}
}
The RecurringApplicationCharge resource facilitates a fixed-value, 30-day recurring charge. You can create an application charge by sending a request with the name the charge should appear under, the price your app is charging, and a return URL where Shopify redirects the merchant after the charge is accepted. After you've created the charge, redirect the merchant to the confirmation URL returned by Shopify. If the charge is declined, then Shopify redirects the merchant and provides a notification message that the app charge was declined. For step-by-step guidance that walks through this flow using examples, see our implementation guide.
Note
For testing purposes you can include "test": true
when creating the charge. This prevents the credit card from being charged.
Test shops and demo shops cannot be charged.
Updating an application charge
Each shop can have only one recurring charge per app. When a new recurring application charge is activated for a shop that already has one, the existing recurring charge is canceled and replaced by the new charge. The new recurring charge is then activated.
For example, if you want to offer discounted pricing to a specific merchant, then you can create a new application charge for the shop. This will prompt the shop to accept the new charge in order to continue using the app. The new charge replaces the old billing going forward.
What you can 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:
- POST /admin/api/2020-10/recurring_application_charges.json Creates a recurring application charge
- GET /admin/api/2020-10/recurring_application_charges/{recurring_application_charge_id}.json Retrieves a single charge
- GET /admin/api/2020-10/recurring_application_charges.json Retrieves a list of recurring application charges
- POST /admin/api/2020-10/recurring_application_charges/{recurring_application_charge_id}/activate.json Removed in version 2021-01. Activates a recurring application charge.
- DELETE /admin/api/2020-10/recurring_application_charges/{recurring_application_charge_id}.json Cancels a recurring application charge
- PUT /admin/api/2020-10/recurring_application_charges/{recurring_application_charge_id}/customize.json?recurring_application_charge[capped_amount]=200 Updates the capped amount of a recurring application charge
RecurringApplicationCharge properties
activated_on |
The date and time (ISO 8601 format) when the customer activated the recurring application charge. |
billing_on |
The date and time (ISO 8601 format) when the customer is billed. |
cancelled_on |
The date and time (ISO 8601 format) when the merchant canceled their recurring application charge. |
capped_amount |
The limit a customer can be charged for usage based billing. If this property is provided, then you must also provide the |
confirmation_url |
The URL where the merchant accepts or declines the recurring application charge. |
created_at |
The date and time (ISO 8601 format) when the recurring application charge was created. |
id |
The ID of the recurring application charge. |
name |
The name of the recurring application charge. |
price |
The price of the recurring application charge. The maximum price is 10,000. |
return_url |
The URL where the merchant is redirected after accepting the charge. |
status |
The status of the recurring charge. Valid values:
|
terms |
The terms and conditions of usage based billing charges. Must be present in order to create usage charges, for example when the |
test |
Whether the application charge is a test transaction. Valid values: |
trial_days |
The number of days that the customer is eligible for a free trial. |
trial_ends_on |
The date and time (ISO 8601 format) when the free trial ends. |
updated_at |
The date and time (ISO 8601 format) when the recurring application charge was last updated. |
Endpoints
Create a recurring application charge
POST /admin/api/2020-10/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": 1029266954,
"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": "2021-04-01T16:06:29-04:00",
"updated_at": "2021-04-01T16:06:29-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"decorated_return_url": "http://super-duper.shopifyapps.com/?charge_id=1029266954",
"confirmation_url": "https://apple.myshopify.com/admin/charges/1029266954/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBApeWT06EmF1dG9fYWN0aXZhdGVU--623b148570b432d8164c7737e647b596a9d68b79"
}
}
Create a new charge with terms and a capped amount
POST /admin/api/2020-10/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": 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": "2021-04-01T16:06:33-04:00",
"updated_at": "2021-04-01T16:06:33-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"capped_amount": "100.00",
"trial_ends_on": null,
"balance_used": 0.0,
"balance_remaining": 100.0,
"risk_level": 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=BAh7BzoHaWRpBAteWT06EmF1dG9fYWN0aXZhdGVU--ebcaabe65d3e99236a2d2097a8d3ea592fc61966"
}
}
Create a recurring test charge that will not cause a credit card to be charged
POST /admin/api/2020-10/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": 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": "2021-04-01T16:06:35-04:00",
"updated_at": "2021-04-01T16:06:35-04:00",
"test": true,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"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=BAh7BzoHaWRpBAxeWT06EmF1dG9fYWN0aXZhdGVU--cfac91d852547dd7084a2f19bede87a443c1bdf1"
}
}
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/api/2020-10/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": 1029266957,
"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": "2021-04-01T16:06:36-04:00",
"updated_at": "2021-04-01T16:06:36-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 5,
"trial_ends_on": null,
"decorated_return_url": "http://super-duper.shopifyapps.com/?charge_id=1029266957",
"confirmation_url": "https://apple.myshopify.com/admin/charges/1029266957/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBA1eWT06EmF1dG9fYWN0aXZhdGVU--52bcabc865b37121c7d531889002022d35fa5902"
}
}
Trying to create a charge without a price and name will return an error
POST /admin/api/2020-10/recurring_application_charges.json
{
"recurring_application_charge": {
"name": ""
}
}
View Response
HTTP/1.1 422 Unprocessable Entity
{
"errors": {
"name": [
"can't be blank"
],
"price": [
"must be greater than zero"
]
}
}
fields
|
A comma-separated list of fields to include in the response. |
Retrieve a single charge
GET /admin/api/2020-10/recurring_application_charges/455696195.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": "2021-04-01",
"created_at": "2021-04-01T15:57:26-04:00",
"updated_at": "2021-04-01T15:57:26-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"decorated_return_url": "http://yourapp.com?charge_id=455696195",
"confirmation_url": "https://apple.myshopify.com/admin/charges/455696195/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBENfKRs6EmF1dG9fYWN0aXZhdGVG--679000481979aae18d5e349f712aab6fb053a1ff"
}
}
since_id
|
Restrict results to after the specified ID. |
fields
|
A comma-separated list of fields to include in the response. |
Retrieve all recurring application charges
GET /admin/api/2020-10/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": "2021-04-01",
"created_at": "2021-04-01T15:57:26-04:00",
"updated_at": "2021-04-01T16:05:02-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"decorated_return_url": "http://yourapp.com?charge_id=455696195"
}
]
}
Retrieve all recurring charges since a specified ID
GET /admin/api/2020-10/recurring_application_charges.json?since_id=455696195
View Response
HTTP/1.1 200 OK
{
"recurring_application_charges": [
{
"id": 1029266950,
"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": "2021-04-01T16:05:16-04:00",
"updated_at": "2021-04-01T16:05:16-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"decorated_return_url": "http://super-duper.shopifyapps.com/?charge_id=1029266950",
"confirmation_url": "https://apple.myshopify.com/admin/charges/1029266950/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBAZeWT06EmF1dG9fYWN0aXZhdGVG--1945df3b51ef83c9e056d4300b113d4b07c97616"
}
]
}
Activate a recurring application charge
POST /admin/api/2020-10/recurring_application_charges/455696195/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": "2021-04-01",
"created_at": "2021-04-01T15:57:26-04:00",
"updated_at": "2021-03-31T20:00:00-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"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": "2021-05-01",
"created_at": "2021-04-01T15:57:26-04:00",
"updated_at": "2021-03-31T20:00:00-04:00",
"test": null,
"activated_on": "2021-04-01",
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": "2021-04-01",
"decorated_return_url": "http://yourapp.com?charge_id=455696195"
}
}
Cancel the current recurring charge for a shop
DELETE /admin/api/2020-10/recurring_application_charges/455696195.json
View Response
HTTP/1.1 200 OK
Increase the capped amount for a shop
PUT /admin/api/2020-10/recurring_application_charges/455696195/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": "2018-09-04",
"created_at": "2021-04-01T15:57:26-04:00",
"updated_at": "2021-04-01T16:05:52-04:00",
"test": null,
"activated_on": "2021-04-01",
"cancelled_on": null,
"trial_days": 0,
"capped_amount": "100.00",
"trial_ends_on": "2021-04-01",
"balance_used": 0.0,
"balance_remaining": 100.0,
"risk_level": 0,
"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=BAh7BzoHaWRpBENfKRs6EmF1dG9fYWN0aXZhdGVG--349388d4ae4b654f135ece8631fd2df1b0cda01c"
}
}
The RecurringApplicationCharge resource facilitates a fixed-value, 30-day recurring charge. You can create an application charge by sending a request with the name the charge should appear under, the price your app is charging, and a return URL where Shopify redirects the merchant after the charge is accepted. After you've created the charge, redirect the merchant to the confirmation URL returned by Shopify. If the charge is declined, then Shopify redirects the merchant and provides a notification message that the app charge was declined. For step-by-step guidance that walks through this flow using examples, see our implementation guide.
Note
For testing purposes you can include "test": true
when creating the charge. This prevents the credit card from being charged.
Test shops and demo shops cannot be charged.
Updating an application charge
Each shop can have only one recurring charge per app. When a new recurring application charge is activated for a shop that already has one, the existing recurring charge is canceled and replaced by the new charge. The new recurring charge is then activated.
For example, if you want to offer discounted pricing to a specific merchant, then you can create a new application charge for the shop. This will prompt the shop to accept the new charge in order to continue using the app. The new charge replaces the old billing going forward.
What you can 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:
- POST /admin/api/2021-01/recurring_application_charges.json Creates a recurring application charge
- GET /admin/api/2021-01/recurring_application_charges/{recurring_application_charge_id}.json Retrieves a single charge
- GET /admin/api/2021-01/recurring_application_charges.json Retrieves a list of recurring application charges
- DELETE /admin/api/2021-01/recurring_application_charges/{recurring_application_charge_id}.json Cancels a recurring application charge
- PUT /admin/api/2021-01/recurring_application_charges/{recurring_application_charge_id}/customize.json?recurring_application_charge[capped_amount]=200 Updates the capped amount of a recurring application charge
RecurringApplicationCharge properties
activated_on |
The date and time (ISO 8601 format) when the customer activated the recurring application charge. |
billing_on |
The date and time (ISO 8601 format) when the customer is billed. |
cancelled_on |
The date and time (ISO 8601 format) when the merchant canceled their recurring application charge. |
capped_amount |
The limit a customer can be charged for usage based billing. If this property is provided, then you must also provide the |
confirmation_url |
The URL where the merchant accepts or declines the recurring application charge. |
created_at |
The date and time (ISO 8601 format) when the recurring application charge was created. |
id |
The ID of the recurring application charge. |
name |
The name of the recurring application charge. |
price |
The price of the recurring application charge. The maximum price is 10,000. |
return_url |
The URL where the merchant is redirected after accepting the charge. |
status |
The status of the recurring charge. Valid values:
|
terms |
The terms and conditions of usage based billing charges. Must be present in order to create usage charges, for example when the |
test |
Whether the application charge is a test transaction. Valid values: |
trial_days |
The number of days that the customer is eligible for a free trial. |
trial_ends_on |
The date and time (ISO 8601 format) when the free trial ends. |
updated_at |
The date and time (ISO 8601 format) when the recurring application charge was last updated. |
Endpoints
Create a recurring application charge
POST /admin/api/2021-01/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": 1029266954,
"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": "2021-04-01T16:06:29-04:00",
"updated_at": "2021-04-01T16:06:29-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"decorated_return_url": "http://super-duper.shopifyapps.com/?charge_id=1029266954",
"confirmation_url": "https://apple.myshopify.com/admin/charges/1029266954/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBApeWT06EmF1dG9fYWN0aXZhdGVU--623b148570b432d8164c7737e647b596a9d68b79"
}
}
Create a new charge with terms and a capped amount
POST /admin/api/2021-01/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": 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": "2021-04-01T16:06:33-04:00",
"updated_at": "2021-04-01T16:06:33-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"capped_amount": "100.00",
"trial_ends_on": null,
"balance_used": 0.0,
"balance_remaining": 100.0,
"risk_level": 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=BAh7BzoHaWRpBAteWT06EmF1dG9fYWN0aXZhdGVU--ebcaabe65d3e99236a2d2097a8d3ea592fc61966"
}
}
Create a recurring test charge that will not cause a credit card to be charged
POST /admin/api/2021-01/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": 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": "2021-04-01T16:06:35-04:00",
"updated_at": "2021-04-01T16:06:35-04:00",
"test": true,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"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=BAh7BzoHaWRpBAxeWT06EmF1dG9fYWN0aXZhdGVU--cfac91d852547dd7084a2f19bede87a443c1bdf1"
}
}
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/api/2021-01/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": 1029266957,
"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": "2021-04-01T16:06:36-04:00",
"updated_at": "2021-04-01T16:06:36-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 5,
"trial_ends_on": null,
"decorated_return_url": "http://super-duper.shopifyapps.com/?charge_id=1029266957",
"confirmation_url": "https://apple.myshopify.com/admin/charges/1029266957/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBA1eWT06EmF1dG9fYWN0aXZhdGVU--52bcabc865b37121c7d531889002022d35fa5902"
}
}
Trying to create a charge without a price and name will return an error
POST /admin/api/2021-01/recurring_application_charges.json
{
"recurring_application_charge": {
"name": ""
}
}
View Response
HTTP/1.1 422 Unprocessable Entity
{
"errors": {
"name": [
"can't be blank"
],
"price": [
"must be greater than zero"
]
}
}
fields
|
A comma-separated list of fields to include in the response. |
Retrieve a single charge
GET /admin/api/2021-01/recurring_application_charges/455696195.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": "2021-04-01",
"created_at": "2021-04-01T15:57:26-04:00",
"updated_at": "2021-04-01T15:57:26-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"decorated_return_url": "http://yourapp.com?charge_id=455696195",
"confirmation_url": "https://apple.myshopify.com/admin/charges/455696195/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBENfKRs6EmF1dG9fYWN0aXZhdGVG--679000481979aae18d5e349f712aab6fb053a1ff"
}
}
since_id
|
Restrict results to after the specified ID. |
fields
|
A comma-separated list of fields to include in the response. |
Retrieve all recurring application charges
GET /admin/api/2021-01/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": "2021-04-01",
"created_at": "2021-04-01T15:57:26-04:00",
"updated_at": "2021-04-01T16:05:02-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"decorated_return_url": "http://yourapp.com?charge_id=455696195"
}
]
}
Retrieve all recurring charges since a specified ID
GET /admin/api/2021-01/recurring_application_charges.json?since_id=455696195
View Response
HTTP/1.1 200 OK
{
"recurring_application_charges": [
{
"id": 1029266950,
"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": "2021-04-01T16:05:16-04:00",
"updated_at": "2021-04-01T16:05:16-04:00",
"test": null,
"activated_on": null,
"cancelled_on": null,
"trial_days": 0,
"trial_ends_on": null,
"decorated_return_url": "http://super-duper.shopifyapps.com/?charge_id=1029266950",
"confirmation_url": "https://apple.myshopify.com/admin/charges/1029266950/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBAZeWT06EmF1dG9fYWN0aXZhdGVG--1945df3b51ef83c9e056d4300b113d4b07c97616"
}
]
}