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

# Shopify

> Connect your Shopify store to Ocular using a Shop ID and an Admin API access token to sync orders, customers, products, and storefront performance.

Ocular connects to Shopify and Shopify Plus stores via **OAuth** or a **Custom App**. Choose the method that suits your workflow — OAuth is faster, Custom App gives you more control over scopes.

<CardGroup cols={2}>
  <Card title="What you need" icon="key">
    **OAuth** — just your Shopify login. **Custom App** — a Shop ID (`my-store.myshopify.com`), an Admin API access token, and your Client ID & Client Secret.
  </Card>

  <Card title="What it unlocks" icon="chart-column">
    Sales Performance (D2C), the revenue side of the P\&L, customer cohorts, and discount attribution.
  </Card>
</CardGroup>

***

## <Icon icon="signs-post" /> Step 1 · Find your Shop ID (store domain)

<Steps>
  <Step title="Open Shopify Admin" icon="arrow-up-right-from-square">
    Log in to your Shopify Admin at `admin.shopify.com`.
  </Step>

  <Step title="Read the URL" icon="link">
    The browser URL looks like `admin.shopify.com/store/my-store/...`.
  </Step>

  <Step title="Copy your Shop ID" icon="copy">
    The segment after `/store/` is your Shop ID. Add `.myshopify.com` if it isn't already present — e.g., `my-store.myshopify.com`.
  </Step>
</Steps>

<Tip>
  Your Shop ID never changes, even if you rename the store. It's safe to save it once.
</Tip>

***

## <Icon icon="key" /> Step 2 · Authenticate with Shopify

Choose one of the two methods below.

<Tabs>
  <Tab title="A. OAuth (recommended)">
    The fastest way to connect — no custom app required.

    <Steps>
      <Step title="Select OAuth 2.0" icon="lock">
        In the Ocular connector setup screen, select **OAuth 2.0** as the authentication method.
      </Step>

      <Step title="Continue Setup with Shopify" icon="arrow-up-right-from-square">
        Click **Continue Setup with Shopify** to proceed to the Shopify App Store.
      </Step>

      <Step title="Authorize Ocular" icon="circle-check">
        Click **Authorize** to grant Ocular access to your Shopify account using OAuth authentication.
      </Step>

      <Step title="Save & Test" icon="flask-vial">
        Click **Save & Test** to initiate the Shopify data sync.
      </Step>
    </Steps>
  </Tab>

  <Tab title="B. Custom App">
    Create a custom app in Shopify to generate an Admin API access token.

    <Steps>
      <Step title="Log in to Shopify" icon="arrow-up-right-from-square">
        Log in to your [Shopify account](https://accounts.shopify.com/lookup).
      </Step>

      <Step title="Open Apps settings" icon="grid-2">
        On the left-hand navigation menu, click **Apps**, and then select **App and sales channel settings**.
      </Step>

      <Step title="Develop apps" icon="code">
        Click **Develop apps**. If prompted, click **Allow custom app development** and accept the terms.
      </Step>

      <Step title="Create an app" icon="plus">
        Click **Create an app**. Enter an **App name** (e.g., *Ocular Analytics*), select the appropriate **App developer** from the drop-down, and click **Create app**.
      </Step>

      <Step title="Configure Admin API scopes" icon="shield-check">
        Enable the following read permissions:

        <CardGroup cols={2}>
          <Card title="Analytics & content" icon="chart-line">
            * `read_analytics`
            * `read_content`
            * `read_locales`
            * `read_translations`
          </Card>

          <Card title="Orders & customers" icon="users">
            * `read_orders`
            * `read_draft_orders`
            * `read_customers`
            * `read_returns`
          </Card>

          <Card title="Money & finance" icon="indian-rupee-sign">
            * `read_shopify_payments_accounts`
            * `read_shopify_payments_disputes`
            * `read_shopify_payments_payouts`
          </Card>

          <Card title="Catalog & inventory" icon="boxes-stacked">
            * `read_products`
            * `read_product_listings`
            * `read_publications`
            * `read_inventory`
            * `read_locations`
            * `read_files`
            * `read_price_rules`
            * `read_discounts`
          </Card>

          <Card title="Fulfilment & shipping" icon="truck">
            * `read_merchant_managed_fulfillment_orders`
            * `read_assigned_fulfillment_orders`
            * `read_third_party_fulfillment_orders`
            * `read_fulfillments`
            * `read_shipping`
          </Card>

          <Card title="Marketing & other" icon="bullhorn">
            * `read_marketing_events`
            * `read_reports`
            * `read_resource_feedbacks`
            * `read_script_tags`
            * `read_themes`
          </Card>
        </CardGroup>

        <Note>
          The `read_gift_cards` and `read_users` scopes are available **only for Shopify Plus** accounts. To sync data from the `GIFT_CARD` and `USER` tables, contact Shopify Support to enable these scopes for your account.
        </Note>
      </Step>

      <Step title="Install the app" icon="download">
        Click **Install App**.
      </Step>

      <Step title="Copy the access token" icon="eye">
        On the **API credentials** page, copy the **Admin API access token**.

        <Warning>
          You can only view this token **once**. Save it somewhere secure. If you lose it, uninstall and reinstall the custom app to generate a new one — all previous tokens are invalidated.
        </Warning>
      </Step>
    </Steps>
  </Tab>
</Tabs>

### <Icon icon="lock" /> A. OAuth (recommended)

The fastest way to connect — no custom app required.

<Steps>
  <Step title="Select OAuth 2.0" icon="lock">
    In the Ocular connector setup screen, select **OAuth 2.0** as the authentication method.
  </Step>

  <Step title="Continue Setup with Shopify" icon="arrow-up-right-from-square">
    Click **Continue Setup with Shopify** to proceed to the Shopify App Store.
  </Step>

  <Step title="Authorize Ocular" icon="circle-check">
    Click **Authorize** to grant Ocular access to your Shopify account using OAuth authentication.
  </Step>

  <Step title="Save & Test" icon="flask-vial">
    Click **Save & Test** to initiate the Shopify data sync.
  </Step>
</Steps>

### <Icon icon="code" /> B. Custom App

Create a custom app in Shopify to generate an Admin API access token.

<Steps>
  <Step title="Log in to Shopify" icon="arrow-up-right-from-square">
    Log in to your [Shopify account](https://accounts.shopify.com/lookup).
  </Step>

  <Step title="Open Apps settings" icon="grid-2">
    On the left-hand navigation menu, click **Apps**, and then select **App settings**.

    <Frame>
      <img src="https://mintcdn.com/ocular/sW7-uz7ZirpNplo6/shopify1.png?fit=max&auto=format&n=sW7-uz7ZirpNplo6&q=85&s=a026b691459c8f02d83a4e57bab3e3b0" alt="Shopify1" width="1908" height="876" data-path="shopify1.png" />
    </Frame>

    <Frame>
      <img src="https://mintcdn.com/ocular/sW7-uz7ZirpNplo6/shopify2.png?fit=max&auto=format&n=sW7-uz7ZirpNplo6&q=85&s=d33ccc0d1b06ba6f5bd23058f937681a" alt="Shopify2" width="1917" height="849" data-path="shopify2.png" />
    </Frame>
  </Step>

  <Step title="Develop apps" icon="code">
    Click **Develop apps**. If prompted, click **Allow custom app development** and accept the terms.

    <Frame>
      <img src="https://mintcdn.com/ocular/sW7-uz7ZirpNplo6/Shopify-develop-apps.png?fit=max&auto=format&n=sW7-uz7ZirpNplo6&q=85&s=048d685ecba0c29c1bb6d48661c62ed0" alt="Shopify Develop Apps" width="1893" height="836" data-path="Shopify-develop-apps.png" />
    </Frame>
  </Step>

  <Step title="Create an app" icon="plus">
    Click **Create an app**. Enter an **App name** (e.g., *Ocular Analytics*), select the appropriate **App developer** from the drop-down, and click **Create app**.

    <Frame>
      <img src="https://mintcdn.com/ocular/sW7-uz7ZirpNplo6/shopify3.png?fit=max&auto=format&n=sW7-uz7ZirpNplo6&q=85&s=009031ce2be5a4e9375f08cc1da1cbd3" alt="Shopify3" width="894" height="495" data-path="shopify3.png" />
    </Frame>
  </Step>

  <Step title="Configure Admin API scopes" icon="shield-check">
    Enable the following read permissions:

    <CardGroup cols={2}>
      <Card title="Analytics & content" icon="chart-line">
        * `read_analytics`
        * `read_content`
        * `read_locales`
        * `read_translations`
      </Card>

      <Card title="Orders & customers" icon="users">
        * `read_orders`
        * `read_draft_orders`
        * `read_customers`
        * `read_returns`
      </Card>

      <Card title="Money & finance" icon="indian-rupee-sign">
        * `read_shopify_payments_accounts`
        * `read_shopify_payments_disputes`
        * `read_shopify_payments_payouts`
      </Card>

      <Card title="Catalog & inventory" icon="boxes-stacked">
        * `read_products`
        * `read_product_listings`
        * `read_publications`
        * `read_inventory`
        * `read_locations`
        * `read_files`
        * `read_price_rules`
        * `read_discounts`
      </Card>

      <Card title="Fulfilment & shipping" icon="truck">
        * `read_merchant_managed_fulfillment_orders`
        * `read_assigned_fulfillment_orders`
        * `read_third_party_fulfillment_orders`
        * `read_fulfillments`
        * `read_shipping`
      </Card>

      <Card title="Marketing & other" icon="bullhorn">
        * `read_marketing_events`
        * `read_reports`
        * `read_resource_feedbacks`
        * `read_script_tags`
        * `read_themes`
      </Card>
    </CardGroup>

    <Note>
      The `read_gift_cards` and `read_users` scopes are available **only for Shopify Plus** accounts. To sync data from the `GIFT_CARD` and `USER` tables, contact Shopify Support to enable these scopes for your account.
    </Note>
  </Step>

  <Step title="Install the app" icon="download">
    Click **Install App**.
  </Step>

  <Step title="Copy your credentials" icon="eye">
    On the **API credentials** page, copy three values you'll need in Ocular:

    * **Admin API access token**
    * **API key** (this is your **Client ID**)
    * **API secret key** (this is your **Client Secret**)

    <Frame>
      <img src="https://mintcdn.com/ocular/sW7-uz7ZirpNplo6/shopify--id-and-secret.png?fit=max&auto=format&n=sW7-uz7ZirpNplo6&q=85&s=8f80abf06d697b709a9962b5d02ebad0" alt="Shopify Id And Secret" width="1901" height="876" data-path="shopify--id-and-secret.png" />
    </Frame>

    <Warning>
      The Admin API access token can only be viewed **once**. Save it somewhere secure. If you lose it, uninstall and reinstall the custom app to generate a new one — all previous tokens are invalidated.
    </Warning>
  </Step>
</Steps>

***

## <Icon icon="plug" /> Step 3 · Configure the connector in Ocular

<Steps>
  <Step title="Open the connector form" icon="window">
    In Ocular, navigate to **Data Management → Connectors → Add connector → Shopify**.
  </Step>

  <Step title="Fill the fields" icon="pen-to-square">
    <CardGroup cols={2}>
      <Card title="Connector Name" icon="tag">
        Free-form label (e.g., `shopify_main`).
      </Card>

      <Card title="Connector Identifier" icon="hashtag">
        Auto-generated by Ocular.
      </Card>

      <Card title="Start Date" icon="calendar">
        YYYY-MM-DD — how far back Ocular should pull data from your Shopify store.
      </Card>

      <Card title="Lookback Days" icon="clock-rotate-left">
        The number of past days from which data will be fetched during synchronization. Default 30.
      </Card>

      <Card title="Schedule Frequency" icon="repeat">
        Numeric value + unit (e.g., 4 hours) — defines how often the connector will automatically sync data.
      </Card>

      <Card title="Shop ID" icon="link">
        `my-store.myshopify.com`
      </Card>

      <Card title="Access Token" icon="key">
        The token from Step 2 (Custom App method only).
      </Card>
    </CardGroup>
  </Step>

  <Step title="Fill the fields" icon="pen-to-square">
    <CardGroup cols={2}>
      <Card title="Connector Name" icon="tag">
        Free-form label (e.g., `shopify_main`).
      </Card>

      <Card title="Connector Identifier" icon="hashtag">
        Auto-generated by Ocular.
      </Card>

      <Card title="Start Date" icon="calendar">
        YYYY-MM-DD — how far back Ocular should pull data from your Shopify store.
      </Card>

      <Card title="Lookback Days" icon="clock-rotate-left">
        The number of past days from which data will be fetched during synchronization. Default 30.
      </Card>

      <Card title="Schedule Frequency" icon="repeat">
        Numeric value + unit (e.g., 4 hours) — defines how often the connector will automatically sync data.
      </Card>

      <Card title="Shop ID" icon="link">
        `my-store.myshopify.com`
      </Card>

      <Card title="Access Token" icon="key">
        The Admin API access token from Step 2 (Custom App method only).
      </Card>

      <Card title="Client ID" icon="id-card">
        The **API key** from your custom app's API credentials page (Custom App method only).
      </Card>

      <Card title="Client Secret" icon="key-skeleton">
        The **API secret key** from your custom app's API credentials page (Custom App method only).
      </Card>
    </CardGroup>
  </Step>

  <Step title="Select authentication method" icon="lock">
    Choose **OAuth** or **Custom App** as your authentication method. If using Custom App, enter your **Shop name** (the part before `.myshopify.com` in your Shopify URL — e.g., if your URL is `shopname.myshopify.com`, your shop name is `shopname`) and the **Admin API access token** you copied.
  </Step>

  <Step title="Select authentication method" icon="lock">
    Choose **OAuth** or **Custom App** as your authentication method. For **Custom App**, provide:

    * **Client ID** and **Client Secret** — the API key and API secret key from your custom app's API credentials page.
    * **Shop name** — the part before `.myshopify.com` in your Shopify URL (e.g., if your URL is `shopname.myshopify.com`, your shop name is `shopname`).
    * **Admin API access token** — the token you copied in Step 2.

    <Tip>
      Find your Client ID and Client Secret on the custom app's **API credentials** page, under **API key and secret key** (App development → your app → API credentials.
    </Tip>
  </Step>

  <Step title="Save & Test" icon="circle-check">
    Click **Save & Test**. Ocular will sync your data from your Shopify account. Initial historical load takes **24–48 hours**.

    <Frame>
      <img src="https://mintcdn.com/ocular/OVLTuDCFkfm2U4mW/images/image-20260406-092047.png?fit=max&auto=format&n=OVLTuDCFkfm2U4mW&q=85&s=ebdd38f531628c4f43018807895d711b" alt="Image 20260406 092047" width="1912" height="926" data-path="images/image-20260406-092047.png" />
    </Frame>
  </Step>

  <Step title="Save & Test" icon="circle-check">
    Click **Save & Test**. Ocular will sync your data from your Shopify account. Initial historical load takes **24–48 hours**.

    <Frame>
      <img src="https://mintcdn.com/ocular/sW7-uz7ZirpNplo6/shopify-connected.png?fit=max&auto=format&n=sW7-uz7ZirpNplo6&q=85&s=e1e0ecba8079c4df8f0cb7d9053d814f" alt="Shopify Connected" width="1495" height="801" data-path="shopify-connected.png" />
    </Frame>
  </Step>
</Steps>

***

## <Icon icon="life-ring" /> Troubleshooting

<AccordionGroup>
  <Accordion title="Token isn't accepted" icon="triangle-exclamation">
    Re-copy the token — there's a high chance of an accidental leading/trailing space. If that fails, uninstall and reinstall the custom app, then generate a fresh token. All previous tokens are invalidated.
  </Accordion>

  <Accordion title="Missing orders beyond 60 days" icon="clock-rotate-left">
    `read_orders` alone caps at 60 days of history. To pull further back, request **`read_all_orders`** from the Shopify Partner Dashboard, then re-enable it in the custom app's scopes.
  </Accordion>

  <Accordion title="Permission error during sync" icon="user-shield">
    Open the custom app's **Configuration → Admin API access scopes** and confirm every scope above is enabled. After enabling additional scopes, you must click **Save** — Shopify won't re-issue the token, the same one will start working with the new permissions.
  </Accordion>
</AccordionGroup>

<Note>
  For ticket-writing format when filing a connector issue, see [Working with the Ocular team → Connector-not-working tickets](/overview/working-with-the-ocular-team).
</Note>