Application Billing
From Shopify Wiki
Contents |
Application Billing Through Shopify
Third party apps can make use of the Shopify billing API to handle both recurring (e.g. subscription) and one-off payments. The advantages of using this method are two-fold. For developers it makes integration easier and merchants don't have to give their payment info to a third party: Apps that use the billing API show up on the merchant's existing Shopify invoice.
Note: An app does not have to be available through the Shopify App Store in order to take advantage of the billing API.
Revenue Share
Shopify takes a 20% share of the funds paid to developers through the billing API.
Types of Billing
One-Time Charge
Applications are able to ask shop merchants to approve one-time charges. When accepted, these charges are added to the shop’s upcoming invoice.
Recurring Charge
Applications are able to ask shop merchants to approve recurring charges. When accepted, these charges are added to the shop’s upcoming invoice on a recurring basis, starting 30 days after that particular recurring charge has been accepted.
The first time the shop will see the recurring application charge is often on the invoice after the invoice they expect it to be on. Here’s an example timeline to explain why that’s the case:
Day 0 Shop signs up; 30-day shop billing cycle starts Day 5 App is installed; 30-day recurring app billing cycle starts Day 30 Shop is invoiced; invoice does not mention app charge Day 35 Recurring charge is added to shop’s next invoice; recurring cycle restarts Day 37 Shop credit card is charged; no app charge Day 60 Shop is invoiced; app charge appears for the first time Day 67 Shop credit card is charged; app charge included
Note that these recurring application billing cycles happen on a per-install basis, shop and app specific. A shop will have its own 30-day billing cycle, plus an independent 30-day cycle for each app install/recurring application charge.
Billing Process
Getting Started
Let's assume you are a developer with an existing app who wants to charge for it using the billing API. Where do you begin?
First things first, take a look at the API documentation. There's an overview of the billing API, and separate pages for one-time and recurring charges.
Charge Creation
Creating a charge is a multi-step process. The order of events is as follows:
- App creates the charge
- User approves the charge
- App activates the charge
The trigger for the charge can be anything you want: Installation, service plan upgrade, individual purchase, etc.
When creating a new charge, the API needs a return URL. This is the URL at which Shopify will notify your app when the user approves (or declines) the charge. In return, The API returns another URL when the charge is created. This URL is a link to the confirmation page for the charge. If possible, the app should redirect the user to this page immediately.
If the merchant approves the charge, the app needs to activate it. This should be done when the return URL provided when creating the charge is called. If the charge is not activated it will not appear on the merchant's invoice and you won't get paid.
Technical details on how to implement this process can be found on in our API documentation.
Charge States
Charges transition through a number of states as various parties act on them.
One-Time Charge States
The one-time charge states are simple. Once the merchant has accepted the charge and the app has activated it, the store is billed and the charge remains in the active state.
Recurring Charge States
Recurring charges are a bit more complicated. Once activated and approved, the system has to handle the case where future payments are declined for some reason. If a shop stops paying its bills Shopify will freeze the account. It will be unfrozen and charges will resume in the event that the store starts payments again.
From the app developer perspective, service should continue to be provided to a store as long as the associated recurring charge is in the Active state.
FAQs
What happens when a shop uninstalls an app?
If the app has an accepted recurring application charge with the shop, that charge is cancelled and added in full to the next invoice. There is no pro-rating.
What happens when a shop cancels?
Any recurring application charges are pro-rated and added to the shop’s last invoice.
What happens when a shop changes its plan?
The shop’s billing cycle restarts, but the recurring application charge cycle is unchanged.
When does an unapproved app charge expire?
If an app charge (one-time or recurring) is not approved by the merchant within 48 hours, it expires and is deleted from the system. When this happens, you'll need to recreate the charge if you still want to bill the merchant.
Where's My Money?
The Partners Dashboard only reports the money Shopify knows for sure you’ve got coming, as in Shopify has successfully charged the merchant for the amount on their invoice, including the charges your application levied.
That means if you've made a 30 day recurring charge, that charge won't be added to the running total in the partner dashboard until:
- The 30 days have elapsed and the charge has been added to the merchant's next Shopify invoice
- The merchant has paid Shopify for the invoice the charge was added to. (Note that Shopify merchant payment cycles are 30 days long with a 7 day invoice review period.)
All this is to say that it will be at least 30 days between activating the charge and it appearing in your partner dashboard total summation.
Why is it like this? For a few legal reasons we're in the process of ironing out, we can only show you the totals of the amount of money we're for sure going to be remitting to you the partner. We're working on fixing this so we can give you a more useful and encouraging number sooner. Trust us - we dislike this as much as you do, so we're working pretty hard to change this to be a non-issue.