Billing API implementation flow

[Alan2]

Greetings,

We are interested in publishing an app on Shopify - the app will basically use a Script Tag to add a widget to store pages. We have implemented this part and can install the app on test stores.

We need to implement billing. A recurring charge, with an initial free trial.

We are insure at which step we should post that initial charge. It is during the app installation? After the oauth process and before adding the Script Tag?

Additionally, we should post a new recurring charge once for each of our monthly billing cycle? 

Any pointers here would of great help

Best regards, 

[Joel-Reeds]

A typical install process looks like this:

1. User Clicks "Get" on App Store Listing
2. App Receives Shop Domain And Redirects User Back To Install Page With client_id, scope, redirect_uri and state.
3. User Clicks "Install" and is redirected back to your app using the redirect_uri above for authentication.  Response should include a code, HMAC, timestamp, state and shop.  The app should validate the returned response by comparing the sent state to the returned state, as well as validating the return HMAC.
4. App generates an oauth access token using the returned code and your app API Key & secret.
5. App creates a recurring application charge with the plan name, price, return_url, trial_days and test status.  App then redirects user to the returned confirmation_url.
6. User accepts charge and is redirected back to your App using the redirect_url defined in the recurring application charge creation.  Returned user carries a charge_id in the URL.
7. App looks up the recurring application charge status using the returned charge_id.  If user has accepted the charge, app activates the charge.
8. App completes necessary install functions.  For example in your case this would include adding the Script Tag.

Once the user has accepted the recurring application charge you shouldn't need to create another one, unless the customer cancels.  Keep the returned charge_id stored so you can make a API call to check the status of the charge if needed.

Good luck with your app!

Cheers,

Joel.

[wiretrackio]

@

[wiretrackio]

Hi @Joel-Reeds 

Thanks a lot for your explanation.

Even though your response is from 2017 I imagine this hasn't changed much since then.

I'm not sure I understand the full flow (considering OAuth and billing).

Our current flow (without billing, only OAuth) is:

1. User clicks "install"

2. App receives the request and redirects to the permission URL

3. User accepts the installation (confirms the OAuth flow)

4. App receives the callback request and redirects the user to the application

If I understand correctly, the application charge would also happen in the "callback" route, meaning, at the same time the app gets the token it also creates the subscription charge.

What is not clear to me is, if that's the logic, and the user also needs to confirm the subscription charge, the user would have two steps to "accept" the installation: one for the installation/OAuth, and the other for the subscription charge. But I'm not sure I'm interpreting this the right way. I couldn't quite understand how the subscriptions and OAuth flow talk to each other.

Any suggestions?

Thanks!

[Joel-Reeds]

Hey @wiretrackio,

If a merchant is required to activate billing upon installation of the app, then you would need to create an application charge upon the response from the OAuth flow (Step 4), then redirect the merchant to the confirmation_url in the response.

This will send the merchant to the Shopify billing confirmation page to accept the application charge.  When they accept the charge they will be redirected to the return_url you provided in the ApplicationCharge creation step. to your application with a charge_id that is used to confirm the billing status.

You would then update your internal storage with the billing info and mark the account as activated their billing.

Regards,

Joel.

[wiretrackio]

Hey @Joel-Reeds 

Thanks a lot for the response.

This was exactly my doubt, so from your response I understand that the user would need to "interact" twice with the app: one for the OAuth installation and the second to approve the charge. So I would just add the application charge right on the OAuth callback method (after the user agreed to install the app). This considering the billing is activated as soon as the user installs the app.

I would have imagined that there was a way for the user to accept both the application charge and installation (OAuth flow) at the same time, but I understand this is not the case, and I will have to do both separately. 

Thanks a lot!

[Alan2]

Hi Joel,

Thanks, this helps a lot - very clear steps.

I do have one question. If the customer at a later date cancels billing how do we know so we can remove the Script Tag? I assume we have to periodically query the endpoint, or is there a webhook?

Best regards,

[Joel-Reeds]

Add a webhook for app/uninstalled.   This will send you a notification when the user uninstalls the app.

[Alan2]

Perfect - thanks.

Is this webhook event invoked only when the customer explicitly uninstalls the app, or will it also be automatically invoked when the user cancels the billing?

Best regards,

[Felix2]

From my experience, it's only fired when uninstalling the app.

[Joel-Reeds]

From everything I can find the only way a user can cancel the billing for an app is to uninstall it.

Perhaps a Shopify Expert could weigh in to confirm this for us.