Export API: Bulk Catalog Ingestion

The Export API powers bulk catalog ingestion. Instead of paging through /v3/products or /v3/collections/{collectionId}/products to mirror the Snappy catalog into your own platform, you queue an asynchronous export job and pull a single NDJSON file containing the full result set. Export is the recommended way to keep a local product mirror up to date - pair a nightly bulk export with Webhooks for incremental product changes between exports.

Want to understand how Export fits into the bigger picture? See Snappy Core Concepts & Data Models.

Exports are NDJSON-only for now. Each line in the file is a single JSON object representing one product, with the same shape as GET /v3/products/{productId} plus an export-only variants array containing every variant with per-country availability. See NDJSON export format below for the full shape.

When to use Export

Use the Export API when:

You need the entire catalog (or a large filtered subset) in a single payload - typically for nightly ingestion into a partner system, search index, or data warehouse.
The synchronous list endpoints would require dozens or hundreds of paginated requests.
You’d rather fire-and-forget the job and pick up the result later than hold an HTTP connection open.

Use the synchronous list endpoints (GET /v3/products, GET /v3/collections/{collectionId}/products) when:

You need real-time browse / search inside your UI.
The result set is small enough to fit in one or two pages.

How export jobs work

Export is a standard async job pattern:

Create the job

Call POST /v3/products/exports (filtered export) or POST /v3/collections/exports (collection-scoped export). Both return 200 OK with an exportId immediately.

Poll for status

Call GET /v3/products/exports/{exportId} until the job reaches a terminal state.

Download the file

When status is completed, the response includes a downloadUrls map of signed URLs. Download the file(s) before the export record expires.

Status lifecycle

Status	Description
`pending`	Job has been queued; processing has not started.
`processing`	Job is actively running.
`completed`	Job finished successfully. `downloadUrls` is populated with signed S3 URLs.
`failed`	Job terminated without producing a file. `errorMessage` contains a human-readable reason.

Key Concepts & Business Rules

Download URLs are signed and short-lived

When a job completes, the poll response returns a downloadUrls map (keyed by file identifier or location code). These are signed S3 URLs that expire 48 hours after the export record is created. After expiry, you’ll need to re-issue a new export job.

NDJSON, not JSON

Exports produce newline-delimited JSON - one product (with its variants) per line. This makes it safe to stream-parse multi-gigabyte exports without holding the whole payload in memory.

Filtering uses flat body fields (not the JSON:API `filter[...]` query convention)

V3 list endpoints accept filters as bracketed query parameters (filter[price][gte], filter[brandId]). Export jobs accept the same filters as flat JSON body fields (price.gte, brandId) - this is intentional for JSON ergonomics. Same semantics, different surface.

Idempotency is not currently supported

Repeated calls to POST /v3/products/exports with identical bodies create separate export jobs. If you need idempotency for nightly runs, persist the exportId of the latest in-flight job on your side and skip creating a new one when one is already pending.

Locations drive price localisation

The locations array (ISO 3166-1 alpha-2 country codes) is used to localise prices and availability in the exported file. Defaults to ["US"] on the products export endpoint; required on the collections export endpoint.

Permissions

All Export endpoints require: Requires: products:read

NDJSON export format

Each line in the export file is a full Product JSON with one export-only addition: a variants array containing every variant on that product.

Per-line shape

Product fields - identical to GET /v3/products/{productId}, including any include (brand, tags) and fields (priceRange, variantsCount) expansions you requested.
variants - an array of the product’s variants, each with its full details plus an availability object.

Variant `availability`

Each variant in the export includes an availability object with one entry per country listed in your locations filter. Each entry follows the same shape as GET /v3/variants/{variantId}/availability:

isAvailable - whether the variant is orderable in that country.
price - the localised price for that country.
priceBreakdown - a breakdown of itemPrice, shippingFee, and ddp (duties, taxes, and paid-on-delivery fees). Partner pricing is reflected here when applicable.

fields does not control variants in the export. Variant data is always fully included on every line - you can’t opt into a subset. If you don’t need variant details, ignore the variants array on the consumer side. Variant-level fields (e.g. price, priceBreakdown, details, brand) apply only to the synchronous variant endpoints, not to the export.

Example line

{
  "id": "655277e68e0719000d6c3fd5",
  "title": "NFL 25-Layer StadiumView Wall Art",
  "createdAt": "2026-05-11T10:53:01.026Z",
  "category": {
    "fullName": "Fan Merchandise / NFL / NFL Memorabilia / Autographed Helmets"
  },
  "catalog": "marketplace",
  "media": [
    { "type": "image", "src": "https://media.snappy.com/image/o1xc17wfbda6cl91hm0r6_picture-1.jpg?w=1000&h=1000&q=80&f=auto" }
  ],
  "brand": {
    "id": "6511b55142c420000d083a55",
    "name": "YouTheFan",
    "description": "Officially licensed NFL fan merchandise."
  },
  "tags": [
    { "id": "6527bb3567f414000c15d2c7", "name": "Snappy's Picks", "backgroundColor": "#13C2C2", "textColor": "#FFFFFF" }
  ],
  "priceRange": {
    "min": { "amount": 244.99, "currency": "USD" },
    "max": { "amount": 249.99, "currency": "USD" }
  },
  "variantsCount": 9,
  "variants": [
    {
      "id": "FB6bgFV4lf",
      "productId": "655277e68e0719000d6c3fd5",
      "title": "NFL 25-Layer StadiumView Wall Art",
      "selectedOptions": { "nfl_team": "Denver Broncos" },
      "taxable": true,
      "media": [
        { "type": "image", "src": "https://media.snappy.com/image/psqy00xpuxrhrdelvkiz?w=1000&h=1000&q=80&f=auto" }
      ],
      "personalization": null,
      "descriptionHtml": "<p>The 25-Layer StadiumViews 3D Wall Art ...</p>",
      "details": {
        "includes": null,
        "features": null,
        "specifications": null,
        "notices": null
      },
      "brand": {
        "id": "6511b55142c420000d083a55",
        "name": "YouTheFan",
        "description": "Officially licensed NFL fan merchandise."
      },
      "availability": {
        "US": {
          "isAvailable": true,
          "price": { "amount": 244.99, "currency": "USD" },
          "priceBreakdown": { "ddp": 0, "shippingFee": 0, "itemPrice": 244.99 }
        },
        "CA": {
          "isAvailable": true,
          "price": { "amount": 268.50, "currency": "USD" },
          "priceBreakdown": { "ddp": 12.50, "shippingFee": 11.01, "itemPrice": 244.99 }
        }
      }
    },
    {
      "id": "MdjSPF4zHE",
      "productId": "655277e68e0719000d6c3fd5",
      "title": "NFL 25-Layer StadiumView Wall Art",
      "selectedOptions": { "nfl_team": "Philadelphia Eagles" },
      "taxable": true,
      "media": [
        { "type": "image", "src": "https://media.snappy.com/image/hljxb9yzjomaf4qpbs22?w=1000&h=1000&q=80&f=auto" }
      ],
      "personalization": null,
      "descriptionHtml": "<p>...</p>",
      "details": {
        "includes": null,
        "features": null,
        "specifications": null,
        "notices": null
      },
      "brand": {
        "id": "6511b55142c420000d083a55",
        "name": "YouTheFan",
        "description": "Officially licensed NFL fan merchandise."
      },
      "availability": {
        "US": {
          "isAvailable": true,
          "price": { "amount": 249.99, "currency": "USD" },
          "priceBreakdown": { "ddp": 0, "shippingFee": 0, "itemPrice": 249.99 }
        },
        "CA": {
          "isAvailable": true,
          "price": { "amount": 273.75, "currency": "USD" },
          "priceBreakdown": { "ddp": 12.75, "shippingFee": 11.01, "itemPrice": 249.99 }
        }
      }
    }
  ]
}

How to Work with Export

Create a filtered product export job

POST /v3/products/exports

Queues an async export of products matching the supplied filters. Required: catalog, format. Optional filters: search, brandName, brandId, tagId, productIds, price.gte/price.lte, locations, include, fields. Returns 200 OK with an exportId to poll. Create a collection export job

POST /v3/collections/exports

Queues an async export of every product in a single collection. Required: collectionId, catalog, locations. Returns 200 OK with an exportId to poll. Poll export job status

GET /v3/products/exports/{exportId}

Returns the current status of an export job. When status is completed, includes a downloadUrls map with signed URLs. When status is failed, includes an errorMessage. Polls both products and collections export jobs.

Authentication

Marketplace

Gifting

Administration

Export API: Bulk Catalog Ingestion

When to use Export

How export jobs work

Status lifecycle

Key Concepts & Business Rules

Download URLs are signed and short-lived

NDJSON, not JSON

Filtering uses flat body fields (not the JSON:API `filter[...]` query convention)

Idempotency is not currently supported

Locations drive price localisation

Permissions

NDJSON export format

Per-line shape

Variant `availability`

Example line

How to Work with Export

​When to use Export

​How export jobs work

​Status lifecycle

​Key Concepts & Business Rules

​Download URLs are signed and short-lived

​NDJSON, not JSON

​Filtering uses flat body fields (not the JSON:API filter[...] query convention)

​Idempotency is not currently supported

​Locations drive price localisation

​Permissions

​NDJSON export format

​Per-line shape

​Variant availability

​Example line

​How to Work with Export

When to use Export

How export jobs work

Status lifecycle

Key Concepts & Business Rules

Download URLs are signed and short-lived

NDJSON, not JSON

Filtering uses flat body fields (not the JSON:API `filter[...]` query convention)

Idempotency is not currently supported

Locations drive price localisation

Permissions

NDJSON export format

Per-line shape

Variant `availability`

Example line

How to Work with Export