# Shopify app

The Datalumo app connects a Shopify store to your knowledge base. It pushes **active products** and **published blog articles** into a source so search and chat can answer from your catalog.

Install at [shopify.datalumo.app](https://shopify.datalumo.app).

| Feature | What it does |
|---|---|
| **Connect** | Organisation public ID + API key (`pages.write`) → source picker |
| **Sync now** | Active products + published articles → pages API (batches of 50) |
| **Live products** | Product create/update/delete webhooks keep the source in sync |
| **Articles** | Full sync plus a background poll (default every 15 minutes) — Shopify has no article webhooks |
| **Scopes** | `read_products`, `read_content` only — no customer data |

Draft or archived products and unpublished articles are not indexed on a full sync.

## Install

1. Open [shopify.datalumo.app](https://shopify.datalumo.app) and install the app on your store.
2. In Datalumo, create a **Shopify** source (or any source the app can write to) and an **API key** with `pages.write` (see [Authentication](/docs/authentication)). You can limit the key to that one source.
3. Copy your **organisation ID** from the **API keys** page. It is a long public id, not your organisation name.

In the embedded app:

1. Paste the organisation public ID and API key
2. Choose a **source**
3. **Connect & test**
4. **Sync products now** (and articles if enabled)

Watch indexing progress on the source page in the Datalumo dashboard — a finished push is not the same as fully indexed.

Self-hosting Datalumo? Set the **Datalumo URL** in the app to your own install (defaults to `https://datalumo.app`).

## What syncs

| Content | How it stays up to date |
|---|---|
| **Active products** | Full **Sync now** + product webhooks (create, update, delete) |
| **Published blog articles** | Full **Sync now** + background poll (Shopify does not emit article webhooks) |

You can turn products or articles on or off in the app's content preferences.

### What a page looks like

| Page field | Products | Articles |
|---|---|---|
| Title | Product title | Article title |
| Content | Description (HTML) + variant list | Body HTML |
| URL | Storefront product URL | Storefront blog path |
| Reference | `product:{shopify_id}` | `article:{shopify_id}` |
| Details | Handle, vendor, type, tags, status, variants | Handle, blog, author, tags, published date |

Because the Shopify id is the reference, a full sync is always safe to run again. It updates what is already there instead of duplicating.

### External IDs

```
product:{shopify_product_id}
article:{shopify_article_id}
```

Re-syncs and deletes use the same id.

## After you connect

- **Pushing is not indexing.** When a sync finishes, Datalumo still has to read and embed everything it received. Progress continues on the source page after the app reports done.
- Product changes land quickly via webhooks. Article edits show up on the next poll or the next full sync.
- Uninstalling the app stops new pushes; pages already indexed stay until you clear or delete the source.

## Troubleshooting

| Symptom | Check |
|---|---|
| Connect & test fails | Organisation ID and API key belong to the same organisation; the key has `pages.write` |
| Source not listed | The API key can access that source (or is not limited to another one) |
| Nothing appears in the source | Products are **Active** / articles are published; content preferences include them; run **Sync now** |
| Content synced but not searchable yet | Indexing runs after the push; watch progress on the source page |
| Product edits missing | App is still installed and product webhooks are healthy |
| Article edits lag | Wait for the next poll, or run **Sync now** |

## Related

- [Introduction](/docs/introduction) for the other ways to integrate
- [Authentication](/docs/authentication) for API keys and permissions
- [Pages](/docs/pages) for the endpoints the app uses under the hood
- [Widget SDK](/docs/sdk) for embedding search and chat on your storefront