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

# Shopify

> What direct-to-consumer brands list on their Shopify stores, and at what price: store profiles, products, variants, and collections.

Use this to see what other brands sell online and at what price — to size a market, compare your prices with competitors, or find brands that might buy your ingredients.

The data comes from the public storefronts of online stores built on Shopify. Every record has `source: "shopify"`.

<Note>
  The crawl covers stores in every industry, not just CPG. Pass `industry=cpg` when you search stores to keep only consumer packaged goods brands.
</Note>

The API works from the store down: find stores, open one, then list its products and collections.

| Endpoint                          | What it does                                 | Scope                   |
| --------------------------------- | -------------------------------------------- | ----------------------- |
| `GET /v1/stores`                  | Search stores with filters                   | `search-stores`         |
| `GET /v1/stores/{id}`             | Get one store's full profile                 | `get-store`             |
| `GET /v1/stores/{id}/products`    | List a store's products                      | `get-store-products`    |
| `GET /v1/stores/{id}/collections` | List a store's collections                   | `get-store-collections` |
| `GET /v1/products/{id}`           | Get one product with every variant and price | `get-product`           |

## Search stores

Every filter is optional. When you pass several, a store must match all of them.

| Parameter  | Type    | Match                   | Description                                                                                     |
| ---------- | ------- | ----------------------- | ----------------------------------------------------------------------------------------------- |
| `domain`   | string  | Contains, ignoring case | The store's web address, such as `coffee`.                                                      |
| `name`     | string  | Contains, ignoring case | The store's name.                                                                               |
| `industry` | string  | Exact                   | Whether the store sells consumer packaged goods: `cpg`, `partial_cpg`, `not_cpg`, or `unknown`. |
| `category` | string  | Exact                   | A product category the store sells in, such as `coffee_and_tea`.                                |
| `limit`    | integer | —                       | Rows per page, default `50`, at most 200. Above 200 is served as 200.                           |
| `cursor`   | string  | —                       | The `next_cursor` from the previous page.                                                       |

### Your first search: find food and drink brands

<CodeGroup>
  ```bash Request theme={null}
  curl --request GET \
    --url 'https://api.orbbit.co/v1/stores?industry=cpg&category=coffee_and_tea&limit=20' \
    --header 'authorization: Bearer YOUR_API_KEY'
  ```

  ```json Response theme={null}
  {
    "data": [
      {
        "id": "shopify_store_01k3a1b2c3d4e5f6g7h8j9k0mn",
        "domain": "example-coffee.com",
        "name": "Example Coffee Co.",
        "country": "US",
        "industry": "cpg",
        "category": "coffee_and_tea",
        "product_count": 84,
        "variant_count": 212,
        "min_price": 7.5,
        "median_price": 18,
        "max_price": 129,
        "crawled_at": "2026-08-31T00:00:00.000Z",
        "source": "shopify"
      }
    ],
    "next_cursor": null
  }
  ```
</CodeGroup>

Values are illustrative.

### Understanding the response

Results come one page at a time. `limit` sets the page size (1 to 200, default 50). Each response has a `next_cursor`: pass it back as `cursor` to get the next page, and stop when it's `null`. Rows come back in ID order, so paging never skips or repeats a row.

* `category` is the one category the store sells most of. A store can sell in several; `GET /v1/stores/{id}` shows the full mix.
* `product_count` and `variant_count` count what the store lists. A variant is one buyable version of a product, such as a size or flavor.
* `min_price`, `median_price`, and `max_price` summarize the store's variant prices, in the store's own currency.
* `crawled_at` is when Orbbit last read the store. Use it to judge how fresh the numbers are.

## Get a store's full profile

<CodeGroup>
  ```bash Request theme={null}
  curl --request GET \
    --url https://api.orbbit.co/v1/stores/shopify_store_01k3a1b2c3d4e5f6g7h8j9k0mn \
    --header 'authorization: Bearer YOUR_API_KEY'
  ```

  ```json Response theme={null}
  {
    "data": {
      "id": "shopify_store_01k3a1b2c3d4e5f6g7h8j9k0mn",
      "domain": "example-coffee.com",
      "name": "Example Coffee Co.",
      "industry": "cpg",
      "category": "coffee_and_tea",
      "shopify_domain": "example-coffee.myshopify.com",
      "description": "Small-batch coffee roasted in Portland.",
      "city": "Portland",
      "province": "Oregon",
      "currency": "USD",
      "published_products_count": 84,
      "common_crawl": {
        "release": "CC-MAIN-2026-33",
        "harmonic_rank": 1843221,
        "host_count": 3
      },
      "categories": [
        { "category": "coffee_and_tea", "product_count": 71, "share": 0.845 },
        { "category": "soft_drinks_and_refreshments", "product_count": 13, "share": 0.155 }
      ]
    }
  }
  ```
</CodeGroup>

Response trimmed for clarity. Values are illustrative. The profile has every field a search returns, plus:

* `currency` — the currency every price in this store is in.
* `categories` — every category the store sells in, with the share of its products in each, largest first.
* `common_crawl` — how prominent the store is on the web, from the public Common Crawl web index. A lower `harmonic_rank` means more of the web links to the store.

## List a store's products

Products are paged. Each product carries its price range and main image; open one product to see every variant.

<CodeGroup>
  ```bash Request theme={null}
  curl --request GET \
    --url 'https://api.orbbit.co/v1/stores/shopify_store_01k3a1b2c3d4e5f6g7h8j9k0mn/products?limit=50' \
    --header 'authorization: Bearer YOUR_API_KEY'
  ```

  ```json Response theme={null}
  {
    "data": [
      {
        "id": "shopify_product_01k3a9x8w7v6u5t4s3r2q1p0nm",
        "title": "House Blend, Whole Bean",
        "handle": "house-blend",
        "vendor": "Example Coffee Co.",
        "product_type": "Coffee",
        "category": "coffee_and_tea",
        "sub_category": "coffee",
        "tags": ["medium-roast", "whole-bean"],
        "image": {
          "src": "https://cdn.shopify.com/s/files/1/0000/0000/products/house-blend.jpg",
          "width": 1200,
          "height": 1200
        },
        "price": { "min": 18, "max": 54, "currency": "USD" },
        "variant_count": 3,
        "published_at": "2025-03-14T17:02:11.000Z",
        "source": "shopify"
      }
    ],
    "next_cursor": null
  }
  ```
</CodeGroup>

Values are illustrative.

## Get one product

`GET /v1/products/{id}` returns everything in the list row, plus the full description, every image, and every variant with its own price.

```bash theme={null}
curl --request GET \
  --url https://api.orbbit.co/v1/products/shopify_product_01k3a9x8w7v6u5t4s3r2q1p0nm \
  --header 'authorization: Bearer YOUR_API_KEY'
```

```json Response (variants only) theme={null}
{
  "data": {
    "id": "shopify_product_01k3a9x8w7v6u5t4s3r2q1p0nm",
    "store_id": "shopify_store_01k3a1b2c3d4e5f6g7h8j9k0mn",
    "variants": [
      {
        "id": "shopify_variant_01k3aa0b1c2d3e4f5g6h7j8k9mnp",
        "title": "12 oz",
        "sku": "HB-12",
        "price": 18,
        "compare_at_price": null,
        "grams": 340,
        "available": true,
        "option1": "12 oz",
        "option2": null,
        "option3": null,
        "position": 1,
        "image_src": null
      }
    ]
  }
}
```

`compare_at_price` is the "was" price the store shows next to a sale price. When it's set and higher than `price`, the variant is on sale.

## List a store's collections

Collections are the merchant's own groupings of products, such as "Best sellers" or "Single origin". They show how a brand organizes and markets its range.

```bash theme={null}
curl --request GET \
  --url https://api.orbbit.co/v1/stores/shopify_store_01k3a1b2c3d4e5f6g7h8j9k0mn/collections \
  --header 'authorization: Bearer YOUR_API_KEY'
```

The response is a paged list of `{ id, title, handle, description, image, product_count, published_at, updated_at, source }`.

## Errors

An unknown store or product ID returns `404`:

```json 404 — unknown store theme={null}
{
  "error": {
    "type": "not_found",
    "message": "Unknown store: shopify_store_01k3a1b2c3d4e5f6g7h8j9k0mn"
  }
}
```

See [Errors](/errors) for every other error.

## Store fields

Returned by `GET /v1/stores` and `GET /v1/stores/{id}`.

| Field           | Type           | Description                                                                                     |
| --------------- | -------------- | ----------------------------------------------------------------------------------------------- |
| `id`            | string         | Orbbit's ID for the store. Starts with `shopify_store_`.                                        |
| `domain`        | string         | The store's web address, such as `example-coffee.com`.                                          |
| `name`          | string or null | The store's name.                                                                               |
| `country`       | string or null | The country the store is based in, as a two-letter code.                                        |
| `industry`      | string or null | Whether the store sells consumer packaged goods: `cpg`, `partial_cpg`, `not_cpg`, or `unknown`. |
| `category`      | string or null | The category the store sells most of.                                                           |
| `product_count` | number or null | How many products the store lists.                                                              |
| `variant_count` | number or null | How many variants — sizes, flavors, and so on — across all products.                            |
| `min_price`     | number or null | The lowest variant price, in the store's currency.                                              |
| `median_price`  | number or null | The middle variant price.                                                                       |
| `max_price`     | number or null | The highest variant price.                                                                      |
| `crawled_at`    | string or null | When Orbbit last read the store, as an ISO 8601 timestamp.                                      |
| `source`        | string         | Always `shopify`.                                                                               |

### Profile-only fields

`GET /v1/stores/{id}` also returns:

| Field                        | Type           | Description                                                                   |
| ---------------------------- | -------------- | ----------------------------------------------------------------------------- |
| `shopify_domain`             | string or null | The store's `myshopify.com` address.                                          |
| `description`                | string or null | The store's own description of itself.                                        |
| `city`                       | string or null | The store's city.                                                             |
| `province`                   | string or null | The store's state or province.                                                |
| `currency`                   | string or null | The currency the store prices in, such as `USD`.                              |
| `published_products_count`   | number or null | How many products the store says it has published.                            |
| `common_crawl.release`       | string or null | The Common Crawl web index release the ranking came from.                     |
| `common_crawl.harmonic_rank` | number or null | The store's rank by how much of the web links to it. Lower is more prominent. |
| `common_crawl.host_count`    | number or null | How many web hosts under the store's domain the crawl found.                  |
| `categories[].category`      | string         | A category the store sells in.                                                |
| `categories[].product_count` | number         | How many of its products are in that category.                                |
| `categories[].share`         | number         | That count as a share of all its products, from 0 to 1.                       |

## Product fields

Returned by `GET /v1/stores/{id}/products` and `GET /v1/products/{id}`.

| Field            | Type           | Description                                                  |
| ---------------- | -------------- | ------------------------------------------------------------ |
| `id`             | string         | Orbbit's ID for the product. Starts with `shopify_product_`. |
| `title`          | string or null | The product name.                                            |
| `handle`         | string or null | The product's name in the store's web address.               |
| `vendor`         | string or null | The brand or maker the store lists.                          |
| `product_type`   | string or null | The store's own label for the kind of product.               |
| `category`       | string or null | The product's category.                                      |
| `sub_category`   | string or null | A narrower category within `category`.                       |
| `tags`           | string\[]      | The store's tags on the product.                             |
| `image`          | object or null | The main image: `src`, `width`, `height`.                    |
| `price.min`      | number or null | The lowest variant price.                                    |
| `price.max`      | number or null | The highest variant price.                                   |
| `price.currency` | string or null | The currency of both prices.                                 |
| `variant_count`  | number         | How many variants the product has.                           |
| `published_at`   | string or null | When the store first published the product.                  |
| `source`         | string         | Always `shopify`.                                            |

### Single-product fields

`GET /v1/products/{id}` also returns:

| Field       | Type           | Description                                           |
| ----------- | -------------- | ----------------------------------------------------- |
| `store_id`  | string         | The store that sells the product.                     |
| `body_text` | string or null | The product description, as plain text.               |
| `images`    | array          | Every image: `src`, `width`, `height`.                |
| `variants`  | array          | Every variant. See [Variant fields](#variant-fields). |

## Variant fields

| Field               | Type            | Description                                                     |
| ------------------- | --------------- | --------------------------------------------------------------- |
| `id`                | string          | Orbbit's ID for the variant. Starts with `shopify_variant_`.    |
| `title`             | string or null  | The variant name, such as `12 oz`.                              |
| `sku`               | string or null  | The store's stock-keeping code.                                 |
| `price`             | number or null  | The current price.                                              |
| `compare_at_price`  | number or null  | The "was" price shown beside a sale price.                      |
| `grams`             | number or null  | The shipping weight in grams.                                   |
| `available`         | boolean or null | Whether the variant can be bought right now.                    |
| `option1`–`option3` | string or null  | The values that set this variant apart, such as size or flavor. |
| `position`          | number or null  | The variant's order on the product page.                        |
| `image_src`         | string or null  | The variant's own image, when it has one.                       |

## Collection fields

Returned by `GET /v1/stores/{id}/collections`.

| Field           | Type           | Description                                                        |
| --------------- | -------------- | ------------------------------------------------------------------ |
| `id`            | string         | Orbbit's ID for the collection. Starts with `shopify_collection_`. |
| `title`         | string or null | The collection name.                                               |
| `handle`        | string or null | The collection's name in the store's web address.                  |
| `description`   | string or null | The store's description of the collection.                         |
| `image`         | object or null | The collection image: `src`, `alt`.                                |
| `product_count` | number or null | How many products the collection holds.                            |
| `published_at`  | string or null | When the store published the collection.                           |
| `updated_at`    | string or null | When the store last changed the collection.                        |
| `source`        | string         | Always `shopify`.                                                  |

## Validation rules

| Rule            | Behavior                                                               |
| --------------- | ---------------------------------------------------------------------- |
| Filters combine | Several filters mean a store must match all of them.                   |
| Empty filter    | `?name=` with no text is the same as leaving it out.                   |
| `limit`         | A whole number of at least 1. Above 200 is served as 200, not refused. |
| Order           | Results are sorted by `id`, so paging is stable.                       |
| Unknown ID      | Any `{id}` that doesn't exist returns `404`.                           |

## Summary

| Endpoint                          | Scope                   | Response                              | Paged | Errors                     |
| --------------------------------- | ----------------------- | ------------------------------------- | ----- | -------------------------- |
| `GET /v1/stores`                  | `search-stores`         | `{ data: [store], next_cursor }`      | Yes   | `400`, `401`, `403`        |
| `GET /v1/stores/{id}`             | `get-store`             | `{ data: store profile }`             | No    | `401`, `403`, `404`        |
| `GET /v1/stores/{id}/products`    | `get-store-products`    | `{ data: [product], next_cursor }`    | Yes   | `400`, `401`, `403`, `404` |
| `GET /v1/stores/{id}/collections` | `get-store-collections` | `{ data: [collection], next_cursor }` | Yes   | `400`, `401`, `403`, `404` |
| `GET /v1/products/{id}`           | `get-product`           | `{ data: product }`                   | No    | `401`, `403`, `404`        |

## What to do next

* **Try it live** — [Search stores](/api-reference/shopify/search-stores), [Get a store](/api-reference/shopify/get-a-store), [List store products](/api-reference/shopify/list-store-products), [List store collections](/api-reference/shopify/list-store-collections), and [Get a product](/api-reference/shopify/get-a-product).
* **See how this fits with packaged-food data** — read the [CPG overview](/industry-data/cpg/overview).