> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.zenskar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Shopify

## Overview

[Shopify](https://www.shopify.com/) is a leading e-commerce platform that enables businesses to create and manage online stores, process orders, and handle payments. In Zenskar, you can use Shopify as a data source to import order, product, and customer data for metering, billing, and analytical reporting.

The connector supports both **REST** and **GraphQL** APIs, allowing you to access a wide range of Shopify resources efficiently and keep your billing data continuously in sync with your store’s operations.

***

Would you like me to make it slightly more technical (e.g., mention sync modes, OAuth, bulk API support)?

## Prerequisites

* [An active Shopify store](https://www.shopify.com/).
* [Request access to your client's store](https://help.shopify.com/en/partners/dashboard/managing-stores/request-access#request-access), if you are syncing data from a store that you do not own (not required for account owners).
* A custom Shopify application with [`read_` scopes enabled](https://docs.zenskar.com/docs/data-source-connector-for-shopify#custom-app-scopes).

***

## Set up a Shopify data-source connector via Zenskar dashboard

1. Log into your Zenskar dashboard.
2. In the left side bar, click **Usage > Data Sources**.
3. In the top-right corner, click **+ ADD DATA SOURCE**.
4. On the **Add New Data Source** page, [configure the connector](https://docs.zenskar.com/docs/data-source-connector-for-shopify#connector-configuration).
5. Click on the **SAVE SOURCE** button.

### Connector configuration

#### General configuration

| Field           | Description                                | Required |
| :-------------- | :----------------------------------------- | :------- |
| **Source Name** | Enter a unique name for this data source.  | Yes      |
| **Source Type** | Select **Shopify** from the dropdown menu. | Yes      |

#### Connector configuration

| Field                                      | Description                                                                                                                                                          |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Shopify Store**                          | Enter your **Shopify store name**.                                                                                                                                   |
| **Shopify Authorization Method**           | Choose how you want to authorize API requests: **OAuth 2.0** or **API Password**. Depending on your choice, fill in the required fields listed below.                |
| **Replication Start Date**                 | Defaults to **01 January 2020**. Set a start date for data replication. Records created before this date will not be synced.                                         |
| **Add `user_id` to Transactions (slower)** | Defines which API type (**REST** or **BULK**) is used to fetch `Transactions` data. For **Shopify Plus** users, keep the default value to optimize sync performance. |

<Callout icon="🚧" theme="warn">
  You must complete the corresponding conditional table below based on the **Shopify Authorization Method** you choose.
</Callout>

#### OAuth 2.0 authorization configuration

* To retrieve your **Client ID** and **Client Secret**: [About client secrets](https://shopify.dev/docs/apps/build/authentication-authorization/client-secrets).
* To generate your **Admin API Access Token**: [Generate access tokens for custom apps in the Shopify admin](https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens/generate-app-access-tokens-admin).

<Callout icon="🚧" theme="warn">
  These fields are required only if **Shopify Authorization Method** is set to **OAuth 2.0**.
</Callout>

| Field             | Description                                   |
| ----------------- | --------------------------------------------- |
| **Client ID**     | The client ID of your Shopify custom app.     |
| **Client Secret** | The client secret of your Shopify custom app. |
| **Access Token**  | The Admin API access token for your store.    |

#### API Password authorization configuration

<Callout icon="🚧" theme="warn">
  These fields are required only if **Shopify Authorization Method** is set to **API Password**.
</Callout>

| Field            | Description                                   |
| ---------------- | --------------------------------------------- |
| **API Password** | The API password for your Shopify custom app. |

***

## Addendum

### Custom app scopes

Add the following scopes to your Shopify custom app to allow Zenskar to sync all available data.
For more information about access scopes, refer to the [Shopify documentation](https://shopify.dev/docs/api/usage/access-scopes).

| Scope                                      | Description                                             |
| ------------------------------------------ | ------------------------------------------------------- |
| `read_analytics`                           | Access analytics data.                                  |
| `read_assigned_fulfillment_orders`         | Access assigned fulfillment orders.                     |
| `read_content`                             | Access online store content such as articles and blogs. |
| `read_customers`                           | Access customer data.                                   |
| `read_discounts`                           | Access discount details.                                |
| `read_draft_orders`                        | Access draft orders.                                    |
| `read_fulfillments`                        | Access fulfillment data.                                |
| `read_gdpr_data_request`                   | Access GDPR-related data requests.                      |
| `read_gift_cards`                          | Access gift card information.                           |
| `read_inventory`                           | Access product inventory data.                          |
| `read_legal_policies`                      | Access store legal policies.                            |
| `read_locations`                           | Access location data.                                   |
| `read_locales`                             | Access localization information.                        |
| `read_marketing_events`                    | Access marketing event data.                            |
| `read_merchant_managed_fulfillment_orders` | Access merchant-managed fulfillment orders.             |
| `read_online_store_pages`                  | Access online store pages.                              |
| `read_order_edits`                         | Access order edits.                                     |
| `read_orders`                              | Access order information.                               |
| `read_price_rules`                         | Access price rules.                                     |
| `read_product_listings`                    | Access product listings.                                |
| `read_products`                            | Access product data.                                    |
| `read_publications`                        | Access publications.                                    |
| `read_reports`                             | Access reports.                                         |
| `read_resource_feedbacks`                  | Access feedback on resources.                           |
| `read_script_tags`                         | Access script tags.                                     |
| `read_shipping`                            | Access shipping information.                            |
| `read_shopify_payments_accounts`           | Access Shopify Payments account information.            |
| `read_shopify_payments_bank_accounts`      | Access bank account details for Shopify Payments.       |
| `read_shopify_payments_disputes`           | Access dispute data for Shopify Payments.               |
| `read_shopify_payments_payouts`            | Access payout data for Shopify Payments.                |
| `read_themes`                              | Access themes and related assets.                       |
| `read_third_party_fulfillment_orders`      | Access third-party fulfillment orders.                  |
| `read_translations`                        | Access store translations.                              |

### Supported sync modes

The Shopify source supports both **Full Refresh** and **Incremental** sync modes. You can configure the connector to either copy only new or updated data, or replicate all rows in the selected tables and columns each time a sync runs.

This source can sync data using the following Shopify APIs:

* [Shopify REST API](https://shopify.dev/api/admin-rest)
* [Shopify GraphQL API](https://shopify.dev/api/admin-graphql)
* [Shopify GraphQL Bulk API](https://shopify.dev/docs/api/usage/bulk-operations/queries)

***

Would you like it phrased more technically (for engineers) or in a slightly simpler tone (for general users)?

### Rate limiting

🚧 Shopify has [rate limit restrictions](https://shopify.dev/concepts/about-apis/rate-limits) . In some edge cases, you may encounter the following warning message:

```
"Caught retryable error '<some_error> or null' after <some_number> tries. Waiting <some_number> seconds then retrying..."
```

This is expected when the connector hits a `429 - Rate Limit Exceeded` HTTP error. The sync operation will continue successfully after a short backoff period. These [limitations are applied to all Shopify GraphQL bulk API requests](https://shopify.dev/docs/api/usage/bulk-operations/queries#operation-restrictions) .

### Capturing deleted records

The connector captures [record deletions](https://shopify.dev/docs/api/admin-rest/2024-04/resources/event) in the `Articles`, `Blogs`, `CustomCollections`, `Orders`, `Pages`, `PriceRules` and `Products` streams.

When a record is deleted, the connector outputs a record with the `ID` of that record and the `deleted_at`, `deleted_message`, and `deleted_description` fields filled out. No other fields are filled out for the deleted records.

### Access errors

🚧 If you encounter access errors while using OAuth 2.0 authentication, ensure you've [requested access to the client’s store](https://help.shopify.com/en/manual/your-account/staff-accounts/staff-permissions) as described in the Shopify documentation. Once access is granted, you can proceed with OAuth 2.0 authentication.