Get collections

curl --request GET \
  --url https://api.snappy.com/public-api/v3/collections \
  --header 'X-Api-Key: <api-key>' \
  --header 'snappy-account-id: <snappy-account-id>'

{
  "data": [
    {
      "id": "64a1234567890abcdef12345",
      "name": "Birthday Gifts",
      "tags": [
        "gifts"
      ],
      "media": [
        {
          "type": "image",
          "src": "https://media.snappy.com/image/o1xc17wfbda6cl91hm0r6_picture-1.jpg?w=1000&h=1000&q=80&f=auto"
        }
      ],
      "coverImage": {
        "type": "image",
        "src": "https://media.snappy.com/image/o1xc17wfbda6cl91hm0r6_picture-1.jpg?w=1000&h=1000&q=80&f=auto"
      },
      "rank": 10,
      "description": "<string>",
      "priceRange": {
        "min": 25,
        "max": 200
      },
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "createdVia": "dashboard"
    }
  ],
  "links": {
    "first": "/v3/collections?page[number]=1&page[size]=100&filter[location]=US",
    "next": "/v3/collections?page[number]=2&page[size]=100&filter[location]=US",
    "prev": null
  },
  "meta": {
    "total": 42
  }
}

Collections

Get collections

Use this endpoint to retrieve a paginated list of Collections available to the calling Account. Use this when you want to render a collection browse experience - a homepage tile grid, a budget-filtered category page, or a swag store landing page.

####### Filtering options**

filter[location] - comma-separated ISO 3166-1 alpha-2 country codes (e.g. US,CA). Only Collections supporting all requested locations are returned. Thumbnails and priceRange use the first location in the list. Defaults to US.
filter[maxPrice] - budget bucket selector that controls which thumbnail set is returned.
filter[tag] - comma-separated collection tags. One or more of gifts, swag, custom.
filter[search] - free-text search on collection name (max 100 characters).

####### Pagination and sorting**

page[number] - 1-indexed page number (default 1).
page[size] - number of collections per page (max 150, default 100).
sort - rank (default - curated display order), name, -name, createdAt, or -createdAt.

Field expansion

fields - comma-separated list of optional fields to include. One or more of priceRange, description, createdAt, updatedAt, createdBy, updatedBy, createdVia.

Required headers

Snappy-Account-Id - account scope.

Optional headers

Snappy-Company-Id - further scope to a specific Company within the Account.

Please note

Uses page-number pagination, unlike GET /v3/collections/{collectionId}/products which uses cursor pagination. The response includes a top-level links object (first, next, prev) and a meta.total count of Collections matching the supplied filters.
Returns Collections by curated rank by default - lower rank values surface first.
Returns 404 if the supplied Snappy-Account-Id does not match a known Account.

Permissions

Requires: collections:read

GET

collections

Get collections

curl --request GET \
  --url https://api.snappy.com/public-api/v3/collections \
  --header 'X-Api-Key: <api-key>' \
  --header 'snappy-account-id: <snappy-account-id>'

{
  "data": [
    {
      "id": "64a1234567890abcdef12345",
      "name": "Birthday Gifts",
      "tags": [
        "gifts"
      ],
      "media": [
        {
          "type": "image",
          "src": "https://media.snappy.com/image/o1xc17wfbda6cl91hm0r6_picture-1.jpg?w=1000&h=1000&q=80&f=auto"
        }
      ],
      "coverImage": {
        "type": "image",
        "src": "https://media.snappy.com/image/o1xc17wfbda6cl91hm0r6_picture-1.jpg?w=1000&h=1000&q=80&f=auto"
      },
      "rank": 10,
      "description": "<string>",
      "priceRange": {
        "min": 25,
        "max": 200
      },
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "createdVia": "dashboard"
    }
  ],
  "links": {
    "first": "/v3/collections?page[number]=1&page[size]=100&filter[location]=US",
    "next": "/v3/collections?page[number]=2&page[size]=100&filter[location]=US",
    "prev": null
  },
  "meta": {
    "total": 42
  }
}

Authorizations

X-Api-Key

string

header

required

Company Level Authentication

Include your API key in the X-Api-Key header for every request:

X-Api-Key: YOUR_API_KEY

Headers

snappy-account-id

string

required

Account identifier.

Example:

"acc123456"

snappy-company-id

string

Optional company identifier.

Example:

"cmp123456"

Query Parameters

filter[location]

string

default:US

Comma-separated ISO 3166-1 alpha-2 country codes. Only collections supporting all locations are returned.

Pattern: ^([A-Z]{2})(,[A-Z]{2})*$

Example:

"US,CA"

filter[maxPrice]

number | null

Budget bucket selector for thumbnails.

Required range: 0 <= x <= 99999

Example:

80

filter[tag]

enum<string>[]

Comma-separated collection tags (gifts, swag, custom).

Available options:

gifts,

swag,

custom

Example:

["gifts", "swag"]

filter[search]

string

Free-text search on collection name (max 100 characters).

Maximum string length: 100

Example:

"birthday"

fields

enum<string>[]

Optional fields to include.

Available options:

priceRange,

description,

createdAt,

updatedAt,

createdVia

Example:

["priceRange", "description"]

sort

enum<string>

default:rank

Sort field. Prefix with - for descending. Defaults to rank.

Available options:

rank,

name,

-name,

createdAt,

-createdAt

Example:

"rank"

page[number]

integer

default:1

1-indexed page number.

Required range: x >= 1

Example:

1

page[size]

integer

default:100

Number of collections per page (max 150, default 100).

Required range: 1 <= x <= 150

Example:

100

Response

Page-number paginated list of collections.

Page-number paginated collection list response.

data

object[]

required

Collections for the requested page.

Show child attributes

links

object

required

Top-level JSON:API-style pagination links for collection list responses.

Show child attributes