Products

Overview

A product is the listing a customer browses. A variant is the thing they actually buy. That split runs through everything on this page. The product holds what’s shared — name, description, images, which categories it’s filed under. Each variant holds what differs — its SKU, its price, its stock. A T-shirt is one product; small navy is a variant. Every product has at least one variant, even when there’s nothing to choose. A book with no size or colour still has a single variant carrying its SKU, price and stock; you just never render a picker.

Product names, descriptions, slugs and SEO fields are translatable.

Product Attributes

Attribute	Description	Translatable
`name`	Product name	Yes
`description` / `description_html`	Description as plain text and as formatted HTML	Yes
`slug`	URL identifier, e.g. `spree-tote`	Yes
`status`	`draft`, `active` or `archived`. A marketplace adds `proposed` and `rejected` — see Seller submissions	No
`available_on`	When it goes on sale	No
`discontinue_on`	When it comes off	No
`meta_title` / `meta_description` / `meta_keywords`	SEO fields	Yes
`purchasable`	Whether it can be added to a cart	No
`in_stock`	Whether any variant has stock	No
`backorderable`	Whether it can be ordered while out of stock	No
`preorder` / `preorder_ships_at`	Whether it’s sold ahead of availability, and when it ships	No
`available`	Whether it’s on sale right now, by date and status	No
`price` / `original_price`	The default variant’s price, and its compare-at price	No
`default_variant_id`	Which variant represents the product	No
`variant_count`	How many variants it has	No
`thumbnail_url`	First image — always returned, no expand needed	No
`tags`	Tags, for filtering	No

The Admin API adds the operational fields on top: product_type_id, delivery_profile_id, tax_category_id, seller_id, metadata, created_at / updated_at / deleted_at.

Listing Products

// List products with pagination
const { data: products, meta } = await client.products.list({
  limit: 12,
  page: 1,
})

// Filter by price range and availability
const filtered = await client.products.list({
  price_gte: 10,
  price_lte: 50,
  in_stock: true,
})

// Search by keyword
const results = await client.products.list({
  search: 'tote bag',
})

// Sort products
const sorted = await client.products.list({
  sort: '-price',  // high to low; also: price, name, -name, available_on, -available_on, best_selling
})

const { data: products, meta } = await adminClient.products.list({
  limit: 12,
  page: 1,
})

# List products
curl 'https://api.mystore.com/api/v3/store/products?limit=12&page=1' \
  -H 'X-Spree-API-Key: pk_xxx'

# Filter by price and stock
curl 'https://api.mystore.com/api/v3/store/products?q[price_gte]=10&q[price_lte]=50&q[in_stock]=true' \
  -H 'X-Spree-API-Key: pk_xxx'

# Search
curl 'https://api.mystore.com/api/v3/store/products?q[search]=tote+bag' \
  -H 'X-Spree-API-Key: pk_xxx'

See Querying for the full list of filtering, sorting, and pagination options.

Getting a Product

// Get by slug
const product = await client.products.get('spree-tote')

// Get with included relations
const detailed = await client.products.get('spree-tote', {
  expand: ['variants', 'media', 'option_types', 'categories'],
})
// detailed.variants => [{ id: "var_xxx", sku: "TOTE-S-R", price: { amount: "15.99", currency: "USD" }, ... }]
// detailed.media => [{ id: "img_xxx", original_url: "https://cdn...", position: 1 }]
// detailed.option_types => [{ name: "size", label: "Size", position: 1, kind: "..." }]
// detailed.option_values => [{ name: "small", label: "S", option_type_name: "size", ... }]  // separate top-level array when expanded

const product = await adminClient.products.get('prod_86Rf07xd4z')

curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=variants,media,option_types,categories' \
  -H 'X-Spree-API-Key: pk_xxx'

Pass expand to include related resources in a single response — see expand relations for how relation inclusion works.

Managing Products

The examples above use the Store API (publishable key, read-only, customer-facing). To create and manage products, use the Admin API — via the Admin SDK or the Spree CLI. A product’s purchasable attributes (SKU, prices, stock) live on its variants, which you can create inline. For a product with options, send the variants:

import { createAdminClient } from '@spree/admin-sdk'

const adminClient = createAdminClient({
  baseUrl: 'https://store.example.com',
  secretKey: 'sk_xxx',
})

const product = await adminClient.products.create({
  name: 'Premium T-Shirt',
  description: 'Soft, organic cotton.',
  status: 'active',
  variants: [
    {
      sku: 'TSHIRT-S-NAVY',
      options: [
        { name: 'size', value: 'Small' },
        { name: 'color', value: 'navy' },
      ],
      prices: [{ currency: 'USD', amount: '29.99' }],
      stock_levels: [{ stock_location_id: 'sloc_xxx', count_on_hand: 50 }],
    },
  ],
})

spree api post /products -d '{
  "name": "Premium T-Shirt",
  "status": "active",
  "variants": [{
    "sku": "TSHIRT-S-NAVY",
    "options": [{ "name": "size", "value": "Small" }],
    "prices": [{ "currency": "USD", "amount": "29.99" }]
  }]
}'

For something with no options at all, send prices directly and skip the variants array — Spree forwards them to the product’s single variant:

await adminClient.products.create({
  name: 'The Spree Handbook',
  status: 'active',
  prices: [{ currency: 'USD', amount: '19.99' }],
})

curl -X POST 'https://api.mystore.com/api/v3/admin/products' \
  -H 'X-Spree-API-Key: sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "The Spree Handbook",
    "status": "active",
    "prices": [{ "currency": "USD", "amount": "19.99" }]
  }'

Don’t pass both. Update, clone, or archive a product (deleting soft-deletes it):

await client.products.update('prod_xxx', { name: 'Premium Tee', status: 'active' })
await client.products.clone('prod_xxx')   // duplicate as a new draft
await client.products.delete('prod_xxx')  // soft-delete

spree api patch /products/prod_xxx -d '{"name": "Premium Tee"}'
spree api post /products/prod_xxx/clone
spree api delete /products/prod_xxx

Operating on many products at once? The Admin API has bulk actions — bulkStatusUpdate, bulkAddToCategories, bulkAddTags, bulkDestroy, and more. See the Admin API endpoint index.

Seller submissions

On a marketplace, a seller lists a product but does not publish one. They submit it, and the marketplace decides. This adds two statuses to the three above — both hidden from the storefront, since only active is visible.

This applies to products that belong to a seller. A marketplace’s own catalog is unaffected: an operator publishing their own product sets status directly and answers to nobody.

The lifecycle

Withdrawing a submission before anyone has ruled on it closes the open row as withdrawn, so a pending row always means the marketplace still owes an answer. A product that was already rejected keeps that decision at the head of its trail instead.

Status	Meaning	Storefront
`draft`	The seller is still working on it	Hidden
`proposed`	Submitted, waiting on the marketplace	Hidden
`rejected`	Sent back with a reason, awaiting changes	Hidden
`active`	Approved and on sale	Visible
`archived`	Withdrawn	Hidden

A seller can always take their own listing down — that is not a review decision. Putting one up is.

The submission record

Each submission and each decision on it is a Spree::ProductSubmission row. The product’s status stays the operational truth; these rows are how it got there.

Column	Description
`status`	`pending`, `approved`, `rejected`, or `withdrawn`
`submitted_by_id`	The seller’s staff member who asked
`reviewed_by_id`	The marketplace’s staff member who decided
`reviewed_at`	When the decision was made
`review_note`	Why it was sent back — this is what the seller reads

Rows accumulate rather than overwrite, so a seller sent back three times leaves three rows. The latest row for a product is the live one; the ones before it are the trail.

Never store a rejection reason on the product itself. A seller can write their own product’s metadata, so a note kept there is erased the next time they save.

An approval with no reviewed_by_id and metadata.auto_approved set means the store approves listings automatically — never a decision whose author was lost. Turn that on with the auto_approve_seller_products store preference.

Submitting, as a seller

Status is not writable on the seller branch. A seller moves a product with an explicit action:

import { createSellerClient } from '@spree/seller-sdk'

const client = createSellerClient({
  baseUrl: 'https://marketplace.example.com',
  sellerId: 'sel_xxx',
})

await client.products.submit('prod_xxx')   // draft or rejected → proposed
await client.products.draft('prod_xxx')    // take it back down
await client.products.archive('prod_xxx')  // withdraw it

// Why it was sent back
const product = await client.products.get('prod_xxx', 'submission')
product.submission?.review_note

spree api patch /seller/products/prod_xxx/submit
spree api patch /seller/products/prod_xxx/draft
spree api patch /seller/products/prod_xxx/archive

Deciding, as the marketplace

await client.products.approve('prod_xxx')
await client.products.reject('prod_xxx', { reason: 'Please add a photo showing scale.' })

// The review queue
const pending = await client.products.list({ status_eq: 'proposed' })

// Who decided, and when
const product = await client.products.get('prod_xxx', { expand: ['submission'] })
product.submission?.reviewed_by_name

spree api patch /products/prod_xxx/approve
spree api patch /products/prod_xxx/reject -d '{"reason": "Please add a photo showing scale."}'

The seller sees the note and when the decision was made, but never who made it.

Leaving review is a decision

A product in proposed or rejected cannot have its status changed by an ordinary update — that would put it on sale with nobody’s name against it. The refusal lives in the product update workflow, so every caller inherits it, and bulk status updates skip those products and report how many they left behind.

Events

Each transition publishes an event you can subscribe to:

Event	Published when
`product.proposed`	A seller submits for review
`product.approved`	The marketplace accepts it
`product.rejected`	The marketplace sends it back
`product.drafted`	A seller takes a listing down
`product.archived`	A seller withdraws it

The submission row itself also publishes product_submission.created and product_submission.updated, carrying the status, the note and the product. See Events. Get available filter options for building a faceted search UI. Returns price ranges, option values, and categories with counts:

const filters = await client.products.filters()
// {
//   filters: [
//     { id: "price", type: "price_range", min: 9.99, max: 199.99, currency: "USD" },
//     { id: "availability", type: "availability", options: [{ id: "in_stock", count: 42 }] },
//     { id: "opt_xxx", type: "option", name: "size", label: "Size", kind: "...",
//       options: [{ id: "optv_xxx", name: "small", label: "Small", count: 12 }, ...] },
//     { id: "categories", type: "category",
//       options: [{ id: "ctg_xxx", name: "Clothing", permalink: "clothing", count: 45 }] },
//   ],
//   sort_options: [{ id: "price" }, ...],
//   default_sort: "best_selling",
//   total_count: 120,
// }

// Scoped to a specific category
const categoryFilters = await client.products.filters({
  category_id: 'ctg_xxx',
})

curl 'https://api.mystore.com/api/v3/store/products/filters' \
  -H 'X-Spree-API-Key: pk_xxx'

# Scoped to a category
curl 'https://api.mystore.com/api/v3/store/products/filters?category_id=ctg_xxx' \
  -H 'X-Spree-API-Key: pk_xxx'

Variants

A product is not the thing you buy — a variant is. The product is the listing; the variant is the actual item with a SKU, a price and stock. That distinction is worth holding onto, because everything purchasable lives on the variant:

Attribute	Description
`sku`	Stock keeping unit
`barcode`	Barcode — UPC, EAN and so on
`price`	Price in the current currency
`original_price`	Compare-at price, for showing a reduction
`weight`, `height`, `width`, `depth`	Used for delivery rates and labels
`in_stock` / `purchasable`	Whether it can be bought right now
`backorderable`	Whether it can be ordered while out of stock
`preorder` / `preorder_ships_at`	Whether it’s sold ahead of availability
`option_values`	What distinguishes it — Size: Small, Colour: Red
`options_text`	Those values as one readable string
`track_inventory`	Whether stock is counted at all

Variants also carry the customs attributes — hs_code, country_of_origin, customs_description — used when a parcel crosses a border. See Fees.

Every product has at least one variant

There’s no such thing as a product without one. A book with no size or colour still has a single variant holding its SKU, price and stock — you simply never show a picker for it.

Earlier versions of Spree had a special “master variant” alongside the real ones, which meant every query had to remember to exclude it. That concept is gone. A product’s variants are all real, all purchasable, and all the same kind of thing.

The default variant

default_variant_id names the variant that represents the product — the price shown on a listing page, and what “add to cart” means before anyone picks anything.

const product = await client.products.get('spree-tote')

product.default_variant_id // "var_xxx"
product.price              // that variant's price
product.variant_count      // 6

curl 'https://api.mystore.com/api/v3/store/products/spree-tote' \
  -H 'X-Spree-API-Key: pk_xxx'

For a single-variant product that’s the only variant. For a product with options it’s the first one, unless you say otherwise. If the default is ever removed, another is promoted automatically — a product is never left without one. Products can also carry buy_box_variant_id, naming the variant a marketplace has chosen to feature when several sellers offer the same listing.

Options make variants

A product with option types has one variant per combination. A T-shirt in three sizes and two colours is six variants:

SKU	Size	Colour
`TEE-S-R`	Small	Red
`TEE-S-G`	Small	Green
`TEE-M-R`	Medium	Red
`TEE-M-G`	Medium	Green
`TEE-L-R`	Large	Red
`TEE-L-G`	Large	Green

Adding one to an existing product:

await adminClient.products.variants.create('prod_xxx', {
  sku: 'TEE-L-R',
  options: [
    { name: 'size', value: 'Large' },
    { name: 'color', value: 'Red' },
  ],
  prices: [{ currency: 'USD', amount: '24.99' }],
  stock_levels: [{ stock_location_id: 'sloc_xxx', count_on_hand: 30 }],
})

spree api post /products/prod_xxx/variants -d '{
  "sku": "TEE-L-R",
  "options": [{ "name": "size", "value": "Large" }],
  "prices": [{ "currency": "USD", "amount": "24.99" }]
}'

Options are named by value rather than by ID, so you don’t have to look up an option value before creating a variant that uses it.

Option Types and Option Values

Option types define the axes of variation for a product (e.g., Size, Color, Material). Option values are the specific choices within each type (e.g., Small, Medium, Large). A product must have at least one option type to have multiple variants. Option types and their values are included in the product response when requested:

const product = await client.products.get('spree-tee', {
  expand: ['option_types', 'option_values'],
})

// Option types describe the axes of variation
product.option_types?.forEach(optionType => {
  console.log(optionType.label) // "Size"
})

// Option values are a separate flat array; each carries its parent's id/label
product.option_values?.forEach(value => {
  console.log(value.option_type_label, value.label) // "Size", "Small"
})

const product = await adminClient.products.get('prod_k5nR8xLq', {
  expand: ['variants'],
})

curl 'https://api.mystore.com/api/v3/store/products/spree-tee?expand=option_types,option_values' \
  -H 'X-Spree-API-Key: pk_xxx'

Option type name and label fields are translatable.

Create option types (and their values) via the Admin API. Sending option_values replaces the full set, so include every value you want to keep:

const optionType = await client.optionTypes.create({
  name: 'size',
  label: 'Size',
  option_values: [
    { name: 'small', label: 'Small', position: 1 },
    { name: 'medium', label: 'Medium', position: 2 },
    { name: 'large', label: 'Large', position: 3 },
  ],
})

spree api post /option_types -d '{
  "name": "size",
  "label": "Size",
  "option_values": [
    { "name": "small", "label": "Small" },
    { "name": "medium", "label": "Medium" }
  ]
}'

Product Types

Merchants who sell more than one kind of thing end up repeating themselves. Every pair of shoes needs Size and Colour, belongs under Footwear, and wants a Material field. Every book needs an ISBN and an author. A product type captures that once. Creating a product from a type gives it the right option types, the right categories, the right delivery profile, and a form asking for the fields that kind of product actually needs.

const shoes = await adminClient.productTypes.create({
  name: 'Footwear',
  option_type_ids: ['opt_size', 'opt_color'],
  category_ids: ['ctg_footwear'],
  delivery_profile_id: 'fp_standard',
  custom_field_definitions: [
    { id: 'cfdef_material', required: true, sort_order: 0 },
  ],
})

await adminClient.products.create({
  name: 'Trail Runner',
  product_type_id: shoes.id,
  status: 'draft',
})

curl -X POST 'https://api.mystore.com/api/v3/admin/product_types' \
  -H 'X-Spree-API-Key: sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Footwear",
    "option_type_ids": ["opt_size", "opt_color"],
    "category_ids": ["ctg_footwear"],
    "delivery_profile_id": "fp_standard"
  }'

A type is a template, not a controller

This is the part that determines how you should think about them.

Editing a product type never rewrites existing products. Add an option type to Footwear next month and the shoes you created last month are untouched.

That’s deliberate. A merchant who adds a field to a type is describing what new products should look like — not asking Spree to silently restructure a live catalogue, invalidate URLs, or change what customers can pick. So the pieces behave in two distinct ways:

Part of the type	Behaviour
Option types, categories, delivery profile	Stamped at creation. Copied onto the product, then independent
Custom field definitions	Live by reference. The form always reflects the type as it is now

Seeding is also additive — it adds what’s missing and never removes what a product already has. Reassigning a product’s type is therefore safe: it seeds the new type’s option types and categories alongside whatever was already there. If you do want an edited type to reach the products already using it, that’s an explicit action:

const { products_count } = await adminClient.productTypes.applyToProducts('pt_xxx')

curl -X POST 'https://api.mystore.com/api/v3/admin/product_types/pt_xxx/apply_to_products' \
  -H 'X-Spree-API-Key: sk_xxx'

It runs in the background and is additive like the rest — never a side effect of saving a type.

required on a type’s custom field is advisory — it marks the field in the dashboard but isn’t enforced on write, since Spree saves the product and its fields in two steps. Validate in your own tooling if you need it enforced.

A type in use can’t be deleted; its products would lose the structure they were built from.

Media

Media can be attached to a product or to individual variants. When displaying a product, show the images for the selected variant, falling back to the product’s own.

Thumbnails

Every product response includes a thumbnail_url field — the URL to the first image, ready to use without any expands. Similarly, each variant includes a thumbnail_url URL and an media_count counter. Use these fields for product listing pages to avoid loading all images:

// List products — thumbnail_url is always included
const { data: products } = await client.products.list({ limit: 12 })

products.forEach(product => {
  product.thumbnail_url // "https://cdn.../tote-front.jpg" — no expand needed
})

const { data: products } = await adminClient.products.list({ limit: 12 })

# thumbnail_url is always in the response — no ?expand needed
curl 'https://api.mystore.com/api/v3/store/products?limit=12' \
  -H 'X-Spree-API-Key: pk_xxx'

Avoid using ?expand=media on listing pages. This loads all images for every product in the response, which is unnecessary when you only need a thumbnail. Use thumbnail_url instead and only expand full media on the product detail page.

All Images

On the product detail page, expand media and variants to get the full set of images. Images are ordered by position:

const product = await client.products.get('spree-tote', {
  expand: ['media', 'variants'],
})

// The product's own images
product.media // [{ original_url: "https://cdn.../tote-front.jpg", position: 1 }, ...]

// Each variant has its own thumbnail and media_count
product.variants?.forEach(variant => {
  variant.thumbnail_url    // "https://cdn.../tote-red.jpg" — always available
  variant.media_count  // 3 — quick check without loading media
  variant.media        // full image array (only when ?expand=media)
})

const product = await adminClient.products.get('prod_86Rf07xd4z', {
  expand: ['media'],
})

curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=media,variants' \
  -H 'X-Spree-API-Key: pk_xxx'

Field	Available on	Always returned	Description
`thumbnail_url`	Product	Yes	URL to the product’s first media
`thumbnail_url`	Variant	Yes	URL to the variant’s first media
`media_count`	Variant	Yes	Number of media
`media`	Product, Variant	No	Full image array (requires `?expand=media`)

Prices

Each variant can have multiple prices — one per currency, plus additional prices from Price Lists that apply conditionally based on market, geography, customer segment, or quantity. The API automatically returns the correct price based on the current currency and market context:

Field	Description
`price`	Current selling price
`original_price`	Compare-at price (for showing strikethrough discounts)

See the Pricing guide for details on Price Lists, Price Rules, and market-specific pricing.

Digital products

A digital product is an ordinary product whose variant delivers without shipping — its delivery profile is a digital one, so buying it grants the customer a download instead of dispatching a parcel. Nothing about the catalog model changes — you still have a product, its variants, and its prices. What that variant hands over is usually a digital asset it carries (an e‑book, a design file) or a value a provider mints on demand (a license key) — but the file is the optional deliverable, not what makes the product digital. Two ideas are worth separating up front, because they are independent:

Being digital is a delivery decision. A variant is digital when its delivery profile is a digital one — that variant needs no shipping address, and a cart made up entirely of digital variants skips the delivery step at checkout.
Carrying downloadable files is a catalog decision. Any variant can own digital assets — including a physical one, so a boxed product can ship a warranty PDF or a setup guide alongside the goods.

Most digital products are both: a digital variant that carries the files it delivers. But the two are decoupled on purpose, so “ships nothing” and “hands over a file” can be mixed as a merchant needs.

Assets live on the variant

A digital asset (Spree::DigitalAsset) belongs to a variant and holds either an uploaded file or a reference to a provider that produces the deliverable on demand (see Where the file comes from below). Uploaded files go to private storage — they are only ever served through a short‑lived, signed link, never a public URL. You attach assets to a variant from the product’s Digital files card in the dashboard, or through the Admin API nested under the product:

// 1. Ask for a private-storage upload slot, then PUT the file to the returned URL.
const { direct_upload, signed_id } = await adminClient.directUploads.create({
  private: true, // digital files are only ever served through a signed link
  blob: { filename: 'guide.pdf', byte_size: file.size, checksum, content_type: 'application/pdf' },
})
await fetch(direct_upload.url, { method: 'PUT', headers: direct_upload.headers, body: file })

// 2. Attach the uploaded blob to the product's default variant.
await adminClient.products.digitalAssets.create('prod_86Rf07xd4z', {
  signed_id,
  authorized_clicks: 5, // optional — omit to inherit the store default
  authorized_days: 30,
})

curl -X POST 'https://api.mystore.com/api/v3/admin/products/prod_86Rf07xd4z/digital_assets' \
  -H 'X-Spree-API-Key: sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{ "signed_id": "eyJfcmFpbHMi...", "authorized_clicks": 5, "authorized_days": 30 }'

Digital files must be uploaded to private storage. The Admin API refuses a blob that landed on the public service — attaching never moves a file between services, so a public upload would stay publicly readable while looking attached. Request the direct upload with private: true.

Replacing an asset’s file keeps every download link that was already issued working: links resolve through the asset, not the underlying blob, so a merchant can swap a corrected file mid‑sale without breaking anyone’s access.

A purchase grants download links

When an order is placed, digital assets fulfill themselves. The digital fulfillment provider runs automatically (it needs no address and no manual action) and, for each purchased unit, creates one download link (Spree::DigitalLink) per asset on the variant. Buy three copies of a two‑file bundle and the buyer gets six links. Re‑running fulfillment is idempotent — it never duplicates links. A download link is the customer’s grant: a globally unique token, a counter of downloads spent, and its own copy of the allowance. The token is the credential — it identifies the store on its own, which is why an emailed link works without any API key. Customers reach their files two ways:

By email. On order placement, Spree::DigitalAssetMailer sends a “your files are ready” message with the links — a message of its own, separate from the order confirmation, so it can be re‑sent from the order page later.
From their account. A signed‑in customer sees every link they have ever been granted, across all their orders, through the customer downloads endpoint.

The files-ready email is only sent when the order actually has digital links and the store has consumer transactional emails enabled. A store that delivers files through its own storefront or webhooks can leave it off.

Downloading, and the allowance

A download is a GET against the link’s token. Every download runs the same guarded sequence, and the customer’s allowance is only spent once a deliverable is actually in hand:

The grant must be live — attempts remaining, and not past its expiry.
The signed‑URL window must be open — clamped to whatever is shorter, the store’s link lifetime or the link’s own remaining days.
The deliverable is produced — see providers below. This step is allowed to fail.
The download is charged — the counter is incremented under a lock.
The file is handed over — a redirect to a signed URL, or an inline body.

The ordering is deliberate: producing the deliverable comes before charging the click, so a provider outage or a missing file returns an honest error and costs the customer nothing. Two allowances govern access, both falling back to store settings when the asset leaves them blank:

Field	Meaning	Store default
`authorized_clicks`	How many times the file may be downloaded	`5`
`authorized_days`	How long after purchase the link stays valid	`7`

Store‑wide defaults and their on/off switches live at Settings → Store; the separate digital_asset_link_expire_time preference caps how long a single signed URL lives (default 5 minutes, never more than an hour) because that URL is a bearer credential. When a customer runs out of downloads or a file was replaced mid‑flight, an admin can restore access by resetting the link from the order page, which zeroes the counter and restarts the clock. Each successful download publishes an event you can subscribe to:

Event	Published when
`digital_link.downloaded`	A customer successfully downloads a file (after the click is charged)

Where the file comes from

By default a digital asset delivers its uploaded file. But the last step — “hand something over” — is pluggable through a digital asset provider, so the deliverable can instead be minted on demand: a license key from your billing system, an entitlement from internal software, or a signed link to a file on your own host. The purchase, the grant, the allowance, and the email are identical either way; only the production of the deliverable changes. A blank provider_type on an asset means the built‑in file provider — the uploaded‑file behavior described above. Registering your own provider adds it as a source on the Digital files card, so a merchant can pick it when adding an asset.

To build one, see the Build a Custom Digital Asset Provider how‑to. It covers the #deliver contract, per‑asset settings, and registration.

	Categories	Collections
Shape	Nested tree	Flat list
Membership	You assign it	Assigned, or matched by rules
Typical use	Site navigation	Merchandising and campaigns

Publications and Sales Channels

A product is visible on a Channel only when a ProductPublication record joins the two. Publications carry an optional time window so a product can be scheduled to go live and come down without code or manual toggles.

Publication state	What customers see
No publication exists	Product is not on this channel — invisible
Publication has no dates set	Live now and indefinitely
`published_at` is in the future	Scheduled — not yet visible
`unpublished_at` is in the past	Hidden — was visible, now sunset
Within the window	Live

Product status (draft / active / archived) is the outer gate: a Draft or Archived product is hidden on every channel regardless of its publication window. Only active products consult publication state.

Reading publications

Publications appear in the API under product_publications when expanded; the same data is available through the channels association as a flat list of joined channels.

const product = await adminClient.products.get('prod_abc', {
  expand: ['product_publications', 'channels'],
})

curl 'https://api.mystore.com/api/v3/admin/products/prod_abc?expand=product_publications,channels' \
  -H 'X-Spree-API-Key: sk_xxx'

Response

{
  "data": {
    "id": "prod_abc",
    "status": "active",
    "channels": [
      { "id": "ch_online", "code": "online", "name": "Online Store" }
    ],
    "product_publications": [
      {
        "id": "pp_xyz",
        "channel_id": "ch_online",
        "published_at": "2026-07-01T00:00:00Z",
        "unpublished_at": null
      }
    ]
  }
}

Writing publications

Two write surfaces serve different shapes:

Per-product, full-set — PATCH /api/v3/admin/products/{id} with a product_publications array. The array represents the complete desired state; channels absent from the payload are detached.

await adminClient.products.update('prod_abc', {
  product_publications: [
    { channel_id: 'ch_online' },
    { channel_id: 'ch_pos', published_at: '2026-07-01T00:00:00Z' },
  ],
})

curl -X PATCH 'https://api.mystore.com/api/v3/admin/products/prod_abc' \
  -H 'X-Spree-API-Key: sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "product_publications": [
      { "channel_id": "ch_online" },
      { "channel_id": "ch_pos", "published_at": "2026-07-01T00:00:00Z" }
    ]
  }'

Per-channel, bulk — POST /api/v3/admin/channels/{id}/add_products and POST /api/v3/admin/channels/{id}/remove_products for publishing or unpublishing many products at once. Idempotent: re-publishing an already-published product is a no-op for its window unless published_at / unpublished_at are explicitly passed.

await adminClient.channels.addProducts('ch_online', {
  product_ids: ['prod_abc', 'prod_def'],
  published_at: '2026-07-01T00:00:00Z',
})

await adminClient.channels.removeProducts('ch_online', {
  product_ids: ['prod_abc'],
})

curl -X POST 'https://api.mystore.com/api/v3/admin/channels/ch_online/add_products' \
  -H 'X-Spree-API-Key: sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "product_ids": ["prod_abc", "prod_def"],
    "published_at": "2026-07-01T00:00:00Z"
  }'

curl -X POST 'https://api.mystore.com/api/v3/admin/channels/ch_online/remove_products' \
  -H 'X-Spree-API-Key: sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{ "product_ids": ["prod_abc"] }'

The two surfaces converge on the same spree_product_publications table — pick whichever matches your call site.

Listing products on a specific channel

Storefronts and client.products.list() calls return only products published on the resolved channel (live within the publication window, with the product itself active). To scope a Store SDK request to a non-default channel — e.g. a POS app querying for the POS catalog — set the channel code on the client or per-request:

// Client-level default
const client = createClient({ baseUrl, publishableKey, channel: 'pos' })

// Per-request override
const posProducts = await client.products.list({}, { channel: 'pos' })

// filter by the channel's code via Ransack (q[channels_code_eq])
const { data: products } = await adminClient.products.list({ channels_code_eq: 'pos' })

curl 'https://api.mystore.com/api/v3/store/products' \
  -H 'X-Spree-API-Key: pk_xxx' \
  -H 'X-Spree-Channel: pos'

For Admin API filtering across channels (back-office reports, admin UI lists), use Ransack instead: q[channels_id_in][]=ch_xxx. See Sales Channels for the resolution rules.

Auto-publish on the default channel

When a product is created via the dashboard, it is auto-published on the store’s default channel (the only channel where default = true). The Admin API does not auto-publish — supply product_publications: [{ channel_id }] on create or call add_products afterwards. See Sales Channels for the full channel lifecycle, including default-channel resolution and the X-Spree-Channel header.

Sales Channels — Channels, publications, and order attribution
Pricing — Price Lists, Price Rules, and market-specific pricing
Inventory — Stock management and backorders
Media — Image management
Build a Custom Digital Asset Provider — Deliver a license key or external file instead of an uploaded one
Translations — Translating product content
Search & Filtering — Full-text search and Ransack filtering
Store SDK Products — Listing, fetching, filtering, and categories via client.products
Querying — API filtering, sorting, and pagination

Develop

Overview

Product Attributes

Listing Products

Getting a Product

Managing Products

Seller submissions

The lifecycle

The submission record

Submitting, as a seller

Deciding, as the marketplace

Leaving review is a decision

Events

Product Filters

Variants

Every product has at least one variant

The default variant

Options make variants

Option Types and Option Values

Product Types

A type is a template, not a controller

Media

Thumbnails

All Images

Prices

Digital products

Assets live on the variant

A purchase grants download links

Downloading, and the allowance

Where the file comes from

Categories

Publications and Sales Channels

Reading publications

Writing publications

Listing products on a specific channel

Auto-publish on the default channel

​Overview

​Product Attributes

​Listing Products

​Getting a Product

​Managing Products

​Seller submissions

​The lifecycle

​The submission record

​Submitting, as a seller

​Deciding, as the marketplace

​Leaving review is a decision

​Events

​Product Filters

​Variants

​Every product has at least one variant

​The default variant

​Options make variants

​Option Types and Option Values

​Product Types

​A type is a template, not a controller

​Media

​Thumbnails

​All Images

​Prices

​Digital products

​Assets live on the variant

​A purchase grants download links

​Downloading, and the allowance

​Where the file comes from

​Categories

​Publications and Sales Channels

​Reading publications

​Writing publications

​Listing products on a specific channel

​Auto-publish on the default channel

​Related Documentation

Overview

Product Attributes

Listing Products

Getting a Product

Managing Products

Seller submissions

The lifecycle

The submission record

Submitting, as a seller

Deciding, as the marketplace

Leaving review is a decision

Events

Product Filters

Variants

Every product has at least one variant

The default variant

Options make variants

Option Types and Option Values

Product Types

A type is a template, not a controller

Media

Thumbnails

All Images

Prices

Digital products

Assets live on the variant

A purchase grants download links

Downloading, and the allowance

Where the file comes from

Categories

Publications and Sales Channels

Reading publications

Writing publications

Listing products on a specific channel

Auto-publish on the default channel

Related Documentation