# Shopify

> Bring orders, products, customers, inventory and the rest of your Shopify store into your warehouse.

## Before you start

sanda reads your store through an app that you create in Shopify and install on the store. The app's Admin API access token is what you give sanda.

- **Admin access to the store.** You need to be able to create and install an app on the store.
- **An app with read access.** In your Shopify admin, open **Settings**, then **Apps and sales channels**, then **Develop apps**, and create an app. Grant it read scopes for the data you want in sanda, such as orders, products, customers and inventory, then install it. Shopify changes where apps are created from time to time. If you cannot find this screen, follow Shopify's current instructions for creating an app with Admin API access to your own store.
- **The Admin API access token.** Shopify reveals it when you install the app, and shows it once, so copy it straight away. It starts with `shpat_`.

Shopify shows an app only the last 60 days of orders unless the app also has the `read_all_orders` scope. Add that scope before you install if you want older order history.

## Connect Shopify

:::steps
1. **Choose Shopify.** Go to **Data · Connections**, press **New connection** and pick **Shopify**.
2. **Name the store.** Enter the part of your store's address before `.myshopify.com` in **Shopify Store**. If your address is `my-store.myshopify.com`, enter `my-store`. You can also paste the full address.
3. **Choose API Password.** **Shopify Authorization Method** sits under **Advanced settings** and opens on **OAuth2.0**. None of its fields is required, so the form does not stop you if you leave them empty. Change it to **API Password** and paste the Admin API access token into **API Password**.
4. **Choose how far back to load.** **Replication Start Date** opens on 2020-01-01. Enter a date as `YYYY-MM-DD`. Data before it is not replicated.
5. **Continue.** Press **Continue**, name the connection, and press **Read schema**. sanda signs in and lists the Shopify objects it can read. If it fails, the message says why. See [Troubleshoot connections](https://docs.sanda-os.com.au/connections/troubleshooting).
:::

The rest of the flow, naming the connection, setting a frequency and choosing streams, is the same for every source. See [Add a connection](https://docs.sanda-os.com.au/connections/add-a-connection).

The **OAuth2.0** option asks for a **Client ID**, a **Client Secret** and an **Access Token**. Use it only if you connect through a Shopify app that issues those.

## What syncs

Shopify's objects each become a stream, and land in your warehouse as their own tables: orders, products, customers, inventory levels, locations, fulfilments, discount codes and abandoned checkouts among them. The stream list shows everything the app can read, so a scope you did not grant means a stream you will not see. See [choose what to sync](https://docs.sanda-os.com.au/connections/choose-streams).

## Tips

- **Add scopes before you need them.** Scopes are fixed when the app is installed. Adding one later means updating the app in Shopify and, if Shopify asks, installing it again.
- **Read the big streams incrementally.** Orders and customers grow fast. After the first run, switch them to an incremental mode. See [sync modes](https://docs.sanda-os.com.au/connections/sync-modes).
- **Catch late changes.** **Lookback Window (in Days)** re-reads records from the past N days on each incremental run, to pick up records that arrived late. It opens on 0, which means no lookback.
- **One connection per store.** For several stores, add a connection for each and give each a distinct name. The name decides the tables the rows land in.

## Configuration fields

What the connection form asks for. Required fields are marked; the rest are optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| **Shopify Store** | string | Yes | The name of your Shopify store found in the URL. For example, if your URL is https://NAME.myshopify.com, then the name is 'NAME'. You may also paste the full myshopify URL (e.g. https://NAME.myshopify.com) and it will be normalized automatically. |
| **Shopify Authorization Method** | one of 2 options | No | The authorization method to use to retrieve data from Shopify. |
| **Replication Start Date** | string | No | The date you would like to replicate data from. Format: YYYY-MM-DD. Any data before this date will not be replicated. Default `2020-01-01`. |
| **GraphQL BULK Date Range in Days** | integer | No | Defines what would be a date range per single BULK Job. Default `30`. |
| **Add `user_id` to Transactions (slower)** | boolean | No | Defines which API type (REST/BULK) to use to fetch `Transactions` data. If you are a `Shopify Plus` user, leave the default value to speed up the fetch. Default `false`. |
| **Include Closed Fulfillment Orders** | boolean | No | If enabled, the `Fulfillment Orders` stream includes closed fulfillment orders. Shopify excludes closed orders by default. Default `false`. |
| **BULK Job checkpoint (rows collected)** | integer | No | The threshold, after which the single BULK Job should be checkpointed (min: 15k, max: 1M). Default `100000`. |
| **Add `Presentment prices` to Product Variants** | boolean | No | If enabled, the `Product Variants` stream attempts to include `Presentment prices` field (may affect the performance). Default `true`. |
| **BULK Job termination threshold** | integer | No | The max time in seconds, after which the single BULK Job should be `CANCELED` and retried. The bigger the value the longer the BULK Job is allowed to run. Default `7200`. |
| **Lookback Window (in Days)** | integer | No | If set to a positive number, during each incremental sync the connector will re-fetch records from the past N days before the saved state. This helps capture records that may have been missed due to race conditions or late-arriving data. The default value of 0 means no lookback and preserves existing behavior. Default `0`. |
| **Populate top-level customer fields in Orders** | boolean | No | Populate the top-level customer_* fields in Orders from the customer object. When disabled, these fields contain null. The original customer object is retained in both modes. Default `false`. |

### Shopify Authorization Method

The authorization method to use to retrieve data from Shopify.

Choose one of the following. Each asks for its own fields.

**OAuth2.0**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| **Client ID** | string, secret | No | The Client ID of the Shopify developer application. |
| **Client Secret** | string, secret | No | The Client Secret of the Shopify developer application. |
| **Access Token** | string, secret | No | The Access Token for making authenticated requests. |

**API Password**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| **API Password** | string, secret | Yes | The API Password for your private application in the `Shopify` store. |


## Related

:::links
- [Sync modes](https://docs.sanda-os.com.au/connections/sync-modes): How sanda reads each stream on every run.
- [Sync schedules](https://docs.sanda-os.com.au/connections/schedules): How often a connection runs.
- [Allowlist sanda’s address](https://docs.sanda-os.com.au/connections/allowlist): For a system behind a firewall.
- [Troubleshoot connections](https://docs.sanda-os.com.au/connections/troubleshooting): What an error means and how to fix it.
:::