Skip to main content
POST
/
v3
/
products
/
search
Search products (body-based filters)
curl --request POST \
  --url https://api.snappy.com/v3/products/search \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "search": "nfl wall art",
  "type": "physical",
  "brandName": "you",
  "brandId": [
    "6511b55142c420000d083a55"
  ],
  "tagId": [
    "6527bb3567f414000c15d2c7"
  ],
  "price": {
    "gte": 10,
    "lte": 50
  },
  "productIds": [
    "655277e68e0719000d6c3fd5"
  ]
}
'
{
  "data": [
    {
      "id": "a1b2c3d4e5",
      "title": "Iphone 17 Pro Max",
      "createdAt": "2026-01-15T10:30:00Z",
      "media": [
        {
          "type": "image",
          "src": "https://media.snappy.com/image/asset123?w=1000&h=1000&q=80&f=auto"
        }
      ],
      "category": {
        "fullName": "gifts / electronics / iphones"
      },
      "catalog": "marketplace",
      "type": "physical",
      "variantsCount": 123,
      "brand": {
        "id": "621f9d4b1e675adcbc196159",
        "name": "Apple",
        "description": "Cute pet brand"
      },
      "tags": [
        {
          "id": "t1",
          "name": "Popular"
        }
      ],
      "priceRange": {
        "min": {
          "amount": 10,
          "currency": "usd"
        },
        "max": {
          "amount": 10,
          "currency": "usd"
        }
      }
    }
  ],
  "links": {
    "first": "/v3/collections/abc/products?page[size]=100",
    "next": "/v3/collections/abc/products?page[cursor]=cursor_abc123&page[size]=100",
    "prev": "<string>"
  },
  "total": 10000
}

Authorizations

​
X-Api-Key
string
header
required

Partner API key. Finalized per partner integration agreement.

Headers

​
Snappy-Account-Id
string

Optional account identifier for scoping/validation/filtering.

​
Snappy-Company-Id
string

Optional company identifier for scoping/validation/filtering.

Query Parameters

​
location
string
default:US

ISO 3166-1 alpha-2 country code (default US).

Pattern: ^[A-Z]{2}$
​
filter[catalog]
enum<string>

Which product catalog to search. Omit to search both marketplace and swag (no default).

Product catalog. As a query value, omit filter[catalog] to search both catalogs.

Available options:
marketplace,
swag
Example:

"marketplace"

​
include
enum<string>[]

Related entities to include (JSON:API include), comma-separated. Supported values: brand, tags. Returned as full objects.

Available options:
brand,
tags
​
fields
enum<string>[]

Comma-separated list of computed/expanded fields for product list endpoints.

  • priceRange — { min: Price, max: Price }.
  • variantsCount — total variants for the product.
  • total — total products matching the request filters (ignores pagination). Returned as a root-level field.
  • full — every field above.
Available options:
priceRange,
variantsCount,
total,
full
​
page[cursor]
string

Opaque continuation token returned by the previous response's links.next. Omit on the first request. Cursors are opaque — clients must not parse or fabricate them.

​
page[size]
integer
default:100

Number of products to return per page (max 300, default 100).

Required range: 1 <= x <= 300
​
sort
string

JSON:API sort parameter. Comma-separated fields; prefix with - for descending. Sortable fields: minPrice, createdAt.

Pattern: ^-?(minPrice|createdAt)(,-?(minPrice|createdAt))*$
Example:

"-createdAt,minPrice"

Body

application/json

Body-based filters for POST /v3/products/search. Mirrors the query filters of GET /v3/products. For multi-value filters, pass arrays.

​
search
string

Free-text search across product title / category / brand.

Example:

"nfl wall art"

​
type
enum<string>

Product type. Used both as the value of Product.type and as the filter value for filter[type].

Available options:
physical,
digital,
giftCard,
donation
Example:

"physical"

​
brandName
string

Substring search on brand name.

Example:

"you"

​
brandId
string[]

Brand id(s). OR semantics.

Example:
["6511b55142c420000d083a55"]
​
tagId
string[]

Tag id(s). OR semantics.

Example:
["6527bb3567f414000c15d2c7"]
​
price
object
​
productIds
string[]

Restrict results to a specific set of product ids (VariationGroup ids). Max 100. ANDed with the other filters.

Maximum array length: 100

Response

Paginated list of products.

Paginated product list response. total is present only when requested via fields=total or fields=full.

​
data
object[]
required
​
links
object
required

Top-level JSON:API-style pagination links for paginated list responses. first is always present. next is null on the final page. prev is null on the first page (and on cursor-paginated endpoints where backward navigation is not supported).

​
total
integer

Total number of products matching the request filters (ignores pagination). Returned only when fields=total or fields=full.

Required range: x >= 0
Example:

10000

Last modified on June 3, 2026