Shopify

The Shopify app is a wrapper around the Shopify Development Ecosystem. It provides a consistent interface for interacting with Shopify within the confines of our framework.

Checkout the Shopify documentation for more information.

The Shopify app sits on top of our Ecommerce package which allows connects things like transactions automatically when you enable crons.

App Store

In order to save the clients auth tokens, this package extends app store.

It will automatically install the shopify app into the app store database when you include it in your project.

Installation

To start using the Shopify app, follow these instructions:

  1. Install the package
pnpm install @juicyllama/app-shopify
  1. Add the module to your application
// app.module.ts
import { ShopifyModule } from '@juicyllama/app-shopify'

@Module({
    imports: [ShopifyModule],
})
export class AppModule {}

Integration

There are two ways to integrate with Shopify:

Access Token

If your use case does not require a fully published app into the Shopify App store and instead you already have access to the Admin API Access Token, e.g. your application only requires access to one store. You can pass this optional value when creating an installed app inside the app-store.

By default this option is hidden inside the app settings object, you can update this from hidden: true to hidden: false. This will allow your users to add this data via the frontend.

The key for this option is SHOPIFY_ADMIN_API_ACCESS_KEY you can add to any installed_app. The system will prioritise this local key over system wide settings.

Shopify App Ecosystem

This app can sit on top of the Shopify App Ecosystem, so you may first create an App in the Shopify Partner Account, here you can also setup a demo store.

This module uses OAuth to connect to shopify stores, to faciliate this we use a cookie to pass the state throught the OAuth flow.You should make sure the cookie-parser package is configured on your project (in your main.ts file)
import cookieParser from 'cookie-parser'
app.use(cookieParser());

Environment Variables

Once your app is created, you will be given the following credentials:

SHOPIFY_APP_CLIENT_ID=
SHOPIFY_APP_CLIENT_SECRET=

Shopify App Setup

You should add the following URL's to your Shopify app:

App URL: ${BASE_URL_API}/oauth/start?integration_name=shopify

Allowed redirection URL(s): ${BASE_URL_API}/app/shopify/auth/redirect${BASE_URL_API}/app/shopify/auth/complete

Replace ${BASE_URL_API} with your actual backend URL.

Extra Oauth Scopes

You can optionally pass in additional scopes if you app has special permissions. An example is that Shopify limits order data to 60 days unless you apply for the read_all_orders scope. This needs to be approved by Shopify. If you app is approved for this, you can add that to the .env file as follows:

SHOPIFY_EXTRA_SCOPES=read_all_orders

This will then be added to the default scopes.

Redirect after Oauth

You can optionally setup a redirect URL which we will send the user to after the Oauth process commpletes, for example, you could redirect them back to your Shopify App screen or to a page on your dashboard confirming the app setup is complete. Add the following to your .env file:

SHOPIFY_OAUTH_REDIRECT_URL=https://some.url

If this is not provided, we will redirect the user back to the your app's base url BASE_URL_APP

Modules

Each endpoint in the Shopify API is built with it's own module, this allows you to install just the module you need, we currently support:

You can also use the shopify provider directly, for more details read about shopify provider.

Crons

The Shopify package ships with the following crons you can enable in your .env file.

CronDescription
CRON_APP_SHOPIFY_SYNC_ORDERSMonitors for new/updated transactions and creates/updates records in the transactions table

Webhooks

We currently support the following webhooks, your application must register them with Shopify before they will be consumed.

WebhookController Route
orders/createapp/shopify/orders/webhook
orders/cancelledapp/shopify/orders/webhook
orders/editedapp/shopify/orders/webhook
orders/fulfilledapp/shopify/orders/webhook
orders/paidapp/shopify/orders/webhook
orders/partially_fulfilledapp/shopify/orders/webhook
orders/updatedapp/shopify/orders/webhook
customers/data_requestapp/shopify/customers/webhook/data_request
customers/redactapp/shopify/customers/webhook/redact
shop/redactapp/shopify/shop/webhook/redact

Docs v.0.9.0 Copyright © 2024