---
updatedAt: 2026-09-28T14:49:06.000Z
agentTools:
  projectIndex: https://developer.searchblox.com/llms.txt
---

# Guide to Use Shopify Data in Product Discovery Collection

## **Steps to configure Shopify data in Product Discovery Collection**

1. Converting Product Data to Shopify-Compatible CSV
2. Getting Shopify Store Fields for SearchBlox Product Discovery

## **Converting Product Data to Shopify-Compatible CSV**

### **Overview**

Any product dataset (JSON, CSV, etc.) can be converted into a Shopify-compatible CSV for import via `Shopify Admin > Products > Import`. The conversion involves mapping source fields to Shopify's 49-column CSV format and structuring rows correctly for variants and images.

> 📘 TIP:
>
> **Claude Code to generate a custom conversion script for any dataset:**
>
> You can use Claude Code to quickly generate a custom conversion script for any dataset. Simply provide your source data file and ask Claude Code to create a script that maps its fields to the Shopify CSV format. It will analyze the data structure and produce a ready-to-use converter.

**Key Shopify CSV Fields**

| Shopify Field            | Description                                                            |
| :----------------------- | :--------------------------------------------------------------------- |
| Handle                   | URL-friendly product identifier (lowercase, hyphens, no special chars) |
| Title                    | Product name                                                           |
| Body (HTML)              | Product description in HTML                                            |
| Vendor                   | Brand or manufacturer                                                  |
| Type                     | Product category (e.g., Skincare > Moisturizer)                        |
| Tags                     | Comma-separated tags for filtering and search                          |
| Variant Price            | Selling price                                                          |
| Variant Compare At Price | Original price (shows strikethrough if higher than selling price)      |
| Image Src                | Image URL                                                              |
| Variant SKU              | Stock-keeping unit identifier                                          |
| Option1 Name / Value     | First variant option (e.g., Size)                                      |
| Option2 Name / Value     | Second variant option (e.g., Color)                                    |
| Variant Inventory Qty    | Stock quantity                                                         |
| Published                | TRUE to make the product visible                                       |

### **CSV Structure**

Shopify uses a multi-row format where products with multiple variants or images span several rows, all sharing the same Handle:

**Row 1:** Contains all product-level data (Title, Body, Vendor, Tags, etc.) + first variant + primary image.\
**Additional variant rows:** Same Handle, only variant-specific fields filled (Option value, SKU, Price, Inventory).\
**Additional image rows:** Same Handle, only Image Src, Image Position, and Image Alt Text filled.

> 📘 Examples:
>
> \*\*Example 1:\*\*A product with 2 sizes and 3 images:
>
> | Row | Handle          | Title           | Option1 Value | Image Src      | Image Position |
> | :-- | :-------------- | :-------------- | :------------ | :------------- | :------------- |
> | 1   | hydrating-cream | Hydrating Cream | 50ml          | primary.jpg    | 1              |
> | 2   | hydrating-cream |                 | 100ml         |                |                |
> | 3   | hydrating-cream |                 |               | side-view\.jpg | 2              |
> | 4   | hydrating-cream |                 |               | close-up.jpg   | 3              |
>
> **Example 2:** Ulta Dataset Conversion:
>
> As a reference, the convert\_to\_shopify.py script converts an Ulta product JSON file to Shopify CSV:
>
> ```shell
> python convert_to_shopify.py ulta_products.json shopify_products.csv
> ```
>
> Key mappings used in this example:
>
> | Source Field                          | Shopify Field                           |
> | :------------------------------------ | :-------------------------------------- |
> | product\_name                         | Handle (auto-generated), Title          |
> | brand\_name                           | Vendor                                  |
> | raw\_description / summary            | Body (HTML)                             |
> | category\_1, category\_2, category\_3 | Type (joined with >)                    |
> | retail, sale\_price                   | Variant Price, Variant Compare At Price |
> | primary\_image\_url                   | Image Src                               |
> | sku                                   | Variant SKU                             |
> | product\_size, color                  | Option1, Option2                        |
> | uniq\_id                              | Metafield: searchblox.uniq\_id          |

### **Importing into Shopify**

1. Go to Shopify Admin > Products > Import.
2. Upload the generated CSV file.
3. Review the preview and click Import products.
4. Shopify will create all products with their variants and images.

For full details on Shopify's CSV format and requirements, see the official guide: [Using CSV files — Shopify Help](https://help.shopify.com/en/manual/products/import-export/using-csv)

## **Getting Shopify Store Fields for SearchBlox Product Discovery**

### **Overview**

To create a Product Discovery collection in SearchBlox, you need three fields from your Shopify store:

| Field        | Description                                  | Example                     |
| :----------- | :------------------------------------------- | :-------------------------- |
| Store Domain | Your Shopify store's .myshopify.com domain   | your-store.myshopify.com    |
| Access Token | Admin API access token (starts with shpat\_) | shpat\_xxxxxxxxxxxxxxxxxxxx |
| API Version  | Shopify API version for requests             | 2025-07                     |

### **Steps to Get Each Field**

1. Store Domain
2. Access Token (Admin API)
3. API Version

#### **Store Domain**

1. Log in to your Shopify Admin panel.
2. The URL in your browser will be: <https://admin.shopify.com/store/><your-store-name>
3. Your store domain is: <your-store-name>.myshopify.com

Alternatively, go to Settings > Domains in Shopify Admin.

#### **Access Token (Admin API)**

**Important — Shopify credential changes (January 2026):** Shopify has deprecated the legacy custom app flow where you could create an app directly in the Shopify Admin and copy a static `shpat_` access token from the screen. New apps must now be created through the **Shopify Developer Dashboard** or **Shopify CLI**, and access tokens are obtained via **OAuth-based flows** (client credentials grant, token exchange, or authorization code grant) rather than being displayed as a one-time copyable value. Tokens also expire regularly for improved security. See [Shopify's official guide on generating access tokens ](https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens/generate-app-access-tokens-admin) for current instructions.

**For existing custom apps** (created before January 2026), the previously issued `shpat_ ` tokens continue to work. If you already have one, you can use it directly in SearchBlox.

**For new apps**, follow these steps:

1. Go to the [Shopify Developer Dashboard](https://partners.shopify.com/) and create a new app.
2. Configure the required **Admin API scopes:**
   * read\_products — to read product data
   * read\_product\_listings — to read product listings
   * read\_inventory — to read inventory levels (optional)
   * read\_content — to read pages/blogs (optional)
3. Install the app on your store.
4. Note the Client ID and Client Secret from the app's credentials page.
5. Obtain the access token using the Client Credentials Grant flow:

### **Request**

```Text None
POST https://{your-store}.myshopify.com/admin/oauth/access_token
Content-Type: application/json
```

### **Payload**

```json
{
  "grant_type": "client_credentials",
  "client_id": "<your_client_id>",
  "client_secret": "<your_client_secret>"
}

```

### **Response**

```json
{
  "access_token": "shpat_xxxxxxxxxxxxxxxxxxxx",
  "scope": "read_products,read_inventory,...",
  "expires_in": 86400
}
```

**Note:** Tokens obtained via the client credentials grant **expire after 24 hours.** You will need to request a new token when the current one expires. This flow is available for apps installed on stores you own.

## **API Version**

Shopify releases new API versions quarterly (e.g., 2025-01, 2025-04, 2025-07, 2025-10). Use the latest stable version available at the time of setup. In SearchBlox, select Custom from the API Version dropdown and enter the version string.

## **SearchBlox Configuration**

1. In SearchBlox Admin, navigate to the **Product Discovery** collection setup.
2. Enter the fields:
   * **Store Domain**: your-store.myshopify.com
   * **Access Token:** `shpat_xxxxxxxxxxxxxxxx`
   * **API Version:** Select **Custom** and enter the version (e.g., 2025-07)
3. Save the configuration. SearchBlox will use the Shopify Admin API to fetch product data for indexing and search.

> 📘 References:
>
> **Shopify CSV & Product Import**
>
> * [Using CSV files to import and export products](https://help.shopify.com/en/manual/products/import-export/using-csv) — Official guide on Shopify's CSV format and column requirements
> * [Importing products with a CSV file](https://help.shopify.com/en/manual/products/import-export/import-products) — Step-by-step import instructions
> * [Sample product CSV template](https://help.shopify.com/csv/product_template.csv) — Downloadable Shopify CSV template
> * [Sample product CSVs with images (GitHub)](https://github.com/shopifypartners/product-csvs) — Shopify-provided sample product CSVs to seed a store
>
> **Shopify API & Authentication**
>
> * [Authentication and authorization overview](https://shopify.dev/docs/apps/build/authentication-authorization) — Overview of Shopify's auth model
> * [Generate access tokens for custom apps](https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens/generate-app-access-tokens-admin)— Current instructions for obtaining Admin API tokens
> * [OAuth authorization code grant](https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens/authorization-code-grant)— Manual OAuth flow implementation
> * [API access scopes reference](https://shopify.dev/docs/api/usage/access-scopes) — Full list of available API scopes (read\_products, read\_inventory, etc.)
> * [Shopify Custom App Deprecation 2026 & Dev Dashboard Guide](https://datronixtech.com/shopify-custom-app-deprecation/) — Summary of the January 2026 credential changes