The REST Admin API is a legacy API as of October 1, 2024. All apps and integrations should be built with the GraphQL Admin API. For details and migration steps, visit our migration guide.

Anchor to section titled 'undefined'

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.

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.

Was this section helpful?
Anchor to section titled 'The RecurringApplicationCharge resource'

The RecurringApplicationCharge resource

Properties
activated_on
->createdAt
The date and time (ISO 8601 format) when the customer activated the recurring application charge.
Note: The recurring application charge must be activated or the returned value is null.
billing_on
->currentPeriodEnd
The date and time (ISO 8601 format) when the customer is billed.
Note: The recurring application charge must be accepted or the returned value is null.
cancelled_on
deprecated
The date and time (ISO 8601 format) when the merchant canceled their recurring application charge.
Note: Returns null when the recurring application charge is not canceled.
capped_amount
->cappedAmount
The limit a customer can be charged for usage based billing. If this property is provided, then you must also provide the terms property. See usage charges for more information.
confirmation_url
The URL where the merchant accepts or declines the recurring application charge.
created_at
->createdAt
The date and time (ISO 8601 format) when the recurring application charge was created.
id
->id
The ID of the recurring application charge.
name
->name
The name of the recurring application charge.
price
->price
The price of the recurring application charge. The maximum price is 10,000.
return_url
->returnUrl
The URL where the merchant is redirected after accepting the charge.
status
->status

The status of the recurring charge. Valid values:

terms
->terms
The terms and conditions of usage based billing charges. Must be present in order to create usage charges, for example when the capped_amount property is provided. Presented to the merchant when they approve an app's usage charges.
Was this section helpful?
{}The RecurringApplicationCharge resource
{
  "activated_on": null,
  "billing_on": null,
  "cancelled_on": null,
  "capped_amount": "100",
  "confirmation_url": "https://jsmith.myshopify.com/admin/charges/confirm_recurring_application_charge?id=654381177&signature=BAhpBHkQASc%3D--374c02da2ea0371b23f40781b8a6d5f4a520e77b",
  "created_at": "2013-06-27T08:48:27-04:00",
  "id": 675931192,
  "name": "Super Duper Expensive action",
  "price": "100.00",
  "return_url": "http://super-duper.shopifyapps.com",
  "status": "accepted",
  "terms": "$1 for 1000 emails",
  "test": null,
  "trial_days": 0,
  "trial_ends_on": null,
  "updated_at": "2013-06-27T08:48:27-04:00",
  "currency": "USD"
}
Anchor to section titled 'POST request, Creates a recurring application charge'

post
Creates a recurring application charge

appSubscriptionCreate
Creates a recurring application charge. Make sure to include a valid return_url property to ensure the merchant is redirected after accepting the charge (an invalid or missing return_url property may lead to unstable behaviour in the charge approval flow).
Anchor to section titled 'Parameters of Creates a recurring application charge'

Parameters

api_version
string
required
Was this section helpful?
Anchor to section titled 'Examples of Creates a recurring application charge'

Examples

Request body
recurringapplicationcharge
Recurring_application_charge resource
Was this section helpful?
post
/admin/api/2024-10/recurring_application_charges.json
Copy
curl -d '{"recurring_application_charge":{"name":"Super Duper Plan","price":10.0,"return_url":"http://super-duper.shopifyapps.com","trial_days":5}}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2024-10/recurring_application_charges.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}Response
JSON
HTTP/1.1 201 Created
{
  "recurring_application_charge": {
    "id": 1029266953,
    "name": "Super Duper Plan",
    "price": "10.00",
    "billing_on": null,
    "status": "pending",
    "created_at": "2024-09-30T15:49:06-04:00",
    "updated_at": "2024-09-30T15:49:06-04:00",
    "activated_on": null,
    "return_url": "http://super-duper.shopifyapps.com/",
    "test": null,
    "cancelled_on": null,
    "trial_days": 5,
    "trial_ends_on": null,
    "api_client_id": 755357713,
    "decorated_return_url": "http://super-duper.shopifyapps.com/?charge_id=1029266953",
    "confirmation_url": "https://jsmith.myshopify.com/admin/charges/755357713/1029266953/RecurringApplicationCharge/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBAleWT06EmF1dG9fYWN0aXZhdGVU--3ff75f4af39200440bfaa8884000935f12459da5",
    "currency": "USD"
  }
}
Anchor to section titled 'GET request, Retrieves a list of recurring application charges'

get
Retrieves a list of recurring application charges

currentAppInstallation
Retrieves a list of recurring application charges
Anchor to section titled 'Parameters of Retrieves a list of recurring application charges'

Parameters

api_version
string
required
fields
A comma-separated list of fields to include in the response.
since_id
Restrict results to after the specified ID.
Was this section helpful?
Anchor to section titled 'Examples of Retrieves a list of recurring application charges'

Examples

Was this section helpful?
get
/admin/api/2024-10/recurring_application_charges.json
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-10/recurring_application_charges.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{
  "recurring_application_charges": [
    {
      "id": 455696195,
      "name": "Super Mega Plan",
      "price": "15.00",
      "billing_on": "2024-09-30",
      "status": "accepted",
      "created_at": "2024-09-30T15:48:38-04:00",
      "updated_at": "2024-09-30T15:49:00-04:00",
      "activated_on": null,
      "return_url": "http://yourapp.example.org",
      "test": null,
      "cancelled_on": null,
      "trial_days": 0,
      "trial_ends_on": null,
      "api_client_id": 755357713,
      "decorated_return_url": "http://yourapp.example.org?charge_id=455696195",
      "currency": "USD"
    }
  ]
}
Anchor to section titled 'GET request, Retrieves a single charge'

get
Retrieves a single charge

currentAppInstallation
Retrieves a single charge
Anchor to section titled 'Parameters of Retrieves a single charge'

Parameters

api_version
string
required
recurring_application_charge_id
string
required
fields
A comma-separated list of fields to include in the response.
Was this section helpful?
Anchor to section titled 'Examples of Retrieves a single charge'

Examples

Path parameters
recurringapplicationchargeid=455696195
string
required
Was this section helpful?
get
/admin/api/2024-10/recurring_application_charges/455696195.json
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-10/recurring_application_charges/455696195.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{
  "recurring_application_charge": {
    "id": 455696195,
    "name": "Super Mega Plan",
    "price": "15.00",
    "billing_on": "2024-09-30",
    "status": "pending",
    "created_at": "2024-09-30T15:48:38-04:00",
    "updated_at": "2024-09-30T15:48:38-04:00",
    "activated_on": null,
    "return_url": "http://yourapp.example.org",
    "test": null,
    "cancelled_on": null,
    "trial_days": 0,
    "trial_ends_on": null,
    "api_client_id": 755357713,
    "decorated_return_url": "http://yourapp.example.org?charge_id=455696195",
    "confirmation_url": "https://jsmith.myshopify.com/admin/charges/755357713/455696195/RecurringApplicationCharge/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBENfKRs6EmF1dG9fYWN0aXZhdGVU--b5f90d04779cc5242b396e4054f2e650c5dace1c",
    "currency": "USD"
  }
}
Anchor to section titled 'PUT request, Updates the capped amount of a recurring application charge'

put
Updates the capped amount of a recurring application charge

appSubscriptionLineItemUpdate
Updates the capped amount of an active recurring application charge. Note that you cannot use this endpoint to update any other proprty on a recurring application charge or the capped amount on an Annual subscription.
Anchor to section titled 'Parameters of Updates the capped amount of a recurring application charge'

Parameters

api_version
string
required
recurring_application_charge_id
string
required
Was this section helpful?
Anchor to section titled 'Examples of Updates the capped amount of a recurring application charge'

Examples

Query parameters
Was this section helpful?
put
/admin/api/2024-10/recurring_application_charges/455696195/customize.json?recurringapplicationcharge[cappedamount]=200
Copy
curl -X PUT "https://your-development-store.myshopify.com/admin/api/2024-10/recurring_application_charges/455696195/customize.json?recurring_application_charge%5Bcapped_amount%5D=200" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{
  "recurring_application_charge": {
    "id": 455696195,
    "name": "Super Mega Plan",
    "price": "15.00",
    "billing_on": null,
    "status": "active",
    "created_at": "2024-09-30T15:48:38-04:00",
    "updated_at": "2024-09-30T15:49:02-04:00",
    "activated_on": "2024-09-30",
    "return_url": "http://yourapp.example.org",
    "test": null,
    "cancelled_on": null,
    "trial_days": 0,
    "trial_ends_on": "2024-09-30",
    "api_client_id": 755357713,
    "decorated_return_url": "http://yourapp.example.org?charge_id=455696195",
    "capped_amount": "100.00",
    "balance_used": "0.0",
    "balance_remaining": "100.00",
    "risk_level": 0,
    "update_capped_amount_url": "https://jsmith.myshopify.com/admin/charges/755357713/455696195/RecurringApplicationCharge/confirm_update_capped_amount?signature=BAh7BzoHaWRpBENfKRs6EmF1dG9fYWN0aXZhdGVG--136c3934bb6bc02c23d1582830bcdfdcb7806ac6",
    "currency": "USD"
  }
}
Anchor to section titled 'DELETE request, Cancels a recurring application charge'

del
Cancels a recurring application charge

appSubscriptionCancel
Cancels a recurring application charge
Anchor to section titled 'Parameters of Cancels a recurring application charge'

Parameters

api_version
string
required
recurring_application_charge_id
string
required
Was this section helpful?
Anchor to section titled 'Examples of Cancels a recurring application charge'

Examples

Path parameters
recurringapplicationchargeid=455696195
string
required
Was this section helpful?
del
/admin/api/2024-10/recurring_application_charges/455696195.json
Copy
curl -X DELETE "https://your-development-store.myshopify.com/admin/api/2024-10/recurring_application_charges/455696195.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK