---
title: "List product Pins"
method: GET
path: "/pinterest/products"
tags: ["Pinterest"]
---

# List product Pins

`GET /pinterest/products`

## Request

- Base URL: `https://api.omnisocials.com/v1`
- URL: `https://api.omnisocials.com/v1/pinterest/products`
- Auth: HTTP bearer

List the product Pins of the connected Pinterest account. Pass a returned `pin_id` in `pinterest.product_tags` on `POST /posts/create` / `PATCH /posts/{id}` to tag the product on a Pin (max 24 products per Pin).

Pinterest only accepts a product tag when the product Pin is public, belongs to the same Pinterest account, and links to a website that account claimed on Pinterest. Products of other merchants cannot be tagged through the API.

**Sources.** `source=catalog` reads the Pinterest catalog (with `price`, `currency`, `availability`, `item_id`) through a product group; the response carries `product_groups` so you can pick another group with `product_group_id`. It needs catalog access on the Pinterest connection: in the OmniSocials composer open the Pinterest options, select Add products, then Connect catalog (one time per workspace). Without catalog access the response is `error.code = pinterest_catalog_access_required`. `source=pins` reads the account's own Pins and returns the ones Pinterest marks as product Pins; it works on every connection. One `pins` call scans up to 250 Pins, so `products` can be empty while `bookmark` is set: call again with the bookmark. When `source` is left out, `catalog` is used when the connection has catalog access, else `pins`.

Problems that are not a bad request (no Pinterest account, no catalog access, Pinterest did not answer) come back as HTTP 200 with an `error` object instead of `products`.

## Query parameters

- `source` 'catalog' | 'pins'
- `product_group_id` string
- `bookmark` string
- `page_size` integer

## Response `200`

Product Pins, or an `error` object when the list could not be read.

- object
  - `products` PinterestProduct[]
    - `pin_id` string: Use this in `pinterest.product_tags`.
    - `title` string, nullable
    - `description` string, nullable
    - `link` string, nullable: The product page the Pin links to.
    - `image_url` string, nullable: A small image of the product Pin.
    - `price` number, nullable: Catalog source only.
    - `currency` string, nullable: Catalog source only. ISO 4217 code.
    - `availability` string, nullable: Catalog source only, as Pinterest reports it (for example `IN_STOCK`, `OUT_OF_STOCK`, `PREORDER`).
    - `item_id` string, nullable: Catalog source only. The merchant's own product id.
  - `bookmark` string, nullable: Pass as `bookmark` to get the next page. `null` on the last page.
  - `source` 'catalog' | 'pins': The source that was read.
  - `catalog_access` boolean: `true` when the Pinterest connection can read the catalog.
  - `no_catalog` boolean: `true` when the connection has catalog access but the Pinterest account has no catalog yet (Pinterest answers HTTP 409 to the product group request). `products` and `product_groups` are then empty. Products are added at https://www.pinterest.com/business/catalogs/.
  - `product_groups` object[]: Catalog source only. The product groups of the account.
    - `id` string
    - `name` string, nullable
  - `product_group_id` string, nullable: Catalog source only. The group these products come from.
  - `error` object, nullable: Present instead of `products` when the list could not be read.
    - `code` 'pinterest_not_connected' | 'pinterest_catalog_access_required' | 'platform_error': `pinterest_not_connected` = no Pinterest account on the workspace. `pinterest_catalog_access_required` = `source=catalog` was asked but the connection has no catalog access; connect the catalog in the composer or use `source=pins`. `platform_error` = Pinterest did not answer or refused; the message carries Pinterest's text.
    - `message` string

## Other responses

- `400`: Bad request: `source` is not `catalog` or `pins`, or `product_group_id` is not a product group of the connected account.

## Changes

- **2026-10-07** `9ff28ac9aa20`: 1 info
  - added the optional property `no_catalog` to the response with the `200` status
- **2026-10-06** `9d50b97cee7a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/omnisocials/apis/omnisocials-api/changes/pinterest/products/get.md)

---

[API](https://skmtc.dev/omnisocials/apis/omnisocials-api.md) - [All operations](https://skmtc.dev/omnisocials/apis/omnisocials-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omnisocials/apis/omnisocials-api/revisions/46e479c09474?raw)