---
title: "Get catalogs items (POST)"
method: POST
path: "/catalogs/items"
tags: ["catalog_items"]
---

# Get catalogs items (POST)

`POST /catalogs/items`

Get the items of the catalog owned by the "operation user_account". <a href="/docs/api-features/shopping-overview/#Update%20items%20in%20batch" target="_blank">See detailed documentation here.</a>
- By default, the "operation user_account" is the token user_account.

Optional: Business Access: Specify an <code>ad_account_id</code> (obtained via <a href='/docs/api/v5/#operation/ad_accounts/list'>List ad accounts</a>) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following <a href="https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts">Business Access</a> roles on the ad_account: Owner, Admin, Catalogs Manager.

Note: Access to the Creative Assets catalog type is restricted to a specific group of users.
If you require access, please reach out to your partner manager.

## Query parameters

- `ad_account_id` string

## Request body

- CatalogsItemsRequest — Request object of catalogs items
  - `country` 'AD' | 'AE' | 'AF' | 'AG' | 'AI' | 'AL' | 'AM' | 'AO' | 'AQ' | 'AR' | 'AS' | 'AT' | 'AU' | 'AW' | 'AX' | 'AZ' | 'BA' | 'BB' | 'BD' | 'BE' | 'BF' | 'BG' | 'BH' | 'BI' | 'BJ' | 'BL' | 'BM' | 'BN' | 'BO' | 'BQ' | 'BR' | 'BS' | 'BT' | 'BV' | 'BW' | 'BY' | 'BZ' | 'CA' | 'CC' | 'CD' | 'CF' | 'CG' | 'CH' | 'CI' | 'CK' | 'CL' | 'CM' | 'CN' | 'CO' | 'CR' | 'CU' | 'CV' | 'CW' | 'CX' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DK' | 'DM' | 'DO' | 'DZ' | 'EC' | 'EE' | 'EG' | 'EH' | 'ER' | 'ES' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FM' | 'FO' | 'FR' | 'GA' | 'GB' | 'GD' | 'GE' | 'GF' | 'GG' | 'GH' | 'GI' | 'GL' | 'GM' | 'GN' | 'GP' | 'GQ' | 'GR' | 'GS' | 'GT' | 'GU' | 'GW' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IE' | 'IL' | 'IM' | 'IN' | 'IO' | 'IQ' | 'IR' | 'IS' | 'IT' | 'JE' | 'JM' | 'JO' | 'JP' | 'KE' | 'KG' | 'KH' | 'KI' | 'KM' | 'KN' | 'KR' | 'KW' | 'KY' | 'KZ' | 'LA' | 'LB' | 'LC' | 'LI' | 'LK' | 'LR' | 'LS' | 'LT' | 'LU' | 'LV' | 'LY' | 'MA' | 'MC' | 'MD' | 'ME' | 'MF' | 'MG' | 'MH' | 'MK' | 'ML' | 'MM' | 'MN' | 'MO' | 'MP' | 'MQ' | 'MR' | 'MS' | 'MT' | 'MU' | 'MV' | 'MW' | 'MX' | 'MY' | 'MZ' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NL' | 'NO' | 'NP' | 'NR' | 'NU' | 'NZ' | 'OM' | 'PA' | 'PE' | 'PF' | 'PG' | 'PH' | 'PK' | 'PL' | 'PM' | 'PN' | 'PR' | 'PS' | 'PT' | 'PW' | 'PY' | 'QA' | 'RE' | 'RO' | 'RS' | 'RU' | 'RW' | 'SA' | 'SB' | 'SC' | 'SD' | 'SE' | 'SG' | 'SH' | 'SI' | 'SJ' | 'SK' | 'SL' | 'SM' | 'SN' | 'SO' | 'SR' | 'SS' | 'ST' | 'SV' | 'SX' | 'SY' | 'SZ' | 'TC' | 'TD' | 'TF' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TL' | 'TM' | 'TN' | 'TO' | 'TR' | 'TT' | 'TV' | 'TW' | 'TZ' | 'UA' | 'UG' | 'UM' | 'US' | 'UY' | 'UZ' | 'VA' | 'VC' | 'VE' | 'VG' | 'VI' | 'VN' | 'VU' | 'WF' | 'WS' | 'YE' | 'YT' | 'ZA' | 'ZM' | 'ZW', required — Country ID from ISO 3166-1 alpha-2.
  - `language` union, required — We recommend using the CatalogsLocale values.
    - 'af-ZA' | 'ar-SA' | 'bg-BG' | 'bn-IN' | 'cs-CZ' | 'da-DK' | 'de' | 'el-GR' | 'en-AU' | 'en-CA' | 'en-GB' | 'en-IN' | 'en-US' | 'es-419' | 'es-AR' | 'es-ES' | 'es-MX' | 'fi-FI' | 'fr' | 'fr-CA' | 'he-IL' | 'hi-IN' | 'hr-HR' | 'hu-HU' | 'id-ID' | 'it' | 'ja' | 'ko-KR' | 'ms-MY' | 'nb-NO' | 'nl' | 'pl-PL' | 'pt-BR' | 'pt-PT' | 'ro-RO' | 'ru-RU' | 'sk-SK' | 'sv-SE' | 'te-IN' | 'th-TH' | 'tl-PH' | 'tr' | 'uk-UA' | 'vi-VN' | 'zh-CN' | 'zh-TW'
    - 'AM' | 'AR' | 'AZ' | 'BG' | 'BN' | 'BS' | 'CA' | 'CS' | 'DA' | 'DV' | 'DZ' | 'DE' | 'EL' | 'EN' | 'ES' | 'ET' | 'FA' | 'FI' | 'FR' | 'HE' | 'HI' | 'HR' | 'HU' | 'HY' | 'ID' | 'IN' | 'IS' | 'IT' | 'IW' | 'JA' | 'KA' | 'KM' | 'KO' | 'LO' | 'LT' | 'LV' | 'MK' | 'MN' | 'MS' | 'MY' | 'NB' | 'NE' | 'NL' | 'NO' | 'PL' | 'PT' | 'RO' | 'RU' | 'SK' | 'SL' | 'SQ' | 'SR' | 'SV' | 'TL' | 'UK' | 'VI' | 'TE' | 'TH' | 'TR' | 'XX' | 'ZH' — Language code, which is among the official ISO 639-1 language list.
  - `filters` union, required
    - object
      - `catalog_type` 'RETAIL', required — Type of the catalog entity.
      - `item_ids` string[], required
      - `catalog_id` string — Catalog id pertaining to the retail item. If not provided, default to oldest retail catalog
    - object
      - `catalog_type` 'HOTEL', required — Type of the catalog entity.
      - `hotel_ids` string[], required
      - `catalog_id` string — Catalog id pertaining to the hotel item. If not provided, default to oldest hotel catalog
    - object
      - `catalog_type` 'CREATIVE_ASSETS', required — Type of the catalog entity.
      - `creative_assets_ids` string[], required
      - `catalog_id` string — Catalog id pertaining to the creative assets item. If not provided, default to oldest creative assets catalog

## Response `200`

Response containing the requested catalogs items

- CatalogsItems — Response object of catalogs items
  - `items` ItemResponse[] — Array with catalogs items
    - union — Object describing an item record
      - union
        - object — Object describing a retail item record
          - `catalog_type` 'RETAIL' | 'HOTEL' | 'CREATIVE_ASSETS', required — Type of the catalog entity.
          - `item_id` string — The catalog retail item id in the merchant namespace
          - `pins` Pin[], nullable — The pins mapped to the item
            - `alt_text` string, nullable
            - `board_id` string — The board to which this Pin belongs.
            - `board_owner` object
              - …
            - `board_section_id` string, nullable — The board section to which this Pin belongs.
            - `created_at` string, date-time
            - `creative_type` 'REGULAR' | 'VIDEO' | 'SHOPPING' | 'CAROUSEL' | 'MAX_VIDEO' | 'SHOP_THE_PIN' | 'COLLECTION' | 'IDEA' | 'SHOWCASE' | 'QUIZ' — Ad creative type enum. **Note:** SHOP_THE_PIN has been deprecated. Please use COLLECTION instead.
            - `description` string, nullable
            - `dominant_color` string, nullable — Dominant pin color. Hex number, e.g. `#6E7874`.
            - `has_been_promoted` boolean — Whether the Pin has been promoted or not.
            - `id` string, required
            - `is_owner` boolean — Whether the "operation user_account" is the Pin owner.
            - `is_standard` boolean — Whether the Pin is standard or not. See documentation on [Changes to Pin creation](/docs/api-features/content-overview/) for more information.
            - `link` string, nullable
            - `media` union — Pin media that can be an image, video, or a mix of both.
              - …
            - `note` string, nullable — Private note for this Pin. [Learn more](https://help.pinterest.com/en/article/add-notes-to-your-pins).
            - `parent_pin_id` string, nullable — The source pin id if this pin was saved from another pin. [Learn more](https://help.pinterest.com/article/save-pins-on-pinterest).
            - `pin_metrics` object, nullable — Pin metrics with associated time intervals if any.
            - `title` string, nullable
          - `attributes` ItemAttributes
            - `additional_image_link` string[], nullable — <p><= 2000 characters</p> <p>The links to additional images for your product. Up to ten additional images can be used to show a product from different angles or to show different stages. Must begin with http:// or https://.</p>
            - `image_link` string[] — <p><= 2000 characters</p> <p>The link to the main product images. Images should be at least 75x75 pixels to avoid errors. Use the additional_image_link field to add more images of your product. The URL of your image_link must be accessible by the Pinterest user-agent, and send the accurate images. Please make sure there are no template or placeholder images at the link. Must start with http:// or https://.</p>
            - `video_link` string, nullable — <p><= 2,000 characters</p> <p>Hosted link to the product video.</p> <p>File types for linked videos must be .mp4, .mov or .m4v.</p> <p>File size cannot exceed 2GB.</p>
            - `ad_link` string, nullable — Allows advertisers to specify a separate URL that can be used to track traffic coming from Pinterest shopping ads. Must send full URL including tracking—do not send tracking parameters only. At this time we do not support impression tracking. Must begin with http:// or https://.
            - `adult` boolean, nullable — Set this attribute to TRUE if you're submitting items that are considered “adult”. These will not be shown on Pinterest.
            - `age_group` string, nullable — The age group to apply a demographic range to the product. Must be one of the following values (upper or lowercased): ‘newborn’ , ‘infant’, ‘toddler’, ‘kids’, or ‘adult’.
            - `availability` string — The availability of the product. Must be one of the following values (upper or lowercased): ‘in stock’, ‘out of stock’ , ‘preorder’.
            - `average_review_rating` number, nullable — Average reviews for the item. Can be a number from 1-5.
            - `brand` string, nullable — The brand of the product.
            - `checkout_enabled` boolean, nullable — This attribute is not supported anymore.
            - `color` string, nullable — The primary color of the product.
            - `condition` string, nullable — The condition of the product. Must be one of the following values (upper or lowercased): ‘new’, ‘used’, or ‘refurbished’.
            - `custom_label_0` string, nullable — <p><= 511 characters for retail and creative asset catalogs, <= 127 characters for hotel catalogs</p> <p>Custom grouping of products.</p>
            - `custom_label_1` string, nullable — <p><= 511 characters for retail and creative asset catalogs, <= 127 characters for hotel catalogs</p> <p>Custom grouping of products.</p>
            - `custom_label_2` string, nullable — <p><= 511 characters for retail and creative asset catalogs, <= 127 characters for hotel catalogs</p> <p>Custom grouping of products.</p>
            - `custom_label_3` string, nullable — <p><= 511 characters for retail and creative asset catalogs, <= 127 characters for hotel catalogs</p> <p>Custom grouping of products.</p>
            - `custom_label_4` string, nullable — <p><= 511 characters for retail and creative asset catalogs, <= 127 characters for hotel catalogs</p> <p>Custom grouping of products.</p>
            - `custom_number_0` integer, nullable — an attribute for any integer information ranging from 0 to 4,294,967,295, which can be used to group items.
            - `custom_number_1` integer, nullable — an attribute for any integer information ranging from 0 to 4,294,967,295, which can be used to group items.
            - `custom_number_2` integer, nullable — an attribute for any integer information ranging from 0 to 4,294,967,295, which can be used to group items.
            - `custom_number_3` integer, nullable — an attribute for any integer information ranging from 0 to 4,294,967,295, which can be used to group items.
            - `custom_number_4` integer, nullable — an attribute for any integer information ranging from 0 to 4,294,967,295, which can be used to group items.
            - `description` string — <p><= 10000 characters</p> <p>The description of the product.</p>
            - `free_shipping_label` boolean, nullable — The item is free to ship.
            - `free_shipping_limit` string, nullable — The minimum order purchase necessary for the customer to get free shipping. Only relevant if free shipping is offered.
            - `gender` string, nullable — The gender associated with the product. Must be one of the following values (upper or lowercased): ‘male’, ‘female’ , or ‘unisex’.
            - `google_product_category` string, nullable — The categorization of the product based on the standardized Google Product Taxonomy. This is a set taxonomy. Both the text values and numeric codes are accepted.
            - `gtin` union — The unique universal product identifier.
              - …
            - `id` string — <p><= 127 characters</p> <p>The user-created unique ID that represents the product. Only Unicode characters are accepted.</p>
            - `item_group_id` string, nullable — <p><= 127 characters</p> <p>The parent ID of the product.</p>
            - `last_updated_time` integer, nullable — The millisecond timestamp when the item was lastly modified by the merchant.
            - `link` string — <p><= 511 characters</p> <p>The landing page for the product.</p>
            - `material` string, nullable — The material used to make the product.
            - `min_ad_price` string, nullable — The minimum advertised price of the product. It supports the following formats, "19.99 USD", "19.99USD" and "19.99". If the currency is not included, we default to US dollars.
            - `mobile_link` string, nullable — The mobile-optimized version of your landing page. Must begin with http:// or https://.
            - `mpn` string, nullable — Manufacturer Part Number are alpha-numeric codes created by the manufacturer of a product to uniquely identify it among all products from the same manufacturer.
            - `number_of_ratings` integer, nullable — The number of ratings for the item.
            - `number_of_reviews` integer, nullable — The number of reviews available for the item.
            - `pattern` string, nullable — The description of the pattern used for the product.
            - `price` string — The price of the product. It supports the following formats, "24.99 USD", "24.99USD" and "24.99". If the currency is not included, we default to US dollars.
            - `product_type` string, nullable — <p><= 1000 characters</p> <p>The categorization of your product based on your custom product taxonomy. Subcategories must be sent separated by “ > “. The > must be wrapped by spaces. We do not recognize any other delimiters such as comma or pipe.</p>
            - `sale_price` string, nullable — The discounted price of the product. The sale_price must be lower than the price. It supports the following formats, "14.99 USD", "14.99USD" and "14.99". If the currency is not included, we default to US dollars.
            - `shipping` string, nullable — Shipping consists of one group of up to four elements, country, region, service (all optional) and price (required). All colons, even for blank values, are required.
            - `shipping_height` string, nullable — The height of the package needed to ship the product. Ensure there is a space between the numeric string and the metric.
            - `shipping_weight` string, nullable — The weight of the product. Ensure there is a space between the numeric string and the metric.
            - `shipping_width` string, nullable — The width of the package needed to ship the product. Ensure there is a space between the numeric string and the metric.
            - `size` string, nullable — The size of the product.
            - `size_system` string, nullable — Indicates the country’s sizing system in which you are submitting your product. Must be one of the following values (upper or lowercased): ‘US’, ‘UK’, ‘EU’, ‘DE’ , ‘FR’, ‘JP’, ‘CN’, ‘IT’, ‘ BR’, ‘MEX’, or ‘AU’.
            - `size_type` string, nullable — Additional description for the size. Must be one of the following values (upper or lowercased): ‘regular’, ‘petite’ , ‘plus’, ‘big_and_tall’, or ‘maternity’.
            - `tax` string, nullable — Tax consists of one group of up to four elements, country, region, rate (all required) and tax_ship (optional). All colons, even for blank values, are required.
            - `title` string — <p><= 500 characters</p> <p>The name of the product.</p>
            - `variant_names` string[], nullable — Options for this variant. People will see these options next to your Pin and can select the one they want. List them in the order you want them displayed.
            - `variant_values` string[], nullable — Option values for this variant. People will see these options next to your Pin and can select the one they want. List them in the order you want them displayed. The order of the variant values must be consistent with the order of the variant names.
            - `promotion_id` string, nullable — A unique identifier referencing the promotion associated with this catalog item.
            - `ad_image_0_link` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 2000 characters</p> <p>Ad image link that supplements main image for shopping campaigns.</p> <p>Image format:</p> <ul> <li>Pixel size at least 75 x 75</li> </ul> <p>Link guidelines:</p> <ul> <li>Include extension in file name</li> <li>Do not include template or placeholder images in link</li> <li>Make URL accessible to Pinterest user-agent</li> <li>Must start with http:// or https://</li> </ul>
            - `ad_image_1_link` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 2000 characters</p> <p>Ad image link that supplements main image for shopping campaigns.</p> <p>Image format:</p> <ul> <li>Pixel size at least 75 x 75</li> </ul> <p>Link guidelines:</p> <ul> <li>Include extension in file name</li> <li>Do not include template or placeholder images in link</li> <li>Make URL accessible to Pinterest user-agent</li> <li>Must start with http:// or https://</li> </ul>
            - `ad_image_2_link` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 2000 characters</p> <p>Ad image link that supplements main image for shopping campaigns.</p> <p>Image format:</p> <ul> <li>Pixel size at least 75 x 75</li> </ul> <p>Link guidelines:</p> <ul> <li>Include extension in file name</li> <li>Do not include template or placeholder images in link</li> <li>Make URL accessible to Pinterest user-agent</li> <li>Must start with http:// or https://</li> </ul>
            - `ad_image_3_link` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 2000 characters</p> <p>Ad image link that supplements main image for shopping campaigns.</p> <p>Image format:</p> <ul> <li>Pixel size at least 75 x 75</li> </ul> <p>Link guidelines:</p> <ul> <li>Include extension in file name</li> <li>Do not include template or placeholder images in link</li> <li>Make URL accessible to Pinterest user-agent</li> <li>Must start with http:// or https://</li> </ul>
            - `ad_image_4_link` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 2000 characters</p> <p>Ad image link that supplements main image for shopping campaigns.</p> <p>Image format:</p> <ul> <li>Pixel size at least 75 x 75</li> </ul> <p>Link guidelines:</p> <ul> <li>Include extension in file name</li> <li>Do not include template or placeholder images in link</li> <li>Make URL accessible to Pinterest user-agent</li> <li>Must start with http:// or https://</li> </ul>
            - `ad_image_5_link` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 2000 characters</p> <p>Ad image link that supplements main image for shopping campaigns.</p> <p>Image format:</p> <ul> <li>Pixel size at least 75 x 75</li> </ul> <p>Link guidelines:</p> <ul> <li>Include extension in file name</li> <li>Do not include template or placeholder images in link</li> <li>Make URL accessible to Pinterest user-agent</li> <li>Must start with http:// or https://</li> </ul>
            - `ad_image_6_link` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 2000 characters</p> <p>Ad image link that supplements main image for shopping campaigns.</p> <p>Image format:</p> <ul> <li>Pixel size at least 75 x 75</li> </ul> <p>Link guidelines:</p> <ul> <li>Include extension in file name</li> <li>Do not include template or placeholder images in link</li> <li>Make URL accessible to Pinterest user-agent</li> <li>Must start with http:// or https://</li> </ul>
            - `ad_image_7_link` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 2000 characters</p> <p>Ad image link that supplements main image for shopping campaigns.</p> <p>Image format:</p> <ul> <li>Pixel size at least 75 x 75</li> </ul> <p>Link guidelines:</p> <ul> <li>Include extension in file name</li> <li>Do not include template or placeholder images in link</li> <li>Make URL accessible to Pinterest user-agent</li> <li>Must start with http:// or https://</li> </ul>
            - `ad_image_8_link` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 2000 characters</p> <p>Ad image link that supplements main image for shopping campaigns.</p> <p>Image format:</p> <ul> <li>Pixel size at least 75 x 75</li> </ul> <p>Link guidelines:</p> <ul> <li>Include extension in file name</li> <li>Do not include template or placeholder images in link</li> <li>Make URL accessible to Pinterest user-agent</li> <li>Must start with http:// or https://</li> </ul>
            - `ad_image_9_link` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 2000 characters</p> <p>Ad image link that supplements main image for shopping campaigns.</p> <p>Image format:</p> <ul> <li>Pixel size at least 75 x 75</li> </ul> <p>Link guidelines:</p> <ul> <li>Include extension in file name</li> <li>Do not include template or placeholder images in link</li> <li>Make URL accessible to Pinterest user-agent</li> <li>Must start with http:// or https://</li> </ul>
            - `ad_image_10_link` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 2000 characters</p> <p>Ad image link that supplements main image for shopping campaigns.</p> <p>Image format:</p> <ul> <li>Pixel size at least 75 x 75</li> </ul> <p>Link guidelines:</p> <ul> <li>Include extension in file name</li> <li>Do not include template or placeholder images in link</li> <li>Make URL accessible to Pinterest user-agent</li> <li>Must start with http:// or https://</li> </ul>
            - `ad_image_11_link` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 2000 characters</p> <p>Ad image link that supplements main image for shopping campaigns.</p> <p>Image format:</p> <ul> <li>Pixel size at least 75 x 75</li> </ul> <p>Link guidelines:</p> <ul> <li>Include extension in file name</li> <li>Do not include template or placeholder images in link</li> <li>Make URL accessible to Pinterest user-agent</li> <li>Must start with http:// or https://</li> </ul>
            - `ad_image_12_link` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 2000 characters</p> <p>Ad image link that supplements main image for shopping campaigns.</p> <p>Image format:</p> <ul> <li>Pixel size at least 75 x 75</li> </ul> <p>Link guidelines:</p> <ul> <li>Include extension in file name</li> <li>Do not include template or placeholder images in link</li> <li>Make URL accessible to Pinterest user-agent</li> <li>Must start with http:// or https://</li> </ul>
            - `ad_image_13_link` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 2000 characters</p> <p>Ad image link that supplements main image for shopping campaigns.</p> <p>Image format:</p> <ul> <li>Pixel size at least 75 x 75</li> </ul> <p>Link guidelines:</p> <ul> <li>Include extension in file name</li> <li>Do not include template or placeholder images in link</li> <li>Make URL accessible to Pinterest user-agent</li> <li>Must start with http:// or https://</li> </ul>
            - `ad_image_14_link` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 2000 characters</p> <p>Ad image link that supplements main image for shopping campaigns.</p> <p>Image format:</p> <ul> <li>Pixel size at least 75 x 75</li> </ul> <p>Link guidelines:</p> <ul> <li>Include extension in file name</li> <li>Do not include template or placeholder images in link</li> <li>Make URL accessible to Pinterest user-agent</li> <li>Must start with http:// or https://</li> </ul>
            - `ad_image_15_link` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 2000 characters</p> <p>Ad image link that supplements main image for shopping campaigns.</p> <p>Image format:</p> <ul> <li>Pixel size at least 75 x 75</li> </ul> <p>Link guidelines:</p> <ul> <li>Include extension in file name</li> <li>Do not include template or placeholder images in link</li> <li>Make URL accessible to Pinterest user-agent</li> <li>Must start with http:// or https://</li> </ul>
            - `ad_image_16_link` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 2000 characters</p> <p>Ad image link that supplements main image for shopping campaigns.</p> <p>Image format:</p> <ul> <li>Pixel size at least 75 x 75</li> </ul> <p>Link guidelines:</p> <ul> <li>Include extension in file name</li> <li>Do not include template or placeholder images in link</li> <li>Make URL accessible to Pinterest user-agent</li> <li>Must start with http:// or https://</li> </ul>
            - `ad_image_17_link` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 2000 characters</p> <p>Ad image link that supplements main image for shopping campaigns.</p> <p>Image format:</p> <ul> <li>Pixel size at least 75 x 75</li> </ul> <p>Link guidelines:</p> <ul> <li>Include extension in file name</li> <li>Do not include template or placeholder images in link</li> <li>Make URL accessible to Pinterest user-agent</li> <li>Must start with http:// or https://</li> </ul>
            - `ad_image_18_link` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 2000 characters</p> <p>Ad image link that supplements main image for shopping campaigns.</p> <p>Image format:</p> <ul> <li>Pixel size at least 75 x 75</li> </ul> <p>Link guidelines:</p> <ul> <li>Include extension in file name</li> <li>Do not include template or placeholder images in link</li> <li>Make URL accessible to Pinterest user-agent</li> <li>Must start with http:// or https://</li> </ul>
            - `ad_image_19_link` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 2000 characters</p> <p>Ad image link that supplements main image for shopping campaigns.</p> <p>Image format:</p> <ul> <li>Pixel size at least 75 x 75</li> </ul> <p>Link guidelines:</p> <ul> <li>Include extension in file name</li> <li>Do not include template or placeholder images in link</li> <li>Make URL accessible to Pinterest user-agent</li> <li>Must start with http:// or https://</li> </ul>
            - `ad_image_0_tag` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 511 characters</p> <p>If you provide an ad_image_x_link, include the image tag with the corresponding ad_image_x_tag attribute.</p>
            - `ad_image_1_tag` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 511 characters</p> <p>If you provide an ad_image_x_link, include the image tag with the corresponding ad_image_x_tag attribute.</p>
            - `ad_image_2_tag` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 511 characters</p> <p>If you provide an ad_image_x_link, include the image tag with the corresponding ad_image_x_tag attribute.</p>
            - `ad_image_3_tag` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 511 characters</p> <p>If you provide an ad_image_x_link, include the image tag with the corresponding ad_image_x_tag attribute.</p>
            - `ad_image_4_tag` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 511 characters</p> <p>If you provide an ad_image_x_link, include the image tag with the corresponding ad_image_x_tag attribute.</p>
            - `ad_image_5_tag` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 511 characters</p> <p>If you provide an ad_image_x_link, include the image tag with the corresponding ad_image_x_tag attribute.</p>
            - `ad_image_6_tag` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 511 characters</p> <p>If you provide an ad_image_x_link, include the image tag with the corresponding ad_image_x_tag attribute.</p>
            - `ad_image_7_tag` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 511 characters</p> <p>If you provide an ad_image_x_link, include the image tag with the corresponding ad_image_x_tag attribute.</p>
            - `ad_image_8_tag` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 511 characters</p> <p>If you provide an ad_image_x_link, include the image tag with the corresponding ad_image_x_tag attribute.</p>
            - `ad_image_9_tag` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 511 characters</p> <p>If you provide an ad_image_x_link, include the image tag with the corresponding ad_image_x_tag attribute.</p>
            - `ad_image_10_tag` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 511 characters</p> <p>If you provide an ad_image_x_link, include the image tag with the corresponding ad_image_x_tag attribute.</p>
            - `ad_image_11_tag` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 511 characters</p> <p>If you provide an ad_image_x_link, include the image tag with the corresponding ad_image_x_tag attribute.</p>
            - `ad_image_12_tag` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 511 characters</p> <p>If you provide an ad_image_x_link, include the image tag with the corresponding ad_image_x_tag attribute.</p>
            - `ad_image_13_tag` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 511 characters</p> <p>If you provide an ad_image_x_link, include the image tag with the corresponding ad_image_x_tag attribute.</p>
            - `ad_image_14_tag` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 511 characters</p> <p>If you provide an ad_image_x_link, include the image tag with the corresponding ad_image_x_tag attribute.</p>
            - `ad_image_15_tag` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 511 characters</p> <p>If you provide an ad_image_x_link, include the image tag with the corresponding ad_image_x_tag attribute.</p>
            - `ad_image_16_tag` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 511 characters</p> <p>If you provide an ad_image_x_link, include the image tag with the corresponding ad_image_x_tag attribute.</p>
            - `ad_image_17_tag` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 511 characters</p> <p>If you provide an ad_image_x_link, include the image tag with the corresponding ad_image_x_tag attribute.</p>
            - `ad_image_18_tag` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 511 characters</p> <p>If you provide an ad_image_x_link, include the image tag with the corresponding ad_image_x_tag attribute.</p>
            - `ad_image_19_tag` string, nullable — <a href="/docs/getting-started/using-beta-and-restricted-features/" target="blank" target="blank">Restricted</a> <p><= 511 characters</p> <p>If you provide an ad_image_x_link, include the image tag with the corresponding ad_image_x_tag attribute.</p>
        - object — Object describing a hotel record
          - `catalog_type` 'RETAIL' | 'HOTEL' | 'CREATIVE_ASSETS', required — Type of the catalog entity.
          - `hotel_id` string — The catalog hotel id in the merchant namespace
          - `pins` Pin[], nullable — The pins mapped to the item
            - `alt_text` string, nullable
            - `board_id` string — The board to which this Pin belongs.
            - `board_owner` object
              - …
            - `board_section_id` string, nullable — The board section to which this Pin belongs.
            - `created_at` string, date-time
            - `creative_type` 'REGULAR' | 'VIDEO' | 'SHOPPING' | 'CAROUSEL' | 'MAX_VIDEO' | 'SHOP_THE_PIN' | 'COLLECTION' | 'IDEA' | 'SHOWCASE' | 'QUIZ' — Ad creative type enum. **Note:** SHOP_THE_PIN has been deprecated. Please use COLLECTION instead.
            - `description` string, nullable
            - `dominant_color` string, nullable — Dominant pin color. Hex number, e.g. `#6E7874`.
            - `has_been_promoted` boolean — Whether the Pin has been promoted or not.
            - `id` string, required
            - `is_owner` boolean — Whether the "operation user_account" is the Pin owner.
            - `is_standard` boolean — Whether the Pin is standard or not. See documentation on [Changes to Pin creation](/docs/api-features/content-overview/) for more information.
            - `link` string, nullable
            - `media` union — Pin media that can be an image, video, or a mix of both.
              - …
            - `note` string, nullable — Private note for this Pin. [Learn more](https://help.pinterest.com/en/article/add-notes-to-your-pins).
            - `parent_pin_id` string, nullable — The source pin id if this pin was saved from another pin. [Learn more](https://help.pinterest.com/article/save-pins-on-pinterest).
            - `pin_metrics` object, nullable — Pin metrics with associated time intervals if any.
            - `title` string, nullable
          - `attributes` CatalogsHotelAttributes
            - `main_image` object — The main hotel image
              - …
            - `additional_image_link` string[], nullable — <p><= 2000 characters</p> <p>The links to additional images for your hotel. Up to ten additional images can be used to show a hotel from different angles. Must begin with http:// or https://.</p>
            - `name` string, nullable — The hotel's name.
            - `link` string, nullable — Link to the product page
            - `description` string, nullable — Brief description of the hotel.
            - `brand` string, nullable — The brand to which this hotel belongs to.
            - `latitude` number — Latitude of the hotel.
            - `longitude` number, nullable — Longitude of the hotel.
            - `neighborhood` string[], nullable — A list of neighborhoods where the hotel is located
            - `address` CatalogsHotelAddress
              - …
            - `custom_label_0` string, nullable — Custom grouping of hotels
            - `custom_label_1` string, nullable — Custom grouping of hotels
            - `custom_label_2` string, nullable — Custom grouping of hotels
            - `custom_label_3` string, nullable — Custom grouping of hotels
            - `custom_label_4` string, nullable — Custom grouping of hotels
            - `category` string, nullable — The type of property. The category can be any type of internal description desired.
            - `base_price` string, nullable — Base price of the hotel room per night followed by the ISO currency code
            - `sale_price` string, nullable — Sale price of a hotel room per night. Used to advertise discounts off the regular price of the hotel.
            - `guest_ratings` CatalogsHotelGuestRatings — If specified, you must provide all properties
              - …
        - object — Object describing a hotel record
          - `catalog_type` 'RETAIL' | 'HOTEL' | 'CREATIVE_ASSETS', required — Type of the catalog entity.
          - `creative_assets_id` string — The catalog creative assets id in the merchant namespace
          - `pins` Pin[], nullable — The pins mapped to the item
            - `alt_text` string, nullable
            - `board_id` string — The board to which this Pin belongs.
            - `board_owner` object
              - …
            - `board_section_id` string, nullable — The board section to which this Pin belongs.
            - `created_at` string, date-time
            - `creative_type` 'REGULAR' | 'VIDEO' | 'SHOPPING' | 'CAROUSEL' | 'MAX_VIDEO' | 'SHOP_THE_PIN' | 'COLLECTION' | 'IDEA' | 'SHOWCASE' | 'QUIZ' — Ad creative type enum. **Note:** SHOP_THE_PIN has been deprecated. Please use COLLECTION instead.
            - `description` string, nullable
            - `dominant_color` string, nullable — Dominant pin color. Hex number, e.g. `#6E7874`.
            - `has_been_promoted` boolean — Whether the Pin has been promoted or not.
            - `id` string, required
            - `is_owner` boolean — Whether the "operation user_account" is the Pin owner.
            - `is_standard` boolean — Whether the Pin is standard or not. See documentation on [Changes to Pin creation](/docs/api-features/content-overview/) for more information.
            - `link` string, nullable
            - `media` union — Pin media that can be an image, video, or a mix of both.
              - …
            - `note` string, nullable — Private note for this Pin. [Learn more](https://help.pinterest.com/en/article/add-notes-to-your-pins).
            - `parent_pin_id` string, nullable — The source pin id if this pin was saved from another pin. [Learn more](https://help.pinterest.com/article/save-pins-on-pinterest).
            - `pin_metrics` object, nullable — Pin metrics with associated time intervals if any.
            - `title` string, nullable
          - `attributes` CatalogsCreativeAssetsAttributes
            - `image_link` string — The creative assets image.
            - `video_link` string — The creative assets video.
            - `title` string — The name of the creative assets.
            - `description` string — Brief description of the creative assets.
            - `link` string — Link to the creative assets page.
            - `ios_deep_link` string, nullable — IOS deep link to the creative assets page.
            - `android_deep_link` string, nullable — Link to the creative assets page.
            - `google_product_category` string, nullable — The categorization of the product based on the standardized Google Product Taxonomy. This is a set taxonomy. Both the text values and numeric codes are accepted.
            - `custom_label_0` string, nullable — Custom grouping of creative assets.
            - `custom_label_1` string, nullable — Custom grouping of creative assets.
            - `custom_label_2` string, nullable — Custom grouping of creative assets.
            - `custom_label_3` string, nullable — Custom grouping of creative assets.
            - `custom_label_4` string, nullable — Custom grouping of creative assets.
            - `visibility` string, nullable — Visibility of the creative assets. Must be one of the following values (upper or lowercase): ‘visible’, ‘hidden’.
      - union
        - object — Object describing a retail item error
          - `catalog_type` 'RETAIL' | 'HOTEL' | 'CREATIVE_ASSETS', required — Type of the catalog entity.
          - `item_id` string — The catalog item id in the merchant namespace
          - `errors` ItemValidationEvent[] — Array with the errors for the item id requested
            - `attribute` string — The attribute that the item validation event references
            - `code` integer — The event code that the item validation event references
            - `message` string — Title message describing the item validation event
        - object — Object describing a hotel item error
          - `catalog_type` 'RETAIL' | 'HOTEL' | 'CREATIVE_ASSETS', required — Type of the catalog entity.
          - `hotel_id` string — The catalog hotel id in the merchant namespace
          - `errors` ItemValidationEvent[] — Array with the errors for the item id requested
            - `attribute` string — The attribute that the item validation event references
            - `code` integer — The event code that the item validation event references
            - `message` string — Title message describing the item validation event
        - object — Object describing a creative assets item error
          - `catalog_type` 'RETAIL' | 'HOTEL' | 'CREATIVE_ASSETS', required — Type of the catalog entity.
          - `creative_assets_id` string — The catalog creative assets id in the merchant namespace
          - `errors` ItemValidationEvent[] — Array with the errors for the item id requested
            - `attribute` string — The attribute that the item validation event references
            - `code` integer — The event code that the item validation event references
            - `message` string — Title message describing the item validation event

## Other responses

- `400` — Invalid request
- `401` — Not authorized to access catalogs items
- `403` — Not authorized to access catalogs items
- `default` — Unexpected error

## Changes

- **2025-08-14** (v5) `7d64d863909a` — 12 breaking, 6 warning, 21 info
  - added `#/components/schemas/PinMediaWithImage, #/components/schemas/PinMediaWithVideo, #/components/schemas/PinMediaWithImages, #/components/schemas/PinMediaWithVideos, #/components/schemas/PinMediaWithImageAndVideo` to the `items/items/anyOf[subschema #1]/oneOf[#/components/schemas/CatalogsCreativeAssetsItemResponse]/pins/items/media/allOf[subschema #1: Pin media -> subschema #1: Pin media response object.]/` response property `oneOf` list for the response status `200`
  - added `#/components/schemas/PinMediaWithImage, #/components/schemas/PinMediaWithVideo, #/components/schemas/PinMediaWithImages, #/components/schemas/PinMediaWithVideos, #/components/schemas/PinMediaWithImageAndVideo` to the `items/items/anyOf[subschema #1]/oneOf[#/components/schemas/CatalogsHotelItemResponse]/pins/items/media/allOf[subschema #1: Pin media -> subschema #1: Pin media response object.]/` response property `oneOf` list for the response status `200`
  - added `#/components/schemas/PinMediaWithImage, #/components/schemas/PinMediaWithVideo, #/components/schemas/PinMediaWithImages, #/components/schemas/PinMediaWithVideos, #/components/schemas/PinMediaWithImageAndVideo` to the `items/items/anyOf[subschema #1]/oneOf[#/components/schemas/CatalogsRetailItemResponse]/pins/items/media/allOf[subschema #1: Pin media -> subschema #1: Pin media response object.]/` response property `oneOf` list for the response status `200`
  - the `items/items/anyOf[subschema #1]/oneOf[#/components/schemas/CatalogsCreativeAssetsItemResponse]/pins/items/board_owner` response's property type changed from `object` to no type for status `200`
  - …35 more
- …earlier changes not shown

[Full history](https://skmtc.dev/pinterest/apis/pinterest-rest-api/changes/catalogs/items/post.md)

---

[API](https://skmtc.dev/pinterest/apis/pinterest-rest-api.md) · [All operations](https://skmtc.dev/pinterest/apis/pinterest-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/pinterest/pinterest-rest-api/revisions/7d64d863909a/schema)