Shopify public app

docs/integrations/commerce/shopify/commerce-shopify-setup.md → docs/integrations/commerce/shopify/commerce-shopify-public-apps.md

@@ -12,24 +12,25 @@ This article explains how to set up the Shopify integration using the _public ap
 
 <summary>You will learn how to...</summary>
 
-- [Create a Shopify app](/integrations/commerce/shopify/commerce-shopify-setup#create-a-shopify-app)
-- [Submit your app to Shopify for approval](/integrations/commerce/shopify/commerce-shopify-setup#submit-your-app-to-shopify-for-approval)
-- [Add your app's credentials to the Shopify integration](/integrations/commerce/shopify/commerce-shopify-setup#add-your-apps-credentials-to-the-shopify-integration)
-- [Enable the Shopify integration](/integrations/commerce/shopify/commerce-shopify-setup#enable-the-shopify-integration)
-- [Check the commerce sync settings](/integrations/commerce/shopify/commerce-shopify-setup#check-the-commerce-sync-settings)
+- [Create a Shopify app](/integrations/commerce/shopify/commerce-shopify-public-apps#create-a-public-shopify-app)
+- [Submit your app to Shopify for approval](/integrations/commerce/shopify/commerce-shopify-public-apps#submit-your-app-to-shopify-for-approval)
+- [Buid an app for merchant authorization](/integrations/commerce/shopify/commerce-shopify-public-apps#build-an-app-for-merchant-authorization)
+- [Add your app's credentials to the Shopify integration](/integrations/commerce/shopify/commerce-shopify-public-apps#add-your-apps-credentials-to-the-shopify-integration)
+- [Enable the Shopify integration](/integrations/commerce/shopify/commerce-shopify-public-apps#enable-the-shopify-integration)
+- [Check the commerce sync settings](/integrations/commerce/shopify/commerce-shopify-public-apps#check-the-commerce-sync-settings)
 
 </details>
 
 ## Before you begin
 
 Before setting up the integration, make sure that you:
 
-- Understand [how public apps work](/integrations/commerce/shopify/commerce-shopify#about-public-apps)
-- Build an app that meets the [Requirements for public apps](/integrations/commerce/shopify/commerce-shopify-requirements-public-apps)
+- Understand [how public apps work](/integrations/commerce/shopify/commerce-shopify#about-public-apps).
+- Have [built an endpoint](/integrations/commerce/shopify/commerce-shopify-public-apps#build-an-app-for-merchant-authorization) that can be used to identify a merchant on your system.
 
-## Create a Shopify public app
+## Create a public Shopify app
 
-When the app is created you can view the secure app credentials.
+When the app is created, you can view the app's secure credentials.
 
 1. Log in to the [Shopify Partners](https://developers.shopify.com/) site using your Shopify partner account credentials.
 
@@ -41,12 +42,12 @@ When the app is created you can view the secure app credentials.
 3. On the **Apps** page, click **Create app**.
 4. In the **Use Shopify Partners** box, click **Create app manually**.
 5. On the **Create an app manually** page, enter the requested information:
-   - **App name:** Enter a name for your app. Do not use _Shopify_ as part of the app name.
-   - **App URL:** Enter a URL for your app. Do not use _Shopify_ as part of the URL. Use the same URL when you submit your app to Shopify for review in the next procedure.
-   - **Allowed redirection URL(s):** Enter `https://commerceintegration.codat.io/oauth/callback`
+   - **App name:** enter a name for your app. Do not use _Shopify_ as part of the app name.
+   - **App URL:** enter `https://commerceintegration.codat.io/publicApp/{your-client-id}`
+   - **Allowed redirection URL(s):** enter `https://commerceintegration.codat.io/oauth/callback`
 6. Click **Create app**. Your app is created and the app page is displayed.
 7. In the side panel, click **App setup** to view the app's configuration settings.
-8. Optional: On the **App setup** page, if you need to access over 60 days' of orders, do the following:
+8. Optional: if you need to access over 60 days' of orders, do the following on the **App setup** page:
    1. In the **Read all orders** box, click **Request access**.
    2. Enter the details requested in the dialog, then submit your request to Shopify.
 9. In the **GDPR mandatory webhooks** section, enter the following Codat webhook URLs:
@@ -55,17 +56,19 @@ When the app is created you can view the secure app credentials.
    - **Shop data erasure endpoint:** `https://commerceintegration.codat.io/webhooks/shop/redact`
 10. Click the **Save** button that appears at the top of the page.
 
-Your app's **API key** and **API secret key** are shown in the **App credentials** section of the App setup page. You'll need these when you [add your app's credentials to the integration](/integrations/commerce/shopify/commerce-shopify-setup#add-your-apps-credentials-to-the-shopify-integration).
+Your app's **API key** and **API secret key** are shown in the **App credentials** section of the App setup page. You'll need these when you [add your app's credentials to the integration](/integrations/commerce/shopify/commerce-shopify-public-apps#add-your-apps-credentials-to-the-shopify-integration).
+
+If you plan to charge for your app, you will need to integrate to [Shopify's billing API](https://shopify.dev/docs/apps/billing).
 
 ## Submit your app to Shopify for approval
 
-Your public app must be approved by Shopify before you can use the integration with a Production Store. The review and approval process might take up to two weeks.
+Your public app must be [approved by Shopify](https://shopify.dev/apps/store/requirements) before you can use the integration with a Production Store. The review and approval process might take up to two weeks.
 
 In the Shopify Partners site:
 
 1. Click the name of your app.
 2. In the side panel, click **Distribution**.
-3. On the **Distribution** page, click **Choose Shopify App Store** then confirm your selection in the dialog that appears.
+3. On the **Distribution** page, click **Choose Shopify App Store**, then confirm your selection in the dialog that appears.
 
 <img src="/img/old/386725f-choose-shopify-app-store.png" />
 
@@ -76,15 +79,45 @@ In the Shopify Partners site:
 
    :::note Differences between listed and unlisted apps
 
-   You can choose whether to make your Shopify app _listed_ (fully visible in the Shopify App Store) or _unlisted_ (it will not appear in Shopify App Store search engines or results). Both types of apps have a public Shopify App Store URL.
+   You can make your Shopify app _listed_ (fully visible in the Shopify App Store) or _unlisted_ (it will not appear in Shopify App Store search engines or results). Both types of apps have a public Shopify App Store URL.
 
    :::
 
 8. Click **Start listing**. The **English listing** page is displayed.
-9. Enter all the required listing information and then save the form.
+9. Enter all the required listing information and save the form.
 10. On the **App listing** page, click the **Submit app** button at the top right. The button is not available until you've completed all the required listing information.
 
-Your app is sent to Shopify for review and approval.
+Your app is then sent to Shopify for review and approval.
+
+Additionally, if you need access to over 60 days of orders from Shopify stores, you must submit a _Read all orders_ request, as noted in [Create a Shopify public app](/integrations/commerce/shopify/commerce-shopify-public-apps#create-a-shopify-public-app). You'll receive an email from Shopify when your request has been processed. This might take up to seven business days.
+
+Codat can't guarantee that Shopify will approve your public app or grant access to over 60 days of order data.
+
+## Build an app for merchant authorization
+
+When a merchant adds your app to their store, we need to be able to identify them. To do that, we will redirect them to the **App Redirect URL** endpoint you entered in the [integration settings](/integrations/commerce/shopify/commerce-shopify-public-apps#add-your-apps-credentials-to-the-shopify-integration) at the end of the auth flow. 
+
+We will generate and include a `code` query string parameter in the initial redirect to maintain context. Allow the user to authenticate themselves on the redirect page, and then create (or use an existing) Codat company and data connection. The data connection response will contain a `linkURL`. Append the `code` to the query string of the URL and redirect the user to complete their auth flow with us.
+
+```mermaid
+sequenceDiagram
+    participant shopify as Shopify
+    participant codat as Codat
+    participant client as Client
+
+
+    shopify ->> codat: Redirect to App URL in Shopify App configuration
+    codat ->> codat: Validate HMAC value
+    codat ->> codat: Handle OAuth flow with Shopify
+    codat ->> client: Redirect to App redirect URL with `code` in query string
+    client ->> client: Merchant authenticates to client's platform
+    client ->> codat: POST /companies
+    codat ->> client: Response with companyId
+    client ->> codat: POST /companies/{companyId}/connections
+    codat ->> client: Response with linkUrl
+    client ->> codat: Redirect to linkUrl with `code` in query string
+    codat ->> codat: Save access token and complete connection
+```
 
 ## Add your app's credentials to the Shopify integration
 
@@ -96,9 +129,10 @@ In the Codat Portal, add the secure credentials for your Shopify app to the inte
 
    The **Integration settings** page is displayed.
 
-3. Enter your app's credentials from Shopify (to find these, see [Create a Shopify public app](/integrations/commerce/shopify/commerce-shopify-setup#create-a-shopify-public-app)).
+3. Enter your app's credentials from Shopify (to find these, see [Create a Shopify public app](/integrations/commerce/shopify/commerce-shopify-public-apps#create-a-shopify-public-app)).
    - For **Client ID**, enter the **API key** from Shopify.
    - For **Client secret**, enter the **API secret key** from Shopify.
+   - For **App Redirect URL**, enter the location of your [authentication endpoint](/integrations/commerce/shopify/commerce-shopify-public-apps#build-an-app-for-merchant-authorization).
 
 4. If you requested access to over 60 days of orders and your access was approved, turn on **Has request to read all orders**. Otherwise leave this setting turned off.
 
@@ -113,11 +147,11 @@ In the Codat Portal, add the secure credentials for your Shopify app to the inte
 1. In the Codat Portal, go to the <a className="external" href="https://app.codat.io/settings/integrations/commerce" target="blank">**Commerce integrations**</a> page.
 2. Locate **Shopify** and click the toggle to enable the integration.
 
-You can also click **Manage** to view the integration's settings page, and then enable the integration from there.
+You can also click **Manage** to view the integration's settings page and then enable the integration from there.
 
 ## Check the commerce sync settings
 
-All commerce data types must be enabled before you can pull commerce transactions from Shopify to Codat. Follow the steps in [Commerce sync settings](/integrations/commerce/commerce-sync-settings); you only need to do this once.
+All commerce data types must be enabled before you can pull commerce transactions from Shopify to Codat. Follow the steps in [Commerce sync settings](/integrations/commerce/commerce-sync-settings). You only need to do this once.
 
 ## Next steps
 

docs/integrations/commerce/shopify/commerce-shopify.md

@@ -7,23 +7,19 @@ description: "Learn about our Shopify integration"
 
 With Codat's Shopify integration, you can securely retrieve your SMB customers' commerce transactions, standardized to our commerce data model.
 
-## Data type coverage
-
-View the coverage of our Shopify integration in the [Data Coverage Explorer](https://knowledge.codat.io/supported-features/commerce?view=tab-by-integration&integrationKey=fztf).
-
 ## Approaches to merchant data sharing
 
-When setting up the integration, you can take one of two approaches for enabling your merchants to connect and share their commerce data, as follows: 
+When setting up the integration, you can take one of the following two approaches for enabling your merchants to connect and share their commerce data: 
 
 - [Custom apps](/integrations/commerce/shopify/commerce-shopify-custom-apps)
 
     Created by merchants exclusively for their Shopify stores.
 
-- [Public apps](/integrations/commerce/shopify/commerce-shopify-setup)
+- [Public apps](/integrations/commerce/shopify/commerce-shopify-public-apps)
 
     Built by you and must be approved by Shopify before use. A single public app can be installed on multiple Shopify stores.
 
-In general, custom apps require less initial setup, with tasks completed by the merchant. Public apps require more initial setup, with tasks completed by you, the Codat client. Choose the option that best suits your circumstances. 
+In general, custom apps require less initial setup, with tasks completed by the merchant. Public apps require more initial setup, with tasks completed by you, the Codat client. Choose the option that best suits your circumstances.
 
 ## About custom apps
 
@@ -47,7 +43,7 @@ To get started, see [Set up Shopify using custom apps](/integrations/commerce/sh
 
 Public apps offer a low-friction way for merchants to link their commerce data to Codat. With this approach, you build a single public app and use its secure credentials to authorize your access to Shopify commerce data.
 
-_Listed apps_ are published on the Shopify app store whereas _unlisted apps_ are not. Only listed apps can be discovered directly from the app store by merchants.
+_Listed apps_ are published on the Shopify app store and _unlisted apps_ are not. Only listed apps can be discovered directly from the app store by merchants.
 
 Public apps use an OAuth 2.0 authentication flow.
 
@@ -59,20 +55,15 @@ If you choose this connection method, you need to do the following:
 
 3. If your app is approved, enter its secure credentials in the Codat Portal.
 
-If you choose this connection method, you should be aware of Shopify's requirements for public apps, as well as the specific functionality that your app will need to provide. These are outlined in [Requirements for public apps](/integrations/commerce/shopify/commerce-shopify-requirements-public-apps).
-
-To get started, see [Set up Shopify using public apps](/integrations/commerce/shopify/commerce-shopify-setup).
+You should be aware of Shopify's requirements for public apps as well as the specific functionality that your app will need to provide. To get started, see [Set up Shopify using public apps](/integrations/commerce/shopify/commerce-shopify-public-apps).
 
 ## OAuth requirements to apps
 
-If your app is not yet installed or being reinstalled, it must direct the user to their OAuth journey. To comply with this, you need a basic mapping of the Shopify store to a Codat company, which then generates a Link URL that redirects the user either to the OAUth screen, or to your app's dashboard. 
-
-![](/img/integrations/commerce/shopify/Shopify-oauth-flow.png)
+We handle this requirement for you. All we need is a redirect that can be used to [identify the merchant](/integrations/commerce/shopify/commerce-shopify-public-apps#build-an-app-for-merchant-authorization).
 
 ---
 
 ## Read next
 
 - [Set up Shopify using custom apps](/integrations/commerce/shopify/commerce-shopify-custom-apps)
-- [Set up Shopify using public apps](/integrations/commerce/shopify/commerce-shopify-setup)
-
+- [Set up Shopify using public apps](/integrations/commerce/shopify/commerce-shopify-public-apps)