Shopify API – RecurringApplicationCharge

top

Create a recurring application charge

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

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

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

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

After the charge has been accepted or declined, Shopify redirects the shop owner to the return_url set in the request, and appends a parameter accepted set to true when the charge is accepted and false when declined. Retrieving the RecurringApplicationCharge will also show that its status will have updated to be active

Updating

Each shop may have only one recurring charge per application.

When a new RecurringApplicationCharge is created for a shop that already has a recurring charge for that application, the existing recurring charge will be cancelled and pro-rated for the duration it has been active for. The new recurring charge will then activate.

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

Note

Test or demo shops may not be charged.

POST /admin/recurring_application_charges.xml

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

Request

           
<?xml version="1.0" encoding="UTF-8"?>
<recurring-application-charge>
  <price type="float">10.0</price>
  <name>Super Duper Plan</name>
  <return-url>http://super-duper.shopifyapps.com</return-url>
  <test type="boolean">true</test>
</recurring-application-charge>      

Response

           
HTTP/1.1 201 Created
<?xml version="1.0" encoding="UTF-8"?>
<recurring-application-charge>
  <billing-on type="date">2009-11-19</billing-on>
  <created-at type="datetime">2009-10-20T07:29:49-04:00</created-at>
  <id type="integer">1728123008</id>
  <name>Super Duper Plan</name>
  <price type="decimal">10.00</price>
  <return-url>http://super-duper.shopifyapps.com?signature=5ebe2294ecd0e0f08eab7690d2a6ee69</return-url>
  <status>pending</status>
  <updated-at type="datetime">2009-10-20T07:29:49-04:00</updated-at>
  <confirmation-url>http://apple.myshopify.com/admin/subscriptions/confirm_recurring_application_charge/1728123008?signature=BAhsKweAEAFn--2e92009e1b50b0d2fcc5ca46deff7fa5748a36da</confirmation-url>
</recurring-application-charge>
top

Retrieve all recurring application charges

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

GET /admin/recurring_application_charges.xml

Retrieving all recurring charges

Response

           
HTTP/1.1 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<recurring-application-charges type="array">
  <recurring-application-charge>
    <billing-on type="date">2009-10-19</billing-on>
    <created-at type="datetime">2009-10-20T07:28:52-04:00</created-at>
    <id type="integer">1529438018</id>
    <name>Super Mega Plan</name>
    <price type="decimal">15.00</price>
    <return-url>http://yourapp.com?accepted=true&amp;signature=e6cfc87b2d4ea8fbf963eab803fc26bf</return-url>
    <status>active</status>
    <updated-at type="datetime">2009-10-20T07:29:54-04:00</updated-at>
  </recurring-application-charge>
</recurring-application-charges>
top

Cancel a recurring application charge

Errata

Cancelled plans are not pro-rated.

GET /admin/recurring_application_charges.xml

Cancel the current recurring charge for a shop

Response

           
HTTP/1.1 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<recurring-application-charges type="array">
  <recurring-application-charge>
    <billing-on type="date">2009-10-19</billing-on>
    <created-at type="datetime">2009-10-20T07:28:52-04:00</created-at>
    <id type="integer">1529438018</id>
    <name>Super Mega Plan</name>
    <price type="decimal">15.00</price>
    <return-url>http://yourapp.com?signature=5ebe2294ecd0e0f08eab7690d2a6ee69</return-url>
    <status>cancelled</status>
    <updated-at type="datetime">2009-10-20T07:29:52-04:00</updated-at>
  </recurring-application-charge>
</recurring-application-charges>
Last updated at Oct 2009 Oct:10 AM.