1.0 Overview

PaiPai has simplified the process for businesses, regardless of their size, to seamlessly integrate with Shopify, one of the world's largest e-commerce platforms. Thanks to this collaboration, Shopify users can effortlessly link up with the Open Network for Digital Commerce (ONDC) via PaiPai, enabling them to start selling on ONDC with ease. This partnership serves as a seamless bridge that empowers Shopify businesses to broaden their online presence.

Within their Shopify accounts, users can easily configure various aspects such as products, product groups, categories, and outlets. 

As a result of this integration, any modifications made within the Shopify account will be promptly synchronized with the PaiPai system, which, in turn, will update the corresponding ONDC listings accordingly.

1.1 Conditions

For you to proceed with the Integration, certain Conditions must be met.

1. You must have your Shopify Account already created. If you haven’t please complete your Account Creation.

2. You must have your PaiPai Account already created. If you haven’t please complete your Account Creation.

Once you have created both of these Accounts, you can proceed with Integrations.

1.2 How does this work?

PaiPai now allows Upstream APIs to integrate with various e-commerce platforms. 

The integration with PaiPai and Shopify is facilitated by the API key and the configured endpoints.

Webhooks can be configured within the Shopify account for various account operations.

Operations can be related to Orders, Products, Customers, Carts, Inventory, etc

Some of the examples of these operations are below

Orders

These operations are used to sync the data related to Orders from creation to fulfillment and cancelation into the PaiPai system. In a way, you are synchronizing the Order management of Shopify with the PaiPai system and vice-versa.

Examples: Order Creation, Order Edit, Order Cancellation, Order update, Fulfillment Update, etc

Products

These operations are used to sync the data related to your Catalog and products, from creation to editing and deletion of products in the catalog. 

Examples: Product Creation, Product Edit, Product Deletion, etc

Customers

These operations are used to sync the information related to the Customers that are acquired through various channels.

Examples: Customer creation, Customer Edit, Customer Deletion, Customer Enable, Customer Disable, etc.

Similarly, there are operations for Carts, Checkouts, Locations, etc.

Once these webhooks are properly configured, assume that you created a new product in your Shopify Account, the product will instantly reflect in your PaiPai system, which you can check through the logs.

1.3 Requirements

To enable this seamless integration and proper synchronization between both platforms, there are a few things needed from the Client’s Shopify account to set up the PaiPai Account for the Integration

1. Account URL

You can find this URL by navigating into the Customer Accounts Module on the left side panel of the settings page.

Scroll down to navigate to Classic Customer Accounts under which you will find a URL. You can Copy that URL

The Account URL cannot be used for Configuration of End Points. It can only be used to configure the Custom Headers.

2. Domain URL

To obtain this URL, you need to navigate to the Domains Module on the leftside panel of the settings page.

You can find the URL under the Domain Panel. 

This is the Domain URL and it is used to configure the Order push endpoint for the integration

3. API Access Token

API Access token is required to configure the Customer Headers in the PaiPai Account. To obtain this API Access Token

To obtain this, go to the settings page in the Shopify Account

Click on Apps and Sales Channels Module on the left side panel.

On the top-right corner of the screen, Click on Develop Apps Button

We will need an App with the name PaiPai ONDC created. If it is already created, Click on the app in the list below.

In the App Screen, click on the API Credentials Tab where you can find API Access Token. 

Be careful as it can only be viewed once and cannot be accessed again.

Copy the Access token for further use in the configuration

If the App is no there, you need to create a new app.

Click on the Create App Button on the top-right corner.

In the popup, enter the name of the App as PaiPai ONDC

Click on the Create App  button.

Now, you need to Configure the Access Scopes.

Click on the Configure Admin API Access Scopes Button. Here you need to manually tick mark Access scopes

Once you select the Access scopes, Click on the Save button

Now the Install App button will be highlighted.

Click on Install App

Once the App is Installed, Click on API Credential tab, where you can find the API Access Token.

Copy it for further use.

Webhooks Configuration

Webhooks are another important component in making sure the sync between the two platforms is working.

Without webhooks, the data will not be exchanged between both platforms. The Webhooks for various events need to be shared by the PaiPai team with the Client.

The Client needs to configure them in the Shopify Account

For the configuration

Navigate to the Notifications Module in the Settings Page

Scroll down and navigate to find the Webhooks Section

Click on the Create Webhook button.

Select the Event from the dropdown

Add the Webhook URL given by the PaiPai team

Click on Save

Webhook will be created. In the same way, Configure the remaining Webhooks.

Here is an example of the events and the webhooks that need to be configured

Once these three configurations are done. We can proceed forward with the Integration.

If all these requirements are fulfilled we can proceed forward with the Integration

2.0 Integration Process

2.1 Upstream Provider Settings

The first step in the Integration process is to ensure that the upstream provider for the account is set to Shopify on the PaiPai System

• Navigate to the Accounts Module on the Left-side Panel

• Click on Accounts Option

You will be able to see a list of all the Accounts in the PaiPai system

• Click on the Account that you are performing the Integration for.

You can find the Account by scrolling down the list or you can use the search bar.

• Click on the Edit Button in the Overview Panel

• Scroll down to find the Upstream Provider Dropdown under the Details Panel

• If the Upstream Provider is not set up to Shopify, Click on the dropdown and Select Shopify

2.2 Get the Domain URL, Account URL, API Access Token and help the Client finish the Webhook Configuration

For this step, you need to share an email with the Client with a clear step-by-step guide on how they could find the URL, Access Token, and how they can finish the configuration.

You can find the template along with the guide below. Do not change anything other than the client’s name and send the email.

Email template:

Subject: Request for Account URL,Domain URL, API Access Token and Webhook Configuration for PaiPai Integration

Dear [Client’s Name],

I hope this email finds you well. To complete the integration process between your Shopify account and PaiPai Account, we require your Shopify account’s Account URL and API Access Token. We also need you to Configure the required webhooks in your Shopify Account.

Here is a step-by-step guide to assist you in finishing the process

Account URL

Step 1: Log in to your Shopify Account

Step 2: Open Settings

Step 3: Click on the Customer Accounts Module on the left-side panel of the Settings tab

Step 4: Scroll down until you see the Classic Customer Accounts Section

Step 5: Copy the URL

That is the URL we need for the Configuration

Domain URL

Step 1: Open Settings

Step 2: Click on Domains Module on the left-side panel of the Settings tab

Step 3: Find the URL under the Domain Section

That is the Domain URL we need for the Configuration of Order push status endpoint

API Access Token

Step 1: Go to the settings page in the Shopify Account

Step 2: Click on Apps and Sales Channels Module on the left side panel.

Step 3: On the top-right corner of the screen, Click on Develop Apps Button

We will need an App with the name PaiPai ONDC created. If the App is already created Click on the App and proceed forward to Step 11, If not create the App with the following steps

Step 4: Click on the Create App Button in the top-right corner.

Step 5: In the popup, enter the name of the App as PaiPai ONDC

Step 6: Click on the Create App  button.

Now, you need to Configure the Access Scopes.

Step 7: Click on the Configure Admin API Access Scopes Button. Here you need to manually tick mark Access scopes

Step 8: Once you select the Access scopes, Click on the Save button

Step 9: Now the Install App button will be highlighted.

Step 10: Click on Install App

Step 11: Click on the API Credential tab, where you can find the API Access Token.

In the App Screen, click on the API Credentials Tab where you can find API Access Token. 

Be careful as it can only be viewed once and cannot be accessed again.

Webhooks

Step 1: Navigate to the Notifications Module in the Settings Page

Step 2: Scroll down and navigate to find the Webhooks Section

Step 3: Click on the Create Webhook button.

Step 4: Select the Event from the dropdown

Step 5: Add the Webhook URL given by the PaiPai team

Step 6; Click on Save

Webhook will be created. Following these steps, you need to create the following webhooks

[Add the list of webhooks along with the URLs]

By following these steps, you should have successfully obtained the URL, Access Token, and configured your system accordingly. If you encounter any issues or have questions along the way, please don't hesitate to reach out to our support team.

We hope you can send us these details to [email] as soon as possible so that we can complete the configuration process.

Best Regards,

[Your Name]

[Your Postiion]

[Contact info]

Once you receive all these details from the customer you can proceed with the next step.

2.3 Configure the Order Status Push End Point

Now that you have the Domain URL, you need to configure the Order Status Push End Point for the PaiPai Account

https-development-5103.myshopify.com

• Once you have the base URL, format the Order Push Status Endpoint

Format : https://shopify Domain URL/admin/api/2023-07/orders.json

This is how the endpoint should be formatted. So, the properly formatted endpoint should look something like this

https://https-development-5103.myshopify.com/account/admin/api/2023-07/orders.json

• Navigate to the Accounts Module on the Left-side Panel

• Click on Accounts Option

You will be able to see a list of all the Accounts in the PaiPai system

• Click on the Account that you are performing the Integration for.

You can find the Account by scrolling down the list or you can use the search bar.

• Click on the Edit Button in the Overview Panel

• Enter the Formatted Order Status Push End Point

The endpoint is now configured.

Click on Update to Save the settings

2.4 Configure the Custom Headers

To Configure the Customer Headers, you will need the API Access Token and account URL from the Client’s Shopify Account

Once you obtain the Access token and URL, here is you can Configure it in the PaiPai system

• Format the Custom Headers in JSON format

The Format would be like this

Format: {"X-Shopify-Access-Token":  “API ACCESS TOKEN”,,  "Content-Type": "application/json", "up_config_item_pull_url": "Shopify Account URL/admin/api/2023-07/"}

Once you format it properly, the Customer Headers should look like this

{"X-Shopify-Access-Token":  "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",  "Content-Type": "application/json", "up_config_item_pull_url": "https://https-development-5103.myshopify.com/account/admin/api/2023-07/"}

• Navigate to the Accounts Module on the Left-side Panel

• Click on Accounts Option

You will be able to see a list of all the Accounts in the PaiPai system

• Click on the Account that you are performing the Integration for.

You can find the Account by scrolling down the list or you can use the search bar.

• Click on the Edit Button in the Overview Panel

• Enter the Formatted Custom Headers in the field and Click on Update

The Custom Headers are now Configured.

After the Configuration, ensure that the Client has already created the Locations (Outlets) and Catalog items within the Shopify Account. If not, please let them create the locations and outlets in their account.

Location set up in Shopify: https://help.shopify.com/en/manual/locations/setting-up-your-locations

Products set up in Shopify:

https://help.shopify.com/en/manual/products/add-update-products 

2.5 Set up Initial Catalog

Once the Configuration is finished, we need to set up the Initial catalog

With this process, the locations and items in the Client’s Shopify account will Automatically sync with the newly integrated PaiPai Account.

You do not need to manually add any of the locations and catalog items from PaiPai side.

To set up this

• Navigate to the Accounts Module on the Left-side Panel

• Click on Accounts Option

You will be able to see a list of all the Accounts in the PaiPai system

• Click on the Account that you are performing the Integration for.

You can find the Account by scrolling down the list or you can use the search bar.

• In the Account Overview screen, Click on the Actions Dropdown on the top-right corner

• Select Set up Initial Catalog Option

• Click on Confirm

2.6 Verification of Catalog Set-up

Once the Initial Catalog setup is done, all the locations and items will be synched with the PaiPai Account from the Shopify Account.

You can verify if the Sync has any problems through the following process.

• Switch to the Client’s PaiPai Account

Click on Accounts on the System side>> Switch Account>> Enter the Client Account Name>> Select Group User>> Select ID and Click on Switch at the top-right corner.

Checking the Outlets

• Navigate to the Business Module on the left-side panel

• Click on Outlets

• All the outlets that are added to the Shopify account should be here

Checking the Items for the Outlet

• In the Outlets screen, click on any outlet

• Click on Items Tab

• You will be able to see all the Items associated with this particular outlet

Checking the items for the Account

• Navigate to the Products Module on the left-side panel

• Click on Items

• Here you can see all the items that are now linked to this account

Checking the Events

From the above three processes, you can compare the items and outlets directly with the Shopify account. But if there are many outlets and items it is impossible to verify one by one. So, in such case, you can verify it with the Upstream Events and Logs

• Navigate to the Upstream Module on the left-side panel

• Click on Events

You can see the list of all the Events that are performed respective to this account. The top Event would be the most recent. In this case, it should be the Initial catalog setup event.

• Scroll to the side and Check the Status Column

If the catalog is successfully pulled, the status will show success.If the status is Pending, then the process is happening.  If there are any discrepancies, the status will show Crashed. 

• In case the event is crashed, click on the Event ID of the particular event.

• You will be redirected to the Event details page

• Go to Actions dropdown on the top-right corner and click on Download JSON.

You can check where the error is happening and try to fix it

2.7 Store Setup

After the Outlets and items are added, you can now enable the outlets

• Go to the Admin Module on the left-side panel

• Click on the Staff option

• You can see the account that you are currently using now.

• Click on the Staff ID

• In the general info tab, Click on the Edit Option on the top right norner

• In the stores panel, enable All Stores

• Click on Update

Now the Stores are properly set up

You can also add Outlets to this account to access each outlet individually

For this

• Go to Admin Module on the left-side panel

• Click on the Staff option

• You can see the account that you are currently using now

• Click on the Staff ID

• Click on the Outlets Tab

• Click on Add Outlets 

• From the Merchants Dropdown select the Outlet

• From the Role Dropdown add a role

• Click on the Add Button

You can access this outlet POS by clicking on the Switch to POS button on the Header

Click on the Switch to POS

• Select the Outlet 

• You can now see the POS of the particular outlet that you selected

2.8 Configure C Taxonomy and G Taxonomy

Now you need to go back to the System side.

• Go to Accounts Module 

• Click on the Accounts Option

• Click on the Account that you are integrating

• In the Account Details screen click on the C Taxonomy Tab and Map the C Taxonomy

• After configuring the C Taxonomy Click on the G Taxonomy

Click on the Actions dropdown on the top-right.

Select Sync Product Catalog to Master

Then go to ONDC add the new account under ONDC and follow the ONDC flow

2.9 Configuring for ONDC

• Go to ONDC Module on the Left-side Panel

• Click on Accounts

You will see the list of all the Accounts

• Click on Add to ONDC Button on the top-right Corner

You will see a pop-up screen with entry fields

• Enter the Details

• Click on Add Button

The Account will be added to the ONDC and you can see it in the list of Accounts

• Click on the Account to see the general info of the Account

• Click on the Outlets tab

• Map the Outlet

• Now Click on the Items tab

• Click on the Actions Dropdown and select Map all

The account is added to ONDC, and all the products and outlets are synced.

2.10 Order Relay Verification

Now that the account is properly integrated, verify if the orders are reflecting on the Shopify account when the orders are taken through the PaiPai

Here is the process for the verification

Place an Order from POS

Switch to the POS from your Account

Go to POS Module on the left-side panel and click on POS option

Create an Order

The Order will be reflected in your OMS Module

At the same time, the order will be reflected in Shopify

To check that:

Go to your Shopify Account

Click on the Orders Module on left side panel. You can see the list of all the orders placed there.

3.0 FAQs

1.  What is the purpose of the integration between PaiPai and Shopify in terms of catalogs?  

   - The integration between PaiPai and Shopify is designed to synchronize product catalogs between the two platforms seamlessly, allowing changes in one platform to reflect in the other.

2.  What are the key conditions that must be met before proceeding with the integration? 

  - Before proceeding with the integration, you must have an existing Shopify account and a PaiPai account. Both accounts need to be created and ready for integration.

3.  How does the synchronization of product catalogs work between Shopify and PaiPai? 

   - The synchronization is facilitated by webhooks configured in the Shopify account. Changes related to products, such as creation, editing, and deletion, are monitored and promptly reflected in the PaiPai system.

4.  What are some examples of operations related to product catalog synchronization between Shopify and PaiPai? 

   - Examples of operations include product creation, product editing, and product deletion.

5.  What information is synchronized regarding customers in the integration process? 

   - The integration also synchronizes customer-related information, including customer creation, editing, deletion, enabling, and disabling.

6.  What are the requirements for the Client's Shopify account to set up the PaiPai Account for integration? 

   - The requirements include obtaining the Account URL, Domain URL, and API Access Token from the Shopify account. Additionally, the client needs to configure webhooks in their Shopify account.

7.  How can clients configure the required webhooks in their Shopify account for integration? 

   - Clients can configure webhooks by navigating to the Notifications Module in the Shopify Settings Page, selecting the desired event, and adding the Webhook URL provided by the PaiPai team.

8.  What is the purpose of the Order Status Push Endpoint configuration, and how is it done? 

   - The Order Status Push Endpoint is configured to ensure that order status changes are promptly reflected. It is formatted using the Domain URL and API Access Token, following a specific format.

9.  How can clients configure custom headers in the PaiPai system, and why is it necessary? 

   - Custom headers are configured using the API Access Token and account URL obtained from the client's Shopify account. These headers are essential for proper communication and data exchange between the two platforms.

10.  What is the purpose of the "Set up Initial Catalog" step, and how does it work? 

    - The "Set up Initial Catalog" step ensures that the client's locations and catalog items in Shopify are automatically synchronized with the newly integrated PaiPai account, eliminating the need for manual entry.

11.  How can clients verify the successful setup of the catalog, outlets, and items after the initial catalog setup? 

    - Clients can verify the setup by checking the outlets, items, and events in their PaiPai account. They can also compare the data with their Shopify account and identify any discrepancies.

12.  What is the purpose of the "Store Setup" step, and how is it done? 

    - The "Store Setup" step involves enabling outlets in the PaiPai system to access each outlet individually. It ensures that the outlets are properly set up for operations.

13.  How can clients configure C Taxonomy and G Taxonomy in the PaiPai system, and why is it necessary? 

    - Clients can configure C Taxonomy and G Taxonomy in their PaiPai account to categorize and map products effectively, making it easier to manage and sell products.

14.  What is the purpose of the "Order Relay Verification" step, and how is it done? 

    - The "Order Relay Verification" step is used to confirm that orders placed through the PaiPai system are reflected in the Shopify account. It involves placing an order from the Point of Sale (POS) and checking its appearance in both systems

15.  How can clients check if orders placed through PaiPai are reflected in their Shopify account? 

    - Clients can check by navigating to their Shopify account and clicking on the Orders Module, where they should see a list of orders, including those placed through PaiPai.

4.0 Troubleshooting

 1. Issue:  The integration process is not progressing, and you are unable to proceed with the setup.

    Solution:  

   - Ensure that you have met the necessary conditions, including having an existing Shopify account and a PaiPai account. Both accounts should be properly created and ready for integration.

   - Double-check that you have obtained the required Account URL, Domain URL, and API Access Token from the Shopify account.

   - Confirm that webhooks are correctly configured in the Shopify account and associated with the relevant events.

 2. Issue:  Webhooks are not working, and data is not being exchanged between Shopify and PaiPai.

    Solution:  

   - Review the webhooks configuration in the Shopify account and ensure that the Event is correctly selected and the Webhook URL provided by PaiPai is accurate.

   - Verify that webhooks are active and properly saved in the Shopify account.

   - Check if there are any restrictions or security settings in the Shopify account that might prevent webhook communication.

 3. Issue:  The Order Status Push Endpoint is not properly configured, and order status changes are not being reflected in the PaiPai system.

    Solution:  

   - Carefully follow the provided steps to configure the Order Status Push Endpoint. Ensure that the Domain URL and API Access Token are correctly formatted in the endpoint.

   - Double-check that the Order Status Push Endpoint is properly saved and updated in the PaiPai account.

 4. Issue:  Custom headers are not configured correctly in the PaiPai system.

    Solution:  

   - Use the provided format to structure the custom headers properly, including the API Access Token and Shopify Account URL.

   - Ensure that the headers are accurately formatted in JSON format.

   - Double-check that the Custom Headers field in the PaiPai account is correctly updated with the formatted headers.

 5. Issue:  The Initial Catalog setup is not working as expected, and data is not syncing between Shopify and PaiPai.

    Solution:  

   - Confirm that the client has already created locations (outlets) and catalog items within their Shopify account. If not, encourage them to do so according to Shopify guidelines.

   - Review the Initial Catalog setup steps and verify that the "Set up Initial Catalog" option is properly selected in the PaiPai account.

   - Check for any errors or discrepancies in the initial catalog setup event by examining the event logs.

 6. Issue:  Orders placed through PaiPai are not reflecting in the Shopify account as expected.

    Solution:  

   - Ensure that the Order Relay Verification steps are followed accurately.

   - Verify that the order is properly created and reflected in the PaiPai OMS Module.

   - Double-check the Shopify Orders Module to confirm if the order appears there. If not, investigate the event logs for potential issues.