Skip to main content

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.

Ocular connects to Shopify and Shopify Plus stores using two credentials — your Shop ID and an Admin API access token from a custom app you create. The whole flow takes about 5 minutes.

What you need

Shop ID (my-store.myshopify.com) and an Admin API access token from a custom app.

What it unlocks

Sales Performance (D2C), the revenue side of the P&L, customer cohorts, and discount attribution.
Shopify connector form placeholder

​
Step 1 · Find your Shop ID (store domain)

Open Shopify Admin

Log in to your Shopify Admin at admin.shopify.com.

Read the URL

The browser URL looks like admin.shopify.com/store/my-store/....

Copy your Shop ID

The segment after /store/ is your Shop ID. Add .myshopify.com if it isn’t already present — e.g., my-store.myshopify.com.
Your Shop ID never changes, even if you rename the store. It’s safe to save it once.

​
Step 2 · Generate an Admin API access token

Open Settings

In Shopify Admin, click Settings at the bottom of the dashboard.

Apps and sales channels → Develop apps

Navigate to Apps and sales channels and click Develop apps. If prompted, click Allow custom app development and accept the terms.

Create an app

Click Create an app, name it (e.g., Ocular Analytics), and click Create app.

Configure Admin API scopes

On the Configuration tab, click Configure in the Admin API Integration section, then enable these read permissions:

Orders & customers

  • read_orders (also request read_all_orders from Shopify Partner Dashboard for history beyond 60 days)
  • read_customers
  • read_returns

Money & finance

  • read_shopify_payments_payouts
  • read_gift_cards
  • read_store_credit_account_transactions

Catalog & inventory

  • read_products
  • read_inventory
  • read_price_rules
  • read_discounts

Fulfilment & shipping

  • read_merchants_managed_fulfillment_orders
  • read_assigned_fulfillment_orders
  • read_fulfillments
  • reads_shipping
Click Save.

Install the app

Go to the API credentials tab, click Install app, and confirm Install in the popup.

Reveal and copy the token

When the Admin API access token appears, click Reveal token once and copy it immediately.
You can only view this token once. Save it somewhere secure. If you lose it, you’ll need to uninstall and reinstall the custom app to generate a new one — all previous tokens are invalidated.

​
Step 3 · Plug the credentials into Ocular

Open the connector form

In Ocular, navigate to Data Management → Connectors → Add connector → Shopify.

Fill the fields

Connector Name

Free-form label (e.g., shopify_main).

Connector Identifier

Auto-generated by Ocular.

Start Date

YYYY-MM-DD — how far back Ocular should pull data.

Lookback Days

Past days to keep refreshing on every sync. Default 30.

Schedule Frequency

Numeric value + unit (e.g., 4 hours).

Shop ID

my-store.myshopify.com

Access Token

The token from Step 2.

Click Create Connector

Ocular stores the token in its encrypted vault and triggers the first sync. Initial historical load takes 24–48 hours.

​
Troubleshooting

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.
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.
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.
For ticket-writing format when filing a connector issue, see Working with the Ocular team → Connector-not-working tickets.