> ## 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 product recommendations
> Use this endpoint to retrieve products related to a given source product.
###### Optional parameters
- `filter[price][gte]` / `filter[price][lte]` - restrict recommendations to a price range. Both bounds must be supplied together.
- `collectionId` - restrict recommendations to products in a given collection.
- `page[limit]` - control the size of the returned set (0-20).
- `include=brand,tags` - return related entities in each recommended product.
###### Please note
- At most `page[limit]` products are returned.
- This endpoint is not paginated.
- Returns `404` (`404_PROD_001`) when the source `productId` does not exist.
- Returns `422` (`422_PBLC_003`) when `collectionId` references a collection that does not exist or is not accessible.
#### Permissions
- Requires: `products:read`
## OpenAPI
````yaml get /v3/products/{productId}/recommendations
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/{productId}/recommendations:
get:
tags:
- Products
summary: Get product recommendations
description: >-
Use this endpoint to retrieve products related to a given source
product.
###### Optional parameters
- `filter[price][gte]` / `filter[price][lte]` - restrict recommendations
to a price range. Both bounds must be supplied together.
- `collectionId` - restrict recommendations to products in a given
collection.
- `page[limit]` - control the size of the returned set (0-20).
- `include=brand,tags` - return related entities in each recommended
product.
###### Please note
- At most `page[limit]` products are returned.
- This endpoint is not paginated.
- Returns `404` (`404_PROD_001`) when the source `productId` does not
exist.
- Returns `422` (`422_PBLC_003`) when `collectionId` references a
collection that does not exist or is not accessible.
#### Permissions
- Requires: `products:read`
parameters:
- schema:
type: string
pattern: ^[A-Za-z0-9]{8,}$
description: Stable identifier of the source product.
example: 655277e68e0719000d6c3fd5
required: true
description: Stable identifier of the source product.
name: productId
in: path
- schema:
type: string
pattern: ^[A-Z]{2}$
description: >-
ISO 3166-1 alpha-2 country code used to scope pricing and
availability.
example: US
required: true
description: >-
ISO 3166-1 alpha-2 country code used to scope pricing and
availability.
name: location
in: query
- schema:
type: number
nullable: true
minimum: 0
description: >-
Inclusive minimum price. Must be sent together with
`filter[price][lte]`.
example: 10
required: false
description: >-
Inclusive minimum price. Must be sent together with
`filter[price][lte]`.
name: filter[price][gte]
in: query
- schema:
type: number
nullable: true
minimum: 0
description: >-
Inclusive maximum price. Must be sent together with
`filter[price][gte]`.
example: 50
required: false
description: >-
Inclusive maximum price. Must be sent together with
`filter[price][gte]`.
name: filter[price][lte]
in: query
- schema:
type: string
description: >-
Restrict recommendations to products belonging to the given
collection.
example: 6527bb3567f414000c15d2c7
required: false
description: >-
Restrict recommendations to products belonging to the given
collection.
name: collectionId
in: query
- schema:
type: integer
nullable: true
minimum: 0
maximum: 20
default: 10
description: Maximum number of recommendations to return.
example: 10
required: false
description: Maximum number of recommendations to return.
name: page[limit]
in: query
- schema:
type: array
items:
$ref: '#/components/schemas/ProductIncludeV3'
description: >-
Comma-separated related entities to expand in each recommended
product.
example:
- brand
- tags
required: false
description: >-
Comma-separated related entities to expand in each recommended
product.
name: include
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: Recommended products.
content:
application/json:
schema:
$ref: '#/components/schemas/ProductRecommendationsResponseV3'
'400':
description: Bad Request - Invalid path or query parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseV3'
example:
message: Request validation failed.
errorCode: 400_PBLC_001
'404':
description: Not Found - Source product does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseV3'
example:
message: Product not found.
errorCode: 404_PROD_001
'422':
description: Unprocessable Entity - Invalid collection filter.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseV3'
example:
message: Collection doesn’t exist
errorCode: 422_PBLC_003
security:
- ApiKeyAuthentication: []
components:
schemas:
ProductIncludeV3:
type: string
enum:
- brand
- tags
description: Related entities to include.
example: brand
ProductRecommendationsResponseV3:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ProductV3'
description: >-
Recommended products, ordered by relevance. Empty when no qualifying
recommendations are found.
required:
- data
description: Product recommendations response.
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
description: Product catalog.
example: marketplace
type:
type: string
enum:
- physical
- digital
- giftCard
- donation
description: Product type.
example: physical
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
- type
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.
`type` is a **single value** (not an array).
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'
partnerPrice:
allOf:
- $ref: '#/components/schemas/PriceV3'
- description: >-
Partner-specific price for the requested location. Returned only
for partner companies when pricing is requested via `fields`
(same as `price`). Omitted for non-partner companies.
example:
amount: 45.7
currency: usd
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'
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
```
````