Product Catalog

Product Catalog Quickstart

From nothing to a list of your products in three steps. You need a Throttle application with the Product Catalog extension installed and some products in it.

1

Install the SDK

Add @usethrottle/catalog to your project.

2

Create keys

A browser key for your website, and a server key for scripts, servers and curl.

3

Run your first query

List five products from Node.js, then from your website.

1. Install the SDK

Install 
npm install @usethrottle/catalog
# or
pnpm add @usethrottle/catalog

Node.js 20 or later, or any evergreen browser. In TypeScript, moduleResolution must be node16, nodenext or bundler: the package has only an exports map, which the older node setting cannot read.

2. Create keys

Storefront calls use publishable keys (pc_pk_…). Create them in the catalog dashboard:

  1. Open the Product Catalog extension in your Throttle dashboard and go to Storefront › Keys.
  2. For your website, create a key with type Browser and put your site's origin under Allowed websites, one per line, such as https://shop.example.com. Origins are matched exactly and must be https.
  3. For Node.js, a server or curl, create a second key with type Server. It has no websites: it refuses any request that comes from a browser.
  4. Copy each key when it is shown. Store the server key in an environment variable.
Local development
A browser key cannot list http://localhost: allowed websites are https only. While you develop, call the catalog from your dev server with the server key, or serve your site over https (for example https://localhost:8443) and list that origin.

Keys and channels explains the three key types and what each one protects.

3. Run your first query

This script lists five products with their lowest price. A script sends no Origin, so it uses the server key.

quickstart.ts 
import { createCatalogClient } from '@usethrottle/catalog';

const catalog = createCatalogClient({
  publishableKey: process.env.CATALOG_SERVER_KEY ?? '',
});

const { products } = await catalog.products.list({ limit: 5 });

for (const product of products) {
  console.log(product.handle, product.title, product.priceRange?.minMinor);
}
Run it 
# In a new folder, with Node.js 20 or later:
npm init -y
npm pkg set type=module
npm install @usethrottle/catalog

# Save the snippet above as quickstart.ts, then:
CATALOG_SERVER_KEY=pc_pk_your_server_key npx tsx quickstart.ts

It prints one line per product: its handle, its title and its lowest price in minor units (4999 is $49.99). The client talks to https://catalog.usethrottle.dev by default and gives up on a call after 10 seconds.

From your website

The same call in a page, with the browser key. It works only from an origin on the key's allowed websites.

In the browser 
import { createCatalogClient } from '@usethrottle/catalog';

// A browser key: this page's origin must be one of the key's allowed websites.
const catalog = createCatalogClient({
  publishableKey: 'pc_pk_your_browser_key',
});

const { products } = await catalog.products.list({ limit: 5 });

const list = document.querySelector('#products');
for (const product of products) {
  const item = document.createElement('li');
  item.textContent = product.title ?? product.handle;
  list?.append(item);
}

With curl

The API is plain HTTP. Send the key in X-Catalog-Key. Use the server key here too: a browser key refuses a request without an allowed Origin (403 ORIGIN_NOT_ALLOWED).

curl 
curl "https://catalog.usethrottle.dev/v1/storefront/products?limit=5" \
  -H "X-Catalog-Key: $CATALOG_SERVER_KEY"
Answer (one product shown) 
{
  "products": [
    {
      "handle": "ceramic-brake-pads",
      "title": "Ceramic Brake Pads",
      "brand": "Bosch",
      "productType": "Brakes",
      "images": [
        {
          "url": "https://catalog.usethrottle.dev/media/i1/4f2a9c0d7e1b4a6c8d3e5f7a9b1c2d3e/original",
          "mediaId": "4f2a9c0d7e1b4a6c8d3e5f7a9b1c2d3e",
          "width": 1000,
          "height": 800,
          "sizes": {
            "400": "https://catalog.usethrottle.dev/media/i1/4f2a9c0d7e1b4a6c8d3e5f7a9b1c2d3e/400",
            "800": "https://catalog.usethrottle.dev/media/i1/4f2a9c0d7e1b4a6c8d3e5f7a9b1c2d3e/800",
            "2048": "https://catalog.usethrottle.dev/media/i1/4f2a9c0d7e1b4a6c8d3e5f7a9b1c2d3e/original"
          }
        }
      ],
      "priceRange": {
        "minMinor": 4999,
        "maxMinor": 6499,
        "currency": "USD",
        "compareAtMinMinor": null
      },
      "availability": "in_stock",
      "lowStock": false,
      "featured": true,
      "badges": { "sale": false, "new": false },
      "variantCount": 3,
      "optionSwatches": [],
      "seo": { "title": null }
    }
  ],
  "page": {
    "number": 1,
    "limit": 5,
    "total": 1240,
    "pageCount": 248,
    "nextCursor": "WzEsMTcyOTUwMDAwMDAwMCw0Ml0"
  },
  "applied": { "filters": {} },
  "sort": "featured",
  "currency": null,
  "locale": null
}

Next steps