> ## Documentation Index
> Fetch the complete documentation index at: https://docs.snappy.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get products
> Use this endpoint to retrieve a paginated list of products across all collections. Returns the same response shape as the collection-scoped endpoint, without requiring a collectionId.
###### Filtering options
- `filter[catalog]` - `marketplace`, `swag`, `giftCards`, or `donations` (defaults to `marketplace`)
- `filter[search]` - free-text search across product title, category, and brand
- `filter[brandId]` - comma-separated list of brand IDs (OR semantics)
- `filter[brandName]` - case-insensitive substring search on brand name
- `filter[tagId]` - comma-separated list of tag IDs (OR semantics)
- `filter[price][gte]` / `filter[price][lte]` - inclusive minimum / maximum price filter
- `location` - ISO 3166-1 alpha-2 country code (default `US`) to scope pricing
- `Snappy-Account-Id` / `Snappy-Company-Id` headers - optional account/company scoping
###### Please note
- Variants are not returned on this endpoint. Use GET /v3/products/{productId}/variants to retrieve the variants list for a specific product.
#### Permissions
- Requires: `products:read`
## OpenAPI
````yaml get /v3/products
openapi: 3.0.3
info:
title: Snappy Public API v3
version: 3.0.0
contact:
name: Snappy Support
email: info@snappy.com
description: >-
Welcome to the Snappy API reference documentation!
You can use this API to integrate with Snappy and spread smiles to your
employees/clients/customers and much more.
So let's get started!
servers:
- url: https://api.snappy.com/public-api
description: Base API URL
- url: https://mtls-api.snappy.com/public-api
description: >-
## mTLS URL
You can also use mTLS to enhance your API security. To get your specific
certificates please contact our support.
Once you configure the certificated correctly, you need to also update
endpoints to use the following secure api base URL:
security: []
tags:
- name: Products
description: >-
Use these endpoints to retrieve products and tags for building catalog and
browse experiences in your UI.
- name: Collections
description: >-
Use these endpoints to retrieve products within curated collections for
marketplace and browse experiences.
- name: Variants
description: >-
Use these endpoints to retrieve variants, variant pricing, and country
availability for orderable product SKUs.
- name: Billing Methods
description: >-
A **Billing Method** is the funding source attached to an **Account** -
for example, a Purchase Order (PO), Invoice, Prepay deposit, or Credit
Card. Use these endpoints to retrieve billing method details such as
remaining balance, status, and expiration.
- name: Accounts
description: >-
An **Account** is a sub-entity within a **Company**, used to organize
campaigns and gift sends. Use these endpoints to list, retrieve, and
create accounts.
- name: API Keys
description: >-
Use these endpoints to manage API keys for programmatic access. Key
management requires company owner privileges.
- name: Orders
description: >-
Use these endpoints to place, retrieve, cancel, and validate orders and
shipping addresses.
paths:
/v3/products:
get:
tags:
- Products
summary: Get products
description: >-
Use this endpoint to retrieve a paginated list of products across all
collections. Returns the same response shape as the collection-scoped
endpoint, without requiring a collectionId.
###### Filtering options
- `filter[catalog]` - `marketplace`, `swag`, `giftCards`, or `donations`
(defaults to `marketplace`)
- `filter[search]` - free-text search across product title, category,
and brand
- `filter[brandId]` - comma-separated list of brand IDs (OR semantics)
- `filter[brandName]` - case-insensitive substring search on brand name
- `filter[tagId]` - comma-separated list of tag IDs (OR semantics)
- `filter[price][gte]` / `filter[price][lte]` - inclusive minimum /
maximum price filter
- `location` - ISO 3166-1 alpha-2 country code (default `US`) to scope
pricing
- `Snappy-Account-Id` / `Snappy-Company-Id` headers - optional
account/company scoping
###### Please note
- Variants are not returned on this endpoint. Use GET
/v3/products/{productId}/variants to retrieve the variants list for a
specific product.
#### Permissions
- Requires: `products:read`
parameters:
- schema:
$ref: '#/components/schemas/ProductCatalogV3'
required: false
description: >-
Which product catalog to search. Required on product list/search
endpoints. Defaults to marketplace.
name: filter[catalog]
in: query
- schema:
type: string
pattern: ^[^<>]*$
description: Free-text search across product title, category, and brand.
example: tumbler
required: false
description: Free-text search across product title, category, and brand.
name: filter[search]
in: query
- schema:
type: number
nullable: true
minimum: 0
description: Inclusive minimum price filter.
example: 10
required: false
description: Inclusive minimum price filter.
name: filter[price][gte]
in: query
- schema:
type: number
nullable: true
minimum: 0
description: Inclusive maximum price filter.
example: 200
required: false
description: Inclusive maximum price filter.
name: filter[price][lte]
in: query
- schema:
type: string
pattern: ^[A-Z]{2}$
default: US
description: ISO 3166-1 alpha-2 country code.
example: US
required: false
description: ISO 3166-1 alpha-2 country code.
name: location
in: query
- schema:
type: array
items:
$ref: '#/components/schemas/ProductIncludeV3'
description: Related entities to include.
example:
- brand
- tags
required: false
description: Related entities to include.
name: include
in: query
style: form
explode: false
- schema:
type: array
items:
$ref: '#/components/schemas/ProductListFieldsV3'
description: Computed or expanded product fields for list responses.
example:
- priceRange
- variantsCount
required: false
description: Computed or expanded product fields for list responses.
name: fields
in: query
style: form
explode: false
- schema:
type: string
description: Opaque continuation token from the previous response links.next.
example: opaqueCursorToken
required: false
description: Opaque continuation token from the previous response links.next.
name: page[cursor]
in: query
- schema:
type: integer
minimum: 1
maximum: 300
default: 100
description: Number of products per page (max 300, default 100).
example: 100
required: false
description: Number of products per page (max 300, default 100).
name: page[size]
in: query
- schema:
type: string
pattern: ^-?(minPrice|createdAt)$
description: >-
JSON:API sort parameter. Single field; prefix with `-` for
descending.
example: '-minPrice'
required: false
description: >-
JSON:API sort parameter. Single field; prefix with `-` for
descending.
name: sort
in: query
- schema:
type: array
items:
type: string
description: Comma-separated list of brand ids (OR semantics).
example:
- brand12345
- brand67890
required: false
description: Comma-separated list of brand ids (OR semantics).
name: filter[brandId]
in: query
style: form
explode: false
- schema:
type: string
description: Case-insensitive substring search on brand name.
example: Sample Brand
required: false
description: Case-insensitive substring search on brand name.
name: filter[brandName]
in: query
- schema:
type: array
items:
type: string
description: Comma-separated list of tag ids (OR semantics).
example:
- tag12345
required: false
description: Comma-separated list of tag ids (OR semantics).
name: filter[tagId]
in: query
style: form
explode: false
- schema:
type: string
description: Optional account identifier for swag validation/filtering.
example: acc123456
required: false
description: Optional account identifier for swag validation/filtering.
name: snappy-account-id
in: header
- schema:
type: string
description: Optional company identifier for swag validation/filtering.
example: cmp123456
required: false
description: Optional company identifier for swag validation/filtering.
name: snappy-company-id
in: header
responses:
'200':
description: Paginated list of products.
content:
application/json:
schema:
$ref: '#/components/schemas/GetProductsV3Response'
'400':
description: Bad Request - Invalid query parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseV3'
example:
message: Request validation failed.
errorCode: 400_PBLC_001
errors:
- errorCode: 400_PBLC_001
message: >-
filter[price][gte] must be less than or equal to
filter[price][lte]
path: queryStringParameters.filter[price][gte]
'403':
description: Forbidden.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseV3'
'422':
description: Unprocessable Entity - Products not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseV3'
security:
- ApiKeyAuthentication: []
components:
schemas:
ProductCatalogV3:
type: string
enum:
- marketplace
- swag
- giftCards
- donations
default: marketplace
description: >-
Which product catalog to search. Required on product list/search
endpoints. Defaults to marketplace.
example: marketplace
ProductIncludeV3:
type: string
enum:
- brand
- tags
description: Related entities to include.
example: brand
ProductListFieldsV3:
type: string
enum:
- priceRange
- variantsCount
- total
description: Computed or expanded fields for product list responses.
example: priceRange
GetProductsV3Response:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ProductV3'
description: Products for the requested page.
links:
$ref: '#/components/schemas/PaginationLinksV3'
total:
type: integer
minimum: 0
description: >-
Root-level total of products matching the request filters (ignores
pagination). Returned only when `fields=total`.
example: 716
required:
- data
- links
description: >-
Paginated product list response (cursor pagination). `total` is present
only when requested via `fields=total`.
ErrorResponseV3:
type: object
properties:
message:
type: string
description: Human-readable error message.
example: Product not found.
errorCode:
type: string
description: Structured error code.
example: 404_PROD_001
errors:
type: array
items:
type: object
properties:
message:
type: string
example: Product with id 'q1w2e3r4t5' was not found
path:
type: string
description: Dot-separated path to the field that caused the error.
example: pathParameters.productId
errorCode:
type: string
example: 404_PROD_001
required:
- message
- path
description: Optional field-level error details.
required:
- message
- errorCode
description: Standard v3 error envelope.
ProductV3:
type: object
properties:
id:
type: string
description: Stable product identifier.
example: 655277e68e0719000d6c3fd5
title:
type: string
description: Product title.
example: NFL 25-Layer StadiumView Wall Art
createdAt:
type: string
format: date-time
description: Product creation date.
example: '2026-05-11T10:53:01.026Z'
media:
type: array
items:
$ref: '#/components/schemas/MediaV3'
description: Product media.
category:
type: object
properties:
fullName:
type: string
description: Full taxonomy path.
example: Fan Merchandise / NFL / NFL Memorabilia / Autographed Helmets
required:
- fullName
description: Product category.
catalog:
type: string
enum:
- marketplace
- swag
- giftCards
- donations
description: Product catalog.
example: marketplace
brand:
$ref: '#/components/schemas/ProductBrandV3'
tags:
type: array
items:
$ref: '#/components/schemas/ProductTagV3'
description: Returned only when `include=tags`.
options:
type: array
items:
$ref: '#/components/schemas/ProductOptionV3'
description: Aggregated variant options.
priceRange:
$ref: '#/components/schemas/PriceRangeV3'
variantsCount:
type: integer
minimum: 0
description: Returned only when `fields` includes `variantsCount`.
example: 9
required:
- id
- title
- createdAt
- media
- category
- catalog
description: >-
Product (VariationGroup). Optional fields are returned only when
requested via `include` (related entities) or `fields`
(computed/expanded). Field availability depends on the calling endpoint
- see the `include` / `fields` parameter descriptions.
PaginationLinksV3:
type: object
properties:
first:
type: string
nullable: true
description: Link to the first page.
example: >-
/v3/products/655277e68e0719000d6c3fd5/variants?page[size]=100&page[number]=1
next:
type: string
nullable: true
description: Link to the next page, or `null` on the final page.
example: >-
/v3/products/655277e68e0719000d6c3fd5/variants?page[size]=100&page[number]=2
prev:
type: string
nullable: true
description: Link to the previous page, or `null` when not applicable.
example: null
required:
- first
- next
- prev
description: >-
Top-level JSON:API-style pagination links for paginated list responses.
`first`, `next`, and `prev` are all required and all nullable. `prev` is
`null` on cursor-paginated endpoints (backward navigation not
supported).
MediaV3:
type: object
properties:
type:
type: string
enum:
- image
- video
description: Media type.
example: image
src:
type: string
format: uri
description: Media source URL.
example: >-
https://media.snappy.com/image/o1xc17wfbda6cl91hm0r6_picture-1.jpg?w=1000&h=1000&q=80&f=auto
required:
- type
- src
description: A media item for v3 endpoints.
ProductBrandV3:
type: object
nullable: true
properties:
id:
type: string
description: Brand ID.
example: 6511b55142c420000d083a55
name:
type: string
description: Brand name.
example: YouTheFan
description:
type: string
nullable: true
description: Brand description.
example: Officially licensed NFL fan merchandise.
required:
- id
- name
- description
description: >-
Product or variant brand. Returned only when `include=brand`. Nullable
when the product or variant has no brand.
ProductTagV3:
type: object
properties:
id:
type: string
description: Tag ID.
example: tag12345
name:
type: string
description: Tag name.
example: Sustainable
required:
- id
- name
description: Product tag.
ProductOptionV3:
type: object
properties:
name:
type: string
description: Option name.
example: nfl_team
displayName:
type: string
description: Option display name.
example: Team
displayType:
type: string
description: Display type hint.
example: image
values:
type: array
items:
$ref: '#/components/schemas/ProductOptionValueV3'
description: Available values.
required:
- name
- displayName
- displayType
- values
description: Aggregated product option.
PriceRangeV3:
type: object
properties:
min:
$ref: '#/components/schemas/PriceV3'
max:
$ref: '#/components/schemas/PriceV3'
required:
- min
- max
description: >-
Min/max pricing across the product's variants. Returned only when
`fields` includes `priceRange`.
ProductOptionValueV3:
type: object
properties:
displayName:
type: string
description: Option value display name.
example: Denver Broncos
value:
type: string
description: Option value.
example: Denver Broncos
firstSelectableVariant:
$ref: '#/components/schemas/VariantV3'
required:
- displayName
- value
- firstSelectableVariant
description: Product option value.
PriceV3:
type: object
properties:
amount:
type: number
example: 244.99
currency:
type: string
description: ISO 4217 currency code.
example: USD
required:
- amount
- currency
description: Variant price in a given currency.
VariantV3:
type: object
properties:
id:
type: string
description: Variant identifier.
example: FB6bgFV4lf
productId:
type: string
description: Parent product identifier.
example: 655277e68e0719000d6c3fd5
title:
type: string
description: Variant title.
example: NFL 25-Layer StadiumView Wall Art
selectedOptions:
type: object
additionalProperties:
type: string
description: Selected option values for this variant.
example:
nfl_team: Denver Broncos
taxable:
type: boolean
description: Whether the variant is taxable.
example: true
media:
type: array
items:
$ref: '#/components/schemas/MediaV3'
description: Variant media.
personalization:
$ref: '#/components/schemas/PersonalizationV3'
price:
$ref: '#/components/schemas/PriceV3'
priceBreakdown:
$ref: '#/components/schemas/PriceBreakdownV3'
descriptionHtml:
type: string
description: HTML full narrative description.
example: The 25-Layer StadiumViews 3D Wall Art
details:
$ref: '#/components/schemas/VariantDetailsV3'
brand:
$ref: '#/components/schemas/ProductBrandV3'
shippingRequired:
type: boolean
required:
- id
- title
- selectedOptions
- taxable
- media
- personalization
description: First selectable variant for this option value.
PersonalizationV3:
type: object
nullable: true
properties:
isPersonalized:
type: boolean
description: Whether the variant is personalizable.
example: true
personalizationTemplateFields:
type: array
items:
type: string
description: Personalization template field names.
example:
- firstName
- lastName
- department
required:
- isPersonalized
- personalizationTemplateFields
description: Personalization metadata, or null when unavailable.
PriceBreakdownV3:
type: object
properties:
ddp:
type: number
description: Delivered Duty Paid charges (duties + import taxes).
example: 0
shippingFee:
type: number
example: 0
itemPrice:
type: number
description: Base item price before shipping/duties.
example: 244.99
required:
- ddp
- shippingFee
- itemPrice
description: Detailed breakdown of the variant price.
VariantDetailsV3:
type: object
properties:
includes:
type: string
nullable: true
description: HTML content describing what is included.
example: Set of 4 glasses (12oz each)
features:
type: string
nullable: true
description: HTML product highlights.
example:
specifications:
type: object
nullable: true
additionalProperties:
type: string
description: Structured key-value non-regulatory specifications.
example:
material: lead-free glass
capacity: 12oz
dimensions: 4.5' tall
notices:
type: object
nullable: true
additionalProperties:
type: string
description: Structured key-value regulatory notices.
example:
prop65Warning: Warning text
description: >-
Variant-level structured details wrapper. Returned only when `fields`
includes `details`.
securitySchemes:
ApiKeyAuthentication:
type: apiKey
in: header
name: X-Api-Key
description: |-
## Company Level Authentication
Include your API key in the `X-Api-Key` header for every request:
```
X-Api-Key: YOUR_API_KEY
```
````