List and check the product Pins of the connected Pinterest account, to tag products on a Pin with pinterest.product_tags.
List taggable Pinterest product Pins
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
sourceWhere to read product Pins from. Default: catalog when the connection has catalog access, else pins.
product_group_idCatalog source only. A product group id from product_groups. Default: the group named "All Products", else the first group.
bookmarkCursor from the previous response, to get the next page.
page_sizeCatalog source only. Products per page.
List taggable Pinterest product Pins › Responses
Product Pins, or an error object when the list could not be read.
bookmarkPass as bookmark to get the next page. null on the last page.
sourceThe source that was read.
catalog_accesstrue when the Pinterest connection can read the catalog.
Catalog source only. The product groups of the account.
product_group_idCatalog source only. The group these products come from.
errorPresent instead of products when the list could not be read.
Check a Pinterest product Pin
Check whether a Pin can be used in pinterest.product_tags before you create the post. Pass a Pin ID or a Pin link (https://www.pinterest.com/pin/<id>/; pin.it short links do not work). Returns { valid: true, pin_id, title, link, image_url } for a product Pin of the connected account, and { valid: false, reason } for a Pin that is not a product Pin, belongs to another account or does not exist. When the check cannot run (no Pinterest account, Pinterest did not answer, or Pinterest did not say if the Pin is a product Pin) it returns { valid: false, unverified: true }: the publish step is then the final check. The check does not look at the claimed-website rule; Pinterest applies that one at publish.
query Parameters
idPin ID or Pin link of the product Pin.
Check a Pinterest product Pin › Responses
Check result
validpin_idThe Pin ID read from id (null when id is not a Pin ID or link).
titlelinkimage_urlunverifiedThe check could not run; the publish step will check.
reasonWhy the Pin is not valid or could not be checked.