> ## 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 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` ## OpenAPI ````yaml get /v3/collections 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/collections: get: tags: - Collections summary: Get collections description: >- 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` parameters: - schema: type: string pattern: ^([A-Z]{2})(,[A-Z]{2})*$ default: US description: >- Comma-separated ISO 3166-1 alpha-2 country codes. Only collections supporting all locations are returned. example: US,CA required: false description: >- Comma-separated ISO 3166-1 alpha-2 country codes. Only collections supporting all locations are returned. name: filter[location] in: query - schema: type: number nullable: true minimum: 0 maximum: 99999 description: Budget bucket selector for thumbnails. example: 80 required: false description: Budget bucket selector for thumbnails. name: filter[maxPrice] in: query - schema: type: array items: type: string enum: - gifts - swag - custom description: Comma-separated collection tags (`gifts`, `swag`, `custom`). example: - gifts - swag required: false description: Comma-separated collection tags (`gifts`, `swag`, `custom`). name: filter[tag] in: query style: form explode: false - schema: type: string maxLength: 100 description: Free-text search on collection name (max 100 characters). example: birthday required: false description: Free-text search on collection name (max 100 characters). name: filter[search] in: query - schema: type: array items: type: string enum: - priceRange - description - createdAt - updatedAt - createdVia description: Optional fields to include. example: - priceRange - description required: false description: Optional fields to include. name: fields in: query style: form explode: false - schema: type: string enum: - rank - name - '-name' - createdAt - '-createdAt' default: rank description: Sort field. Prefix with `-` for descending. Defaults to `rank`. example: rank required: false description: Sort field. Prefix with `-` for descending. Defaults to `rank`. name: sort in: query - schema: type: integer minimum: 1 default: 1 description: 1-indexed page number. example: 1 required: false description: 1-indexed page number. name: page[number] in: query - schema: type: integer minimum: 1 maximum: 150 default: 100 description: Number of collections per page (max 150, default 100). example: 100 required: false description: Number of collections per page (max 150, default 100). name: page[size] in: query - schema: type: string description: Account identifier. example: acc123456 required: true description: Account identifier. name: snappy-account-id in: header - schema: type: string description: Optional company identifier. example: cmp123456 required: false description: Optional company identifier. name: snappy-company-id in: header responses: '200': description: Page-number paginated list of collections. content: application/json: schema: $ref: '#/components/schemas/GetCollectionsV3Response' '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[location]" must be valid country code(s)' path: queryStringParameters.filter[location] '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV3' security: - ApiKeyAuthentication: [] components: schemas: GetCollectionsV3Response: type: object properties: data: type: array items: $ref: '#/components/schemas/CollectionV3' description: Collections for the requested page. links: $ref: '#/components/schemas/CollectionPaginationLinksV3' meta: type: object properties: total: type: integer minimum: 0 description: Total number of collections matching the filters. example: 42 required: - total description: Pagination metadata. required: - data - links - meta description: Page-number paginated collection list 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. CollectionV3: type: object properties: id: type: string description: Collection identifier. example: 64a1234567890abcdef12345 name: type: string example: Birthday Gifts tags: type: array items: $ref: '#/components/schemas/CollectionTagV3' description: Collection type tags. media: type: array items: $ref: '#/components/schemas/MediaV3' description: Collection thumbnail images for the selected budget bucket. coverImage: allOf: - $ref: '#/components/schemas/MediaV3' - nullable: true description: B2B cover image. `null` when not set. rank: type: integer description: Display rank (lower = higher priority). example: 10 description: type: string nullable: true description: >- Returned when `fields` includes `description` (list) or always on by-id. priceRange: $ref: '#/components/schemas/CollectionPriceRangeV3' createdAt: type: string format: date-time description: >- Returned when `fields` includes `createdAt` (list) or always on by-id. updatedAt: type: string format: date-time description: >- Returned when `fields` includes `updatedAt` (list) or always on by-id. createdVia: type: string nullable: true description: >- Origin of collection creation. Returned when `fields` includes `createdVia`. example: dashboard required: - id - name - tags - media - coverImage - rank description: >- Collection summary. Optional fields depend on endpoint and `fields` parameter. CollectionPaginationLinksV3: type: object properties: first: type: string nullable: true description: Link to the first page. example: /v3/collections?page[number]=1&page[size]=100&filter[location]=US next: type: string nullable: true description: Link to the next page, or `null` on the final page. example: /v3/collections?page[number]=2&page[size]=100&filter[location]=US 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 collection list responses. CollectionTagV3: type: string enum: - gifts - swag - custom description: Collection type tag. example: gifts 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. CollectionPriceRangeV3: type: object nullable: true properties: min: type: number example: 25 max: type: number example: 200 required: - min - max description: Min/max budget range for the first requested location. 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 ``` ````