The REST Admin API is a legacy API as of October 1, 2024. Starting April 1, 2025, all new public apps must be built exclusively with the GraphQL Admin API. For details and migration steps, visit our migration guide.
Recurring
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 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.
Endpoints
- post/admin/api/latest/recurring_
application_ charges. json Creates a recurring application charge - get/admin/api/latest/recurring_
application_ charges. json Retrieves a list of recurring application charges - get/admin/api/latest/recurring_
application_ charges/{recurring_ application_ charge_ id}. json Retrieves a single charge - put/admin/api/latest/recurring_
application_ charges/{recurring_ application_ charge_ id}/customize. json?recurring_ application_ charge[capped_ amount]=200 Updates the capped amount of a recurring application charge - del/admin/api/latest/recurring_
application_ charges/{recurring_ application_ charge_ id}. json Cancels a recurring application charge
The RecurringApplicationCharge resource
Properties
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.
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.
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.
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.
The URL where the merchant accepts or declines the recurring application charge.
The date and time (ISO 8601 format) when the recurring application charge was created.
The ID of the recurring application charge.
The name of the recurring application charge.
The price of the recurring application charge. The maximum price is 10,000.
The URL where the merchant is redirected after accepting the charge.
The status of the recurring charge. Valid values:
Show status properties
- pending: The recurring charge is pending.
- accepted: Removed in version 2021-01. The recurring charge has been accepted. As of API version 2021-01, when a merchant accepts a charge, the charge immediately transitions from
pendingtoactive. - active: The recurring charge is activated. This is the only status that actually causes a merchant to be charged. As of API version 2021-01, when a merchant accepts a charge, the charge immediately transitions from
pendingtoactive. - declined: The recurring charge has been declined.
- expired: The recurring charge was not accepted within 2 days of being created.
- frozen: The recurring charge is on hold due to a shop subscription non-payment. The charge will re-activate once subscription payments resume.
- cancelled: The developer cancelled the charge.
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.
The RecurringApplicationCharge resource
Anchor to POST request, Creates a recurring application chargepostCreates a recurring application charge
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).
Create a new charge with a trial period. The trial period will go into effect at the time the recurring charge is activated.
Create a new charge with a trial period. The trial period will go into effect at the time the recurring charge is activated.
Show recurring_application_charge properties
The name of the recurring application charge.
The price of the recurring application charge. The maximum price is 10,000.
The URL where the merchant is redirected after accepting the charge.
The number of days that the customer is eligible for a free trial.
Create a new charge with terms and a capped amount
Create a new charge with terms and a capped amount
Show recurring_application_charge properties
The name of the recurring application charge.
The price of the recurring application charge. The maximum price is 10,000.
The URL where the merchant is redirected after accepting the charge.
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.
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.
Create a recurring application charge
Create a recurring application charge
Show recurring_application_charge properties
The name of the recurring application charge.
The price of the recurring application charge. The maximum price is 10,000.
The URL where the merchant is redirected after accepting the charge.
Create a recurring test charge that will not cause a credit card to be charged
Create a recurring test charge that will not cause a credit card to be charged
Show recurring_application_charge properties
The name of the recurring application charge.
The price of the recurring application charge. The maximum price is 10,000.
The URL where the merchant is redirected after accepting the charge.
Whether the application charge is a test transaction. Valid values: true,null.
Trying to create a charge without a price and name will return an error
Trying to create a charge without a price and name will return an error
Show recurring_application_charge properties
The name of the recurring application charge.
/admin/api/2025-07/recurring_
Response
Anchor to GET request, Retrieves a list of recurring application chargesgetRetrieves a list of recurring application charges
Retrieves a list of recurring application charges
A comma-separated list of fields to include in the response.
Restrict results to after the specified ID.
Retrieve all recurring application charges
Retrieve all recurring application charges
Retrieve all recurring charges since a specified ID
Retrieve all recurring charges since a specified ID
Restrict results to after the specified ID.
/admin/api/2025-07/recurring_
Response
Anchor to GET request, Retrieves a single chargegetRetrieves a single charge
Retrieves a single charge
A comma-separated list of fields to include in the response.
Retrieve a single charge
Retrieve a single charge
/admin/api/2025-07/recurring_
Response
Anchor to PUT request, Updates the capped amount of a recurring application chargeputUpdates the capped amount of a recurring application charge
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.
Increase the capped amount for a shop
Increase the capped amount for a shop
/admin/api/2025-07/recurring_
Response
Anchor to DELETE request, Cancels a recurring application chargedelCancels a recurring application charge
Cancels a recurring application charge
Cancel the current recurring charge for a shop
Cancel the current recurring charge for a shop