Overview

A runnable sample app of Deferred Purchase Options = Pre-order / Try-before-you-buy app based on Shopify developer document

This app is cloned and modified from this sample app.

How to run

0. You need to submit deferred purchase option API access request from your app settings in partner dashboard (this doesn't need to be a public app, custom one is OK which makes you approved more easily).

1. Add the following environmental variables locally or in cloud platforms like Render / Heroku / Fly, etc.

SHOPIFY_API_KEY:              YOUR_API_KEY (Copy and paste from your app settings in partner dashboard)
SHOPIFY_API_SECRET:           YOUR_API_SECRET (Copy and paste from your app settings in partner dashboard)
SHOPIFY_API_VERSION:          unstable
SHOPIFY_API_SCOPES:           write_products,write_orders,write_purchase_options,write_payment_mandate,write_customers,write_assigned_fulfillment_orders,write_merchant_managed_fulfillment_orders,write_third_party_fulfillment_orders

SHOPIFY_CONTRACT_EXT_ID:      The value of 'SHOPIFY_MY_THEME_CONTRACT_EXT_ID' in '.env' which is generated by `npm run deploy` in step 6. described below

SHOPIFY_DB_TYPE:              MONGODB (Default) / POSTGRESQL / MYSQL

// The followings are required if you set SHOPIFY_DB_TYPE 'MONGODB'
SHOPIFY_MONGO_DB_NAME:        YOUR_DB_NAME (any name is OK)
SHOPIFY_MONGO_URL:            mongodb://YOUR_USER:YOUR_PASSWORD@YOUR_DOMAIN:YOUR_PORT/YOUR_DB_NAME

// The followings are required if you set SHOPIFY_DB_TYPE 'POSTGRESQL'
SHOPIFY_POSTGRESQL_URL:       postgres://YOUR_USER:YOUR_PASSWORD@YOUR_DOMAIN(:YOUR_PORT)/YOUR_DB_NAME

// The followings are required if you set SHOPIFY_DB_TYPE 'MYSQL'
SHOPIFY_MYSQL_HOST:           YOUR_DOMAIN
SHOPIFY_MYSQL_USER:           YOUR_USER
SHOPIFY_MYSQL_PASSWORD:       YOUR_PASSWORD
SHOPIFY_MYSQL_DATABASE:       YOUR_DB_NAME

2. Build and run the app server locally or in cloud platforms. All settings are described in package.json (note that the built React code contains SHOPIFY_API_KEY value from its envrionment variable, so if you run it with your own app, you have to run the build command below at least one time).

Build command = npm install && npm run build (= cd frontend && npm install && npm run build && rm -rf ../public/assets && mv dist/assets ../public/assets && mv dist/index.html ../views/index.html  *Replacing Koa index file with Vite buit code)

Start command = npm run start (= node app.js)

3. If you run locally, you need to tunnel localhost for public URL as follows (otherwise, you should use the command lines above for Render or other cloud platform deploy scripts).

cloudflared tunnel --url localhost:3000 or ./ngrok http 3000

4. Set YOUR_APP_URL (your cloudflare or ngrok or other platform root URL) and YOUR_APP_URL/callback to your app settings in partner dashboard and also replace const APP_URL=... in extensions/my-deferred-purchase-ext/src/index.jsx with YOUR_APP_URL manually.

5. (For PostgreSQL or MySQL users only,) create the following table in your database (in psql or mysql command or other tools).

For PostgreSQL:

CREATE TABLE shops ( _id VARCHAR NOT NULL PRIMARY KEY, data json NOT NULL, created_at TIMESTAMP NOT NULL, updated_at TIMESTAMP NOT NULL );

For MySQL:

CREATE TABLE shops ( _id VARCHAR(500) NOT NULL PRIMARY KEY, data JSON NOT NULL, created_at TIMESTAMP NOT NULL, updated_at TIMESTAMP NOT NULL );

6. Turn OFF [Development store preview] in app extensions menu.

7. For CLI generated extensions, execute npm run deploy -- --reset and follow its instruction (choose your partner account, connecting to the exising app, etc.) which registers extensions to your exising app and create /.env file which has extensiton ids used by this sample app. After the command ends successfully.

8. For updating the extensions, execute npm run deploy (without -- --reset) to apply (upload) your local modified files to the created extensions (-- --reset is used for changing your targeted app only).

How to install

Access to the following endpoit. https://SHOPIFY_SHOP_DOMAIN/admin/oauth/authorize?client_id=YOUR_API_KEY&scope=YOUR_API_SCOPES&redirect_uri=YOUR_APP_URL/callback&state=&grant_options[]=　

Or

you can install to your development stores from the app settings in partner dashboard.

Sample list

All sample videos are available at Wiki.

Trouble shooting

• If you cannot see any selling plans in your product pages in the storefront through the theme app extension in your dev. store, try to activate Shopify Payments test mode or PayPal live mode because Shopify purchase options (subscription / deferred purchase) limit the available payment methods (even if you activate PayPal, you can use Boogus gateway for test credit card payment, tho...).

TIPS

• Note that making selling plans does NOT mean charging the remaining balance and fulfillments are done by Shopify automatically, all those operations need to be done by merchants manually or by the app using corresponding APIs like orderCreateMandatePayment and fulfillmentCreateV2 as described here. For the app responsibility, check this page.
• Shopify new customer accounts my page supports deferred purchase options natively, so you don't have to integrate any code if the merchant use it instead of the classic one. See the Wiki screenshot.
• You can use the endpoint of webhookgdpr for GDPR Webhooks.
• Subscriptions uses the similar APIs, and if you are interested in, check this sample, too.

Disclaimer

• This code is fully unofficial and NOT guaranteed to pass the public app review for Shopify app store. The official requirements are described here.
• You need to follow Shopi API Licene and Terms of Use even for custom app usage.