openapi: 3.0.3
info:
  version: 5.13.0
  title: Pinterest Items API
  description: This is the description of your API.
  contact:
    name: Pinterest, Inc.
    url: https://developers.pinterest.com/
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT
  termsOfService: https://developers.pinterest.com/terms/
servers:
- url: https://api.pinterest.com/v5
tags:
- name: Items
paths:
  /catalogs/items:
    get:
      summary: Get catalogs items
      description: 'Get the items of the catalog owned by the "operation user_account". <a href="/docs/shopping/catalog/#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: The catalog type of Creative Assets is only allowed in the <a href=''https://api-sandbox.pinterest.com/v5''>Pinterest API Sandbox</a>.

        If access is required, please contact your partner manager.'
      operationId: items/get
      security:
      - pinterest_oauth2:
        - catalogs:read
      x-ratelimit-category: catalogs_read
      x-sandbox: enabled
      parameters:
      - $ref: '#/components/parameters/query_ad_account_id'
      - $ref: '#/components/parameters/query_catalogs_items_country'
      - $ref: '#/components/parameters/query_catalogs_items_language'
      - $ref: '#/components/parameters/query_catalogs_items'
      - $ref: '#/components/parameters/query_catalogs_items_filters'
      responses:
        '200':
          description: Response containing the requested catalogs items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogsItems'
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                InvalidRequest:
                  value:
                    code: 1
                    message: Parameter 'item_ids' is required.
        '401':
          description: Not authorized to access catalogs items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UnauthorizedAccess:
                  value:
                    code: 2
                    message: Authentication failed.
        '403':
          description: Not authorized to access catalogs items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Items
    post:
      summary: Get catalogs items (POST)
      description: 'Get the items of the catalog owned by the "operation user_account". <a href="/docs/shopping/catalog/#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: The catalog type of Creative Assets is only allowed in the <a href=''https://api-sandbox.pinterest.com/v5''>Pinterest API Sandbox</a>.

        If access is required, please contact your partner manager.'
      operationId: items/post
      security:
      - pinterest_oauth2:
        - catalogs:read
      x-ratelimit-category: catalogs_read
      x-sandbox: enabled
      parameters:
      - $ref: '#/components/parameters/query_ad_account_id'
      requestBody:
        description: Request object used to get catalogs items
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CatalogsItemsRequest'
      responses:
        '200':
          description: Response containing the requested catalogs items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogsItems'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                InvalidRequest:
                  value:
                    code: 1
                    message: 'Invalid request: {''country'': ''US'', ''language'': ''EN'', ''filters'': {''catalog_type'': ''RETAIL'', ''item_ids'': ''test0''}} (''test0'' is not of type array)'
        '401':
          description: Not authorized to access catalogs items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UnauthorizedAccess:
                  value:
                    code: 2
                    message: Authentication failed.
        '403':
          description: Not authorized to access catalogs items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Items
  /catalogs/items/batch:
    post:
      summary: Operate on item batch
      description: 'This endpoint supports multiple operations on a set of one or more catalog items owned by the "operation user_account". <a href="/docs/shopping/catalog/#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: The catalog type of Creative Assets is only allowed in the <a href=''https://api-sandbox.pinterest.com/v5''>Pinterest API Sandbox</a>.

        If access is required, please contact your partner manager.'
      operationId: items_batch/post
      x-ratelimit-category: catalogs_write
      x-sandbox: enabled
      security:
      - pinterest_oauth2:
        - catalogs:read
        - catalogs:write
      parameters:
      - $ref: '#/components/parameters/query_ad_account_id'
      requestBody:
        description: Request object used to create catalogs items in a batch
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/CatalogsVerticalBatchRequest'
              - $ref: '#/components/schemas/CatalogsItemsBatchRequest'
      responses:
        '200':
          description: Response containing the requested catalogs items batch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogsItemsBatch'
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                InvalidRequest:
                  value:
                    code: 1
                    message: 'Invalid request: {''country'': ''US'', ''language'': ''EN'', ''operation'': ''CREATE'', ''items'': [{''item_id'': ''RAY_01_'', ''attributes'': {''image_link'': ''https://www.example.com/'', ''title'': ''My Product''}}]} (''https://www.example.com/'' is not of type array)'
        '401':
          description: Not authenticated to post catalogs items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UnauthenticatedAccess:
                  value:
                    code: 2
                    message: Authentication failed.
        '403':
          description: Not authorized to post catalogs items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Items
  /catalogs/items/batch/{batch_id}:
    get:
      summary: Get catalogs item batch status
      description: 'Get a single catalogs items batch owned by the "operating user_account". <a href="/docs/shopping/catalog/#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.'
      operationId: items_batch/get
      security:
      - pinterest_oauth2:
        - catalogs:read
      x-ratelimit-category: catalogs_read
      x-sandbox: enabled
      parameters:
      - $ref: '#/components/parameters/path_catalogs_items_batch_id'
      - $ref: '#/components/parameters/query_ad_account_id'
      responses:
        '200':
          description: Response containing the requested catalogs items batch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogsItemsBatch'
        '401':
          description: Not authenticated to access catalogs items batch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UnauthenticatedAccess:
                  value:
                    code: 2
                    message: Authentication failed.
        '403':
          description: Not authorized to access catalogs items batch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Catalogs items batch not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                CannotFindBatch:
                  value:
                    code: 4331
                    message: Sorry! We could not find your batch ID.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                MethodNotAllowed:
                  value:
                    status: failure
                    code: 5
                    data: '405 Method Not Allowed: The method is not allowed for the requested URL.'
                    message: Method not allowed
                    endpoint_name: null
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Items
components:
  schemas:
    CatalogsItemsBatchRequest:
      type: object
      title: legacy_retail_only
      description: Request object of catalogs items batch
      oneOf:
      - $ref: '#/components/schemas/CatalogsItemsUpdateBatchRequest'
      - $ref: '#/components/schemas/CatalogsItemsUpsertBatchRequest'
      - $ref: '#/components/schemas/CatalogsItemsCreateBatchRequest'
      - $ref: '#/components/schemas/CatalogsItemsDeleteDiscontinuedBatchRequest'
      - $ref: '#/components/schemas/CatalogsItemsDeleteBatchRequest'
      discriminator:
        propertyName: operation
        mapping:
          UPDATE: '#/components/schemas/CatalogsItemsUpdateBatchRequest'
          UPSERT: '#/components/schemas/CatalogsItemsUpsertBatchRequest'
          CREATE: '#/components/schemas/CatalogsItemsCreateBatchRequest'
          DELETE_DISCONTINUED: '#/components/schemas/CatalogsItemsDeleteDiscontinuedBatchRequest'
          DELETE: '#/components/schemas/CatalogsItemsDeleteBatchRequest'
    CatalogsHotelBatchItem:
      description: Hotel batch item
      type: object
      anyOf:
      - $ref: '#/components/schemas/CatalogsCreateHotelItem'
      - $ref: '#/components/schemas/CatalogsUpsertHotelItem'
      - $ref: '#/components/schemas/CatalogsUpdateHotelItem'
      - $ref: '#/components/schemas/CatalogsDeleteHotelItem'
      discriminator:
        propertyName: operation
        mapping:
          CREATE: '#/components/schemas/CatalogsCreateHotelItem'
          UPSERT: '#/components/schemas/CatalogsUpsertHotelItem'
          UPDATE: '#/components/schemas/CatalogsUpdateHotelItem'
          DELETE: '#/components/schemas/CatalogsDeleteHotelItem'
    CatalogsRetailBatchRequest:
      type: object
      description: A request object that can have multiple operations on a single retail batch
      additionalProperties: false
      properties:
        catalog_type:
          $ref: '#/components/schemas/CatalogsType'
        country:
          $ref: '#/components/schemas/Country'
        language:
          $ref: '#/components/schemas/Language'
        items:
          minItems: 1
          maxItems: 1000
          type: array
          description: Array with catalogs item operations
          items:
            anyOf:
            - $ref: '#/components/schemas/CatalogsCreateRetailItem'
            - $ref: '#/components/schemas/CatalogsUpdateRetailItem'
            - $ref: '#/components/schemas/CatalogsUpsertRetailItem'
            - $ref: '#/components/schemas/CatalogsDeleteRetailItem'
            discriminator:
              propertyName: operation
              mapping:
                CREATE: '#/components/schemas/CatalogsCreateRetailItem'
                UPDATE: '#/components/schemas/CatalogsUpdateRetailItem'
                UPSERT: '#/components/schemas/CatalogsUpsertRetailItem'
                DELETE: '#/components/schemas/CatalogsDeleteRetailItem'
      required:
      - catalog_type
      - country
      - language
      - items
    CatalogsRetailItemsPostFilter:
      type: object
      properties:
        catalog_type:
          type: string
          enum:
          - RETAIL
        item_ids:
          type: array
          minItems: 1
          maxItems: 1000
          items:
            type: string
        catalog_id:
          type: string
          pattern: ^\d+$
          description: Catalog id pertaining to the retail item. If not provided, default to oldest retail catalog
      required:
      - catalog_type
      - item_ids
    ItemValidationEvent:
      type: object
      description: Object describing an item validation event
      properties:
        attribute:
          description: The attribute that the item validation event references
          example: title
          type: string
        code:
          description: The event code that the item validation event references
          example: 106
          type: integer
        message:
          description: Title message describing the item validation event
          example: Title is missing from product metadata.
          type: string
    CatalogsCreativeAssetsItemsPostFilter:
      type: object
      properties:
        catalog_type:
          type: string
          enum:
          - CREATIVE_ASSETS
        creative_assets_ids:
          type: array
          minItems: 1
          maxItems: 1000
          items:
            type: string
        catalog_id:
          type: string
          pattern: ^\d+$
          description: Catalog id pertaining to the creative assets item. If not provided, default to oldest creative assets catalog
      required:
      - catalog_type
      - creative_assets_ids
    HotelProcessingRecord:
      type: object
      description: Object describing an item processing record
      properties:
        hotel_id:
          description: The catalog hotel id in the merchant namespace
          example: DS0294-M
          type: string
        errors:
          description: 'Array with the validation errors for the item processing record.

            A non empty errors list causes the item processing to fail.'
          items:
            $ref: '#/components/schemas/ItemValidationEvent'
          type: array
        warnings:
          description: Array with the validation warnings for the item processing record
          items:
            $ref: '#/components/schemas/ItemValidationEvent'
          type: array
        status:
          $ref: '#/components/schemas/ItemProcessingStatus'
    CatalogsItemsPostFilters:
      type: object
      properties:
        catalog_type:
          $ref: '#/components/schemas/CatalogsType'
      required:
      - catalog_type
      oneOf:
      - $ref: '#/components/schemas/CatalogsRetailItemsPostFilter'
      - $ref: '#/components/schemas/CatalogsHotelItemsPostFilter'
      - $ref: '#/components/schemas/CatalogsCreativeAssetsItemsPostFilter'
      discriminator:
        propertyName: catalog_type
        mapping:
          RETAIL: '#/components/schemas/CatalogsRetailItemsPostFilter'
          HOTEL: '#/components/schemas/CatalogsHotelItemsPostFilter'
          CREATIVE_ASSETS: '#/components/schemas/CatalogsCreativeAssetsItemsPostFilter'
    CatalogsHotelItemsBatch:
      type: object
      description: Object describing the catalogs hotel items batch
      properties:
        batch_id:
          description: Id of the catalogs items batch
          example: 595953100599279259-66753b9bb65c46c49bd8503b27fecf9e
          type: string
        created_time:
          description: 'Time of the batch creation: YYYY-MM-DD''T''hh:mm:ssTZD'
          example: '2020-01-01T20:10:40-00:00'
          type: string
          format: date-time
          readOnly: true
        completed_time:
          description: 'Time of the batch completion: YYYY-MM-DD''T''hh:mm:ssTZD'
          example: '2022-03-10T15:37:10-00:00'
          type: string
          format: date-time
          readOnly: true
          nullable: true
        status:
          $ref: '#/components/schemas/BatchOperationStatus'
        catalog_type:
          $ref: '#/components/schemas/CatalogsType'
        items:
          description: Array with the catalogs items processing records part of the catalogs items batch
          items:
            $ref: '#/components/schemas/HotelProcessingRecord'
          type: array
      required:
      - catalog_type
    ItemCreateBatchRecord:
      type: object
      description: Object describing an item batch record to create items
      properties:
        item_id:
          description: The catalog item id in the merchant namespace
          example: DS0294-M
          type: string
        attributes:
          $ref: '#/components/schemas/ItemAttributesRequest'
    CatalogsItemsRequest:
      type: object
      additionalProperties: false
      description: Request object of catalogs items
      properties:
        country:
          $ref: '#/components/schemas/Country'
        language:
          $ref: '#/components/schemas/Language'
        filters:
          $ref: '#/components/schemas/CatalogsItemsPostFilters'
      required:
      - country
      - language
      - filters
    ItemUpsertBatchRecord:
      type: object
      description: Object describing an item batch record to upsert items
      properties:
        item_id:
          description: The catalog item id in the merchant namespace
          example: DS0294-M
          type: string
        attributes:
          $ref: '#/components/schemas/ItemAttributesRequest'
    CatalogsItemsFilters:
      type: object
      properties:
        catalog_type:
          $ref: '#/components/schemas/CatalogsType'
      required:
      - catalog_type
      oneOf:
      - $ref: '#/components/schemas/CatalogsRetailItemsFilter'
      - $ref: '#/components/schemas/CatalogsHotelItemsFilter'
      - $ref: '#/components/schemas/CatalogsCreativeAssetsItemsFilter'
      discriminator:
        propertyName: catalog_type
        mapping:
          RETAIL: '#/components/schemas/CatalogsRetailItemsFilter'
          HOTEL: '#/components/schemas/CatalogsHotelItemsFilter'
          CREATIVE_ASSETS: '#/components/schemas/CatalogsCreativeAssetsItemsFilter'
    CatalogsItemsUpsertBatchRequest:
      description: Request object to upsert catalogs items
      type: object
      properties:
        country:
          $ref: '#/components/schemas/Country'
        language:
          $ref: '#/components/schemas/Language'
        operation:
          $ref: '#/components/schemas/BatchOperation'
        items:
          type: array
          description: Array with catalogs items
          items:
            $ref: '#/components/schemas/ItemUpsertBatchRecord'
          minItems: 1
          maxItems: 1000
      required:
      - country
      - language
      - operation
      - items
    CatalogsCreativeAssetsItemsFilter:
      type: object
      properties:
        catalog_type:
          type: string
          enum:
          - CREATIVE_ASSETS
        creative_assets_ids:
          type: array
          minItems: 1
          maxItems: 100
          items:
            type: string
        catalog_id:
          type: string
          pattern: ^\d+$
          description: Catalog id pertaining to the creative assets item. If not provided, default to oldest creative assets catalog
      required:
      - catalog_type
      - creative_assets_ids
    ItemDeleteDiscontinuedBatchRecord:
      type: object
      description: Object describing an item batch record to discontinue items
      properties:
        item_id:
          description: The catalog item id in the merchant namespace
          example: DS0294-M
          type: string
    ItemAttributes:
      type: object
      allOf:
      - type: object
        properties:
          additional_image_link:
            description: '<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>'
            example:
            - https://scene.example.com/image/image_v2.jpg
            - https://scene.example.com/image/image_v3.jpg
            type: array
            nullable: true
            items:
              type: string
          image_link:
            description: '<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>'
            example:
            - https://scene.example.com/image/image.jpg
            type: array
            minItems: 1
            items:
              type: string
      - $ref: '#/components/schemas/UpdatableItemAttributes'
    PinMediaSourceImagesBase64:
      title: Images Base64
      description: Multiple Base64-encoded images media source
      additionalProperties: false
      properties:
        source_type:
          type: string
          enum:
          - multiple_image_base64
        items:
          items:
            additionalProperties: false
            properties:
              title:
                type: string
              description:
                type: string
              link:
                type: string
                description: Destination link for the image.
              content_type:
                type: string
                enum:
                - image/jpeg
                - image/png
              data:
                type: string
                description: Image to upload as base64 string.
                pattern: '[a-zA-Z0-9+\/=]+'
            required:
            - data
            - content_type
            type: object
          minItems: 2
          maxItems: 5
          description: Array with image objects.
          type: array
        index:
          type: integer
          minimum: 0
      required:
      - items
      type: object
    ItemResponse:
      type: object
      description: Object describing an item record
      anyOf:
      - type: object
        properties:
          catalog_type:
            $ref: '#/components/schemas/CatalogsType'
        required:
        - catalog_type
        oneOf:
        - $ref: '#/components/schemas/CatalogsRetailItemResponse'
        - $ref: '#/components/schemas/CatalogsHotelItemResponse'
        - $ref: '#/components/schemas/CatalogsCreativeAssetsItemResponse'
        discriminator:
          propertyName: catalog_type
          mapping:
            RETAIL: '#/components/schemas/CatalogsRetailItemResponse'
            HOTEL: '#/components/schemas/CatalogsHotelItemResponse'
            CREATIVE_ASSETS: '#/components/schemas/CatalogsCreativeAssetsItemResponse'
      - type: object
        properties:
          catalog_type:
            $ref: '#/components/schemas/CatalogsType'
        required:
        - catalog_type
        oneOf:
        - $ref: '#/components/schemas/CatalogsRetailItemErrorResponse'
        - $ref: '#/components/schemas/CatalogsHotelItemErrorResponse'
        - $ref: '#/components/schemas/CatalogsCreativeAssetsItemErrorResponse'
        discriminator:
          propertyName: catalog_type
          mapping:
            RETAIL: '#/components/schemas/CatalogsRetailItemErrorResponse'
            HOTEL: '#/components/schemas/CatalogsHotelItemErrorResponse'
            CREATIVE_ASSETS: '#/components/schemas/CatalogsCreativeAssetsItemErrorResponse'
    CatalogsUpdateRetailItem:
      type: object
      description: An item to be updated
      properties:
        item_id:
          description: The catalog item id in the merchant namespace
          example: DS0294-M
          type: string
        operation:
          type: string
          enum:
          - CREATE
          - UPDATE
          - UPSERT
          - DELETE
        attributes:
          $ref: '#/components/schemas/UpdatableItemAttributes'
        update_mask:
          description: The list of product attributes to be updated. Attributes specified in the update mask without a value specified in the body will be deleted from the product item.
          example:
          - ad_link
          - adult
          - age_group
          - availability
          - average_review_rating
          - brand
          - checkout_enabled
          - color
          - condition
          - custom_label_0
          - custom_label_1
          - custom_label_2
          - custom_label_3
          - custom_label_4
          - description
          - free_shipping_label
          - free_shipping_limit
          - gender
          - google_product_category
          - gtin
          - item_group_id
          - last_updated_time
          - link
          - material
          - min_ad_price
          - mpn
          - number_of_ratings
          - number_of_reviews
          - pattern
          - price
          - product_type
          - sale_price
          - shipping
          - shipping_height
          - shipping_weight
          - shipping_width
          - size
          - size_system
          - size_type
          - tax
          - title
          - variant_names
          - variant_values
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/UpdateMaskFieldType'
      required:
      - item_id
      - operation
      - attributes
    CatalogsRetailItemResponse:
      type: object
      description: Object describing a retail item record
      properties:
        catalog_type:
          $ref: '#/components/schemas/CatalogsType'
        item_id:
          description: The catalog retail item id in the merchant namespace
          example: DS0294-M
          type: string
        pins:
          description: The pins mapped to the item
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/Pin'
          maxItems: 11
        attributes:
          $ref: '#/components/schemas/ItemAttributes'
      required:
      - catalog_type
    CatalogsUpdateHotelItem:
      type: object
      description: Object describing an hotel item batch record
      properties:
        hotel_id:
          description: The catalog hotel item id in the merchant namespace
          example: DS0294-M
          type: string
        operation:
          type: string
          enum:
          - UPDATE
        attributes:
          $ref: '#/components/schemas/CatalogsUpdatableHotelAttributes'
      required:
      - hotel_id
      - operation
      - attributes
    CatalogsHotelItemErrorResponse:
      type: object
      description: Object describing a hotel item error
      properties:
        catalog_type:
          $ref: '#/components/schemas/CatalogsType'
        hotel_id:
          description: The catalog hotel id in the merchant namespace
          example: DS0294-M
          type: string
        errors:
          description: Array with the errors for the item id requested
          items:
            $ref: '#/components/schemas/ItemValidationEvent'
          type: array
      required:
      - catalog_type
    CatalogsCreativeAssetsItemResponse:
      type: object
      description: Object describing a hotel record
      properties:
        catalog_type:
          $ref: '#/components/schemas/CatalogsType'
        creative_assets_id:
          description: The catalog creative assets id in the merchant namespace
          example: DS0294-M
          type: string
        pins:
          description: The pins mapped to the item
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/Pin'
          maxItems: 11
        attributes:
          $ref: '#/components/schemas/CatalogsCreativeAssetsAttributes'
      required:
      - catalog_type
    PinMediaSourceImagesURL:
      title: Images urls
      description: Multiple images urls-based media source
      additionalProperties: false
      properties:
        source_type:
          type: string
          enum:
          - multiple_image_urls
        items:
          items:
            additionalProperties: false
            properties:
              title:
                type: string
              description:
                type: string
              link:
                type: string
                description: Destination link for the image.
              url:
                description: URL of image to upload.
                type: string
            required:
            - url
            type: object
          minItems: 2
          maxItems: 5
          description: Array with image objects.
          type: array
        index:
          type: integer
          minimum: 0
      required:
      - items
      type: object
    ItemProcessingRecord:
      type: object
      description: Object describing an item processing record
      properties:
        item_id:
          description: The catalog item id in the merchant namespace
          example: DS0294-M
          type: string
        errors:
          description: 'Array with the validation errors for the item processing record.

            A non empty errors list causes the item processing to fail.'
          items:
            $ref: '#/components/schemas/ItemValidationEvent'
          type: array
        warnings:
          description: Array with the validation warnings for the item processing record
          items:
            $ref: '#/components/schemas/ItemValidationEvent'
          type: array
        status:
          $ref: '#/components/schemas/ItemProcessingStatus'
    PinMediaSource:
      title: Pin media source
      description: Pin media source.
      oneOf:
      - $ref: '#/components/schemas/PinMediaSourceImageBase64'
      - $ref: '#/components/schemas/PinMediaSourceImageURL'
      - $ref: '#/components/schemas/PinMediaSourceVideoID'
      - $ref: '#/components/schemas/PinMediaSourceImagesBase64'
      - $ref: '#/components/schemas/PinMediaSourceImagesURL'
      - $ref: '#/components/schemas/PinMediaSourcePinURL'
      discriminator:
        propertyName: source_type
        mapping:
          multiple_image_base64: '#/components/schemas/PinMediaSourceImagesBase64'
          image_base64: '#/components/schemas/PinMediaSourceImageBase64'
          multiple_image_urls: '#/components/schemas/PinMediaSourceImagesURL'
          image_url: '#/components/schemas/PinMediaSourceImageURL'
          video_id: '#/components/schemas/PinMediaSourceVideoID'
          pin_url: '#/components/schemas/PinMediaSourcePinURL'
    CatalogsItems:
      type: object
      description: Response object of catalogs items
      properties:
        items:
          type: array
          description: Array with catalogs items
          items:
            $ref: '#/components/schemas/ItemResponse'
    UpdatableItemAttributes:
      type: object
      properties:
        ad_link:
          description: Allows advertisers to specify a separate URL that can be used to track traffic coming from Pinterest shopping ads. Must send full URL including trackingdo not send tracking parameters only. At this time we do not support impression tracking. Must begin with http:// or https://.
          example: https://www.example.com/cat/denim-shirt/item012?utm_source=Pinterest
          type: string
          nullable: true
        adult:
          description: Set this attribute to TRUE if you're submitting items that are considered adult. These will not be shown on Pinterest.
          example: true
          type: boolean
          nullable: true
        age_group:
          description: '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.'
          example: newborn
          type: string
          nullable: true
        availability:
          description: 'The availability of the product. Must be one of the following values (upper or lowercased): in stock, out of stock , preorder.'
          example: in stock
          type: string
        average_review_rating:
          description: Average reviews for the item. Can be a number from 1-5.
          example: 5
          type: number
          nullable: true
        brand:
          description: The brand of the product.
          example: Josies Denim
          type: string
          nullable: true
        checkout_enabled:
          description: This attribute is not supported anymore.
          example: false
          type: boolean
          nullable: true
          deprecated: true
        color:
          description: The primary color of the product.
          example: blue
          type: string
          nullable: true
        condition:
          description: 'The condition of the product. Must be one of the following values (upper or lowercased): new, used, or refurbished.'
          example: new
          type: string
          nullable: true
        custom_label_0:
          description: '<p><= 1000 characters</p>

            <p>Custom grouping of products.</p>'
          example: Best sellers
          type: string
          nullable: true
        custom_label_1:
          description: '<p><= 1000 characters</p>

            <p>Custom grouping of products.</p>'
          example: Summer promotion
          type: string
          nullable: true
        custom_label_2:
          description: '<p><= 1000 characters</p>

            <p>Custom grouping of products.</p>'
          example: Winter sales
          type: string
          nullable: true
        custom_label_3:
          description: '<p><= 1000 characters</p>

            <p>Custom grouping of products.</p>'
          example: Woman dress
          type: string
          nullable: true
        custom_label_4:
          description: '<p><= 1000 characters</p>

            <p>Custom grouping of products.</p>'
          example: Man hat
          type: string
          nullable: true
        description:
          description: '<p><= 10000 characters</p>

            <p>The description of the product.</p>'
          example: Casual fit denim shirt made with the finest quality Japanese denim.
          type: string
        free_shipping_label:
          description: The item is free to ship.
          example: true
          type: boolean
          nullable: true
        free_shipping_limit:
          description: The minimum order purchase necessary for the customer to get free shipping. Only relevant if free shipping is offered.
          example: 35 USD
          type: string
          nullable: true
        gender:
          description: 'The gender associated with the product. Must be one of the following values (upper or lowercased): male, female , or unisex.'
          example: unisex
          type: string
          nullable: true
        google_product_category:
          description: 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.
          example: Apparel & Accessories > Clothing > Shirts & Tops
          type: string
          nullable: true
        gtin:
          description: The unique universal product identifier.
          example: 3234567890126
          type: integer
          nullable: true
        id:
          description: '<p><= 127 characters</p>

            <p>The user-created unique ID that represents the product. Only

            Unicode characters are accepted.</p>'
          example: DS0294-L
          type: string
          deprecated: true
        item_group_id:
          description: '<p><= 127 characters</p>

            <p>The parent ID of the product.</p>'
          example: DS0294
          type: string
          nullable: true
        last_updated_time:
          description: The millisecond timestamp when the item was lastly modified by the merchant.
          example: 1641483432072
          type: integer
          format: int64
          nullable: true
        link:
          description: '<p><= 511 characters</p>

            <p>The landing page for the product.</p>'
          example: https://www.example.com/cat/womens-clothing/denim-shirt-0294
          type: string
        material:
          description: The material used to make the product.
          example: cotton
          type: string
          nullable: true
        min_ad_price:
          description: 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.
          example: 19.99 USD
          type: string
          nullable: true
        mobile_link:
          description: The mobile-optimized version of your landing page. Must begin with http:// or https://.
          example: https://m.example.com/cat/womens-clothing/denim-shirt-0294
          type: string
          nullable: true
        mpn:
          description: 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.
          example: PI12345NTEREST
          type: string
          nullable: true
        number_of_ratings:
          description: The number of ratings for the item.
          example: 10
          type: integer
          nullable: true
        number_of_reviews:
          description: The number of reviews available for the item.
          example: 10
          type: integer
          nullable: true
        pattern:
          description: The description of the pattern used for the product.
          example: plaid
          type: string
          nullable: true
        price:
          description: 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.
          example: 24.99 USD
          type: string
        product_type:
          description: '<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>'
          example: Clothing > Womens > Shirts > Denim
          type: string
          nullable: true
        sale_price:
          description: 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.
          example: 14.99 USD
          type: string
          nullable: true
        shipping:
          description: 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.
          example: US:CA:Ground:0 USD
          type: string
          nullable: true
        shipping_height:
          description: The height of the package needed to ship the product. Ensure there is a space between the numeric string and the metric.
          example: 12 in
          type: string
          nullable: true
        shipping_weight:
          description: The weight of the product. Ensure there is a space between the numeric string and the metric.
          example: 3 kg
          type: string
          nullable: true
        shipping_width:
          description: The width of the package needed to ship the product. Ensure there is a space between the numeric string and the metric.
          example: 16 in
          type: string
          nullable: true
        size:
          description: The size of the product.
          example: M
          type: string
          nullable: true
        size_system:
          description: 'Indicates the countrys 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.'
          example: US
          type: string
          nullable: true
        size_type:
          description: 'Additional description for the size. Must be one of the following values (upper or lowercased): regular, petite , plus, big_and_tall, or maternity.'
          example: regular
          type: string
          nullable: true
        tax:
          description: 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.
          example: US:1025433:6.00:y
          type: string
          nullable: true
        title:
          description: '<p><= 500 characters</p>

            <p>The name of the product.</p>'
          example: Womens denim shirt, large
          type: string
        variant_names:
          description: 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.
          example:
          - Color
          - Size
          type: array
          nullable: true
          items:
            type: string
        variant_values:
          description: 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.
          example:
          - Red
          - Small
          type: array
          nullable: true
          items:
            type: string
    ItemUpdateBatchRecord:
      type: object
      description: Object describing an item batch record to update items
      properties:
        item_id:
          description: The catalog item id in the merchant namespace
          example: DS0294-M
          type: string
        attributes:
          $ref: '#/components/schemas/UpdatableItemAttributes'
        update_mask:
          description: The list of product attributes to be updated. Attributes specified in the update mask without a value specified in the body will be deleted from the product item.
          example:
          - ad_link
          - adult
          - age_group
          - availability
          - average_review_rating
          - brand
          - checkout_enabled
          - color
          - condition
          - custom_label_0
          - custom_label_1
          - custom_label_2
          - custom_label_3
          - custom_label_4
          - description
          - free_shipping_label
          - free_shipping_limit
          - gender
          - google_product_category
          - gtin
          - item_group_id
          - last_updated_time
          - link
          - material
          - min_ad_price
          - mpn
          - number_of_ratings
          - number_of_reviews
          - pattern
          - price
          - product_type
          - sale_price
          - shipping
          - shipping_height
          - shipping_weight
          - shipping_width
          - size
          - size_system
          - size_type
          - tax
          - title
          - variant_names
          - variant_values
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/UpdateMaskFieldType'
    BatchOperation:
      description: The operation performed by the batch. The DELETE_DISCONTINUED operation only updates availablity to "Out of Stock".
      example: UPDATE
      type: string
      enum:
      - UPDATE
      - UPSERT
      - CREATE
      - DELETE_DISCONTINUED
      - DELETE
    CatalogsHotelItemResponse:
      type: object
      description: Object describing a hotel record
      properties:
        catalog_type:
          $ref: '#/components/schemas/CatalogsType'
        hotel_id:
          description: The catalog hotel id in the merchant namespace
          example: DS0294-M
          type: string
        pins:
          description: The pins mapped to the item
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/Pin'
          maxItems: 11
        attributes:
          $ref: '#/components/schemas/CatalogsHotelAttributes'
      required:
      - catalog_type
    CatalogsItemsCreateBatchRequest:
      description: Request object to create catalogs items
      type: object
      additionalProperties: false
      properties:
        country:
          $ref: '#/components/schemas/Country'
        language:
          $ref: '#/components/schemas/Language'
        operation:
          $ref: '#/components/schemas/BatchOperation'
        items:
          type: array
          description: Array with catalogs items
          items:
            $ref: '#/components/schemas/ItemCreateBatchRecord'
          minItems: 1
          maxItems: 1000
      required:
      - country
      - language
      - operation
      - items
    CatalogsUpsertHotelItem:
      type: object
      description: A hotel item to be upserted.
      properties:
        hotel_id:
          description: The catalog hotel id in the merchant namespace
          example: DS0294-M
          type: string
        operation:
          type: string
          enum:
          - UPSERT
        attributes:
          $ref: '#/components/schemas/CatalogsHotelAttributes'
      required:
      - hotel_id
      - operation
      - attributes
    CatalogsCreativeAssetsItemsBatch:
      type: object
      description: Object describing the catalogs creative assets items batch
      properties:
        batch_id:
          description: Id of the catalogs items batch
          example: 595953100599279259-66753b9bb65c46c49bd8503b27fecf9e
          type: string
        created_time:
          description: 'Time of the batch creation: YYYY-MM-DD''T''hh:mm:ssTZD'
          example: '2020-01-01T20:10:40-00:00'
          type: string
          format: date-time
          readOnly: true
        completed_time:
          description: 'Time of the batch completion: YYYY-MM-DD''T''hh:mm:ssTZD'
          example: '2022-03-10T15:37:10-00:00'
          type: string
          format: date-time
          readOnly: true
          nullable: true
        status:
          $ref: '#/components/schemas/BatchOperationStatus'
        catalog_type:
          $ref: '#/components/schemas/CatalogsType'
        items:
          description: Array with the catalogs items processing records part of the catalogs items batch
          items:
            $ref: '#/components/schemas/CreativeAssetsProcessingRecord'
          type: array
      required:
      - catalog_type
    Language:
      type: string
      description: Language code, which is among the offical ISO 639-1 language list.
      example: EN
      enum:
      - 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
    CatalogsDeleteRetailItem:
      type: object
      description: An item to be deleted
      properties:
        item_id:
          description: The catalog item id in the merchant namespace
          example: DS0294-M
          type: string
        operation:
          type: string
          enum:
          - CREATE
          - UPDATE
          - UPSERT
          - DELETE
      required:
      - item_id
      - operation
    CatalogsCreativeAssetsBatchRequest:
      description: Request object to update catalogs creative assets items
      type: object
      additionalProperties: false
      properties:
        catalog_type:
          $ref: '#/components/schemas/CatalogsType'
        country:
          $ref: '#/components/schemas/Country'
        language:
          $ref: '#/components/schemas/Language'
        items:
          minItems: 1
          maxItems: 1000
          type: array
          description: Array with creative assets item operations
          items:
            $ref: '#/components/schemas/CatalogsCreativeAssetsBatchItem'
        catalog_id:
          description: Catalog id pertaining to the creative assets item. If not provided, default to oldest creative assets catalog
          example: '2680059592705'
          type: string
          pattern: ^\d+$
      required:
      - catalog_type
      - country
      - language
      - items
    CatalogsCreativeAssetsAttributes:
      type: object
      allOf:
      - type: object
        properties:
          image_link:
            type: string
            description: The creative assets image.
            example: https://scene.example.com/image/image_v2.jpg
          video_link:
            type: string
            description: The creative assets video.
            example: https://scene.example.com/image/image_v2.mp4
      - $ref: '#/components/schemas/CatalogsUpdatableCreativeAssetsAttributes'
    CatalogsRetailItemsFilter:
      type: object
      properties:
        catalog_type:
          type: string
          enum:
          - RETAIL
        item_ids:
          type: array
          minItems: 1
          maxItems: 100
          items:
            type: string
        catalog_id:
          type: string
          pattern: ^\d+$
          description: Catalog id pertaining to the retail item. If not provided, default to oldest retail catalog
      required:
      - catalog_type
      - item_ids
    CatalogsCreateHotelItem:
      type: object
      description: A hotel item to be created.
      properties:
        hotel_id:
          description: The catalog hotel id in the merchant namespace
          example: DS0294-M
          type: string
        operation:
          type: string
          enum:
          - CREATE
        attributes:
          $ref: '#/components/schemas/CatalogsHotelAttributes'
      required:
      - hotel_id
      - operation
      - attributes
    Error:
      title: Error
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
      required:
      - code
      - message
    CatalogsHotelItemsFilter:
      type: object
      properties:
        catalog_type:
          type: string
          enum:
          - HOTEL
        hotel_ids:
          type: array
          minItems: 1
          maxItems: 100
          items:
            type: string
        catalog_id:
          type: string
          pattern: ^\d+$
          description: Catalog id pertaining to the hotel item. If not provided, default to oldest hotel catalog
      required:
      - catalog_type
      - hotel_ids
    CatalogsRetailItemsBatch:
      type: object
      description: Object describing the catalogs retail items batch
      properties:
        batch_id:
          description: Id of the catalogs items batch
          example: 595953100599279259-66753b9bb65c46c49bd8503b27fecf9e
          type: string
        created_time:
          description: 'Time of the batch creation: YYYY-MM-DD''T''hh:mm:ssTZD'
          example: '2020-01-01T20:10:40-00:00'
          type: string
          format: date-time
          readOnly: true
        completed_time:
          description: 'Time of the batch completion: YYYY-MM-DD''T''hh:mm:ssTZD'
          example: '2022-03-10T15:37:10-00:00'
          type: string
          format: date-time
          readOnly: true
          nullable: true
        status:
          $ref: '#/components/schemas/BatchOperationStatus'
        catalog_type:
          $ref: '#/components/schemas/CatalogsType'
        items:
          description: Array with the catalogs items processing records part of the catalogs items batch
          items:
            $ref: '#/components/schemas/ItemProcessingRecord'
          type: array
      required:
      - catalog_type
    CatalogsUpsertCreativeAssetsItem:
      type: object
      description: A creative assets item to be upserted.
      properties:
        creative_assets_id:
          description: The catalog creative assets id in the merchant namespace
          example: DS0294-M
          type: string
        operation:
          type: string
          enum:
          - UPSERT
        attributes:
          $ref: '#/components/schemas/CatalogsCreativeAssetsAttributes'
      required:
      - creative_assets_id
      - operation
      - attributes
    CreativeAssetsProcessingRecord:
      type: object
      description: Object describing an item processing record
      properties:
        creative_assets_id:
          description: The catalog creative assets id in the merchant namespace
          example: DS0294-M
          type: string
        errors:
          description: 'Array with the validation errors for the item processing record.

            A non empty errors list causes the item processing to fail.'
          items:
            $ref: '#/components/schemas/ItemValidationEvent'
          type: array
        warnings:
          description: Array with the validation warnings for the item processing record
          items:
            $ref: '#/components/schemas/ItemValidationEvent'
          type: array
        status:
          $ref: '#/components/schemas/ItemProcessingStatus'
    PinMediaSourceImageURL:
      title: Image URL
      description: Image URL-based media source
      type: object
      properties:
        source_type:
          type: string
          enum:
          - image_url
        url:
          type: string
        is_standard:
          type: boolean
          description: Set the parameter to false to create the new simplified Pin instead of the standard pin. Currently the field is only available to a list of beta users.
          default: true
      required:
      - source_type
      - url
    PinMediaSourceImageBase64:
      title: Image Base64
      description: Base64-encoded image media source
      type: object
      properties:
        source_type:
          type: string
          enum:
          - image_base64
        content_type:
          type: string
          enum:
          - image/jpeg
          - image/png
        data:
          type: string
          pattern: '[a-zA-Z0-9+\/=]+'
        is_standard:
          type: boolean
          description: Set the parameter to false to create the new simplified Pin instead of the standard pin. Currently the field is only available to a list of beta users.
          default: true
      required:
      - source_type
      - content_type
      - data
    BoardOwner:
      title: Board owner
      type: object
      properties:
        username:
          type: string
          readOnly: true
    PinMediaSourceVideoID:
      title: Video ID
      description: Video ID-based media source
      type: object
      properties:
        source_type:
          type: string
          enum:
          - video_id
        cover_image_url:
          type: string
          description: Cover image url.
        cover_image_content_type:
          type: string
          description: Content type for cover image Base64.
          enum:
          - image/jpeg
          - image/png
        cover_image_data:
          type: string
          description: Cover image Base64.
        media_id:
          type: string
          pattern: ^\d+$
        is_standard:
          type: boolean
          description: Set the parameter to false to create the new simplified Pin instead of the standard pin. Currently the field is only available to a list of beta users.
          default: true
      required:
      - source_type
      - media_id
    CatalogsHotelAttributes:
      type: object
      allOf:
      - type: object
        properties:
          main_image:
            type: object
            description: The main hotel image
            properties:
              link:
                type: string
                description: '<p><= 2000 characters</p>

                  <p>The link to the main hotel image. Image should be at least

                  75x75 pixels to avoid errors. Use the additional_image_link field to add

                  more images of your hotel. The URL of your main_image.link must be accessible

                  by the Pinterest user-agent, and send the accurate image. Please make

                  sure there is no template or placeholder image at the link. Must start

                  with http:// or https://.</p>'
              tag:
                type: array
                nullable: true
                description: Tag appended to the image that identifies image category or details. There can be multiple tags associated with an image
                items:
                  type: string
          additional_image_link:
            type: array
            nullable: true
            items:
              type: string
            description: '<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>'
            example:
            - https://scene.example.com/image/image_v2.jpg
            - https://scene.example.com/image/image_v3.jpg
      - $ref: '#/components/schemas/CatalogsUpdatableHotelAttributes'
    CatalogsUpdatableHotelAttributes:
      type: object
      properties:
        name:
          description: The hotel's name.
          type: string
          nullable: true
        link:
          description: Link to the product page
          type: string
          nullable: true
        description:
          description: Brief description of the hotel.
          type: string
          nullable: true
        brand:
          description: The brand to which this hotel belongs to.
          type: string
          nullable: true
        latitude:
          description: Latitude of the hotel.
          type: number
        longitude:
          description: Longitude of the hotel.
          type: number
          nullable: true
        neighborhood:
          description: A list of neighborhoods where the hotel is located
          type: array
          nullable: true
          items:
            type: string
        address:
          description: Hotel address
          $ref: '#/components/schemas/CatalogsHotelAddress'
        custom_label_0:
          description: Custom grouping of hotels
          type: string
          nullable: true
        custom_label_1:
          description: Custom grouping of hotels
          type: string
          nullable: true
        custom_label_2:
          description: Custom grouping of hotels
          type: string
          nullable: true
        custom_label_3:
          description: Custom grouping of hotels
          type: string
          nullable: true
        custom_label_4:
          description: Custom grouping of hotels
          type: string
          nullable: true
        category:
          description: The type of property. The category can be any type of internal description desired.
          type: string
          nullable: true
        base_price:
          description: Base price of the hotel room per night followed by the ISO currency code
          type: string
          nullable: true
          example: 100 USD
        sale_price:
          description: Sale price of a hotel room per night. Used to advertise discounts off the regular price of the hotel.
          type: string
          nullable: true
          example: 90 USD
        guest_ratings:
          description: If specified, you must provide all properties
          $ref: '#/components/schemas/CatalogsHotelGuestRatings'
    CatalogsRetailItemErrorResponse:
      type: object
      description: Object describing a retail item error
      properties:
        catalog_type:
          $ref: '#/components/schemas/CatalogsType'
        item_id:
          description: The catalog item id in the merchant namespace
          example: DS0294-M
          type: string
        errors:
          description: Array with the errors for the item id requested
          items:
            $ref: '#/components/schemas/ItemValidationEvent'
          type: array
      required:
      - catalog_type
    CatalogsItemsUpdateBatchRequest:
      description: Request object to update catalogs items
      type: object
      additionalProperties: false
      properties:
        country:
          $ref: '#/components/schemas/Country'
        language:
          $ref: '#/components/schemas/Language'
        operation:
          $ref: '#/components/schemas/BatchOperation'
        items:
          type: array
          description: Array with catalogs items
          items:
            $ref: '#/components/schemas/ItemUpdateBatchRecord'
          minItems: 1
          maxItems: 1000
      required:
      - country
      - language
      - operation
      - items
    PinMedia:
      title: Pin media
      type: object
      description: Pin media objects.
      discriminator:
        propertyName: media_type
        mapping:
          image: '#/components/schemas/PinMediaWithImage'
          video: '#/components/schemas/PinMediaWithVideo'
          multiple_images: '#/components/schemas/PinMediaWithImages'
          multiple_videos: '#/components/schemas/PinMediaWithVideos'
          multiple_mixed: '#/components/schemas/PinMediaWithImageAndVideo'
      properties:
        media_type:
          type: string
    CatalogsDeleteHotelItem:
      type: object
      description: A hotel item to be deleted
      properties:
        hotel_id:
          description: The catalog hotel id in the merchant namespace
          example: DS0294-M
          type: string
        operation:
          type: string
          enum:
          - DELETE
      required:
      - hotel_id
      - operation
    CatalogsVerticalBatchRequest:
      type: object
      title: operate on item batch
      description: A request object that can have multiple operations on a single batch
      oneOf:
      - $ref: '#/components/schemas/CatalogsRetailBatchRequest'
      - $ref: '#/components/schemas/CatalogsHotelBatchRequest'
      - $ref: '#/components/schemas/CatalogsCreativeAssetsBatchRequest'
      discriminator:
        propertyName: catalog_type
        mapping:
          RETAIL: '#/components/schemas/CatalogsRetailBatchRequest'
          HOTEL: '#/components/schemas/CatalogsHotelBatchRequest'
          CREATIVE_ASSETS: '#/components/schemas/CatalogsCreativeAssetsBatchRequest'
    CatalogsItemsDeleteDiscontinuedBatchRequest:
      description: Request object to discontinue catalogs items
      type: object
      additionalProperties: false
      properties:
        country:
          $ref: '#/components/schemas/Country'
        language:
          $ref: '#/components/schemas/Language'
        operation:
          $ref: '#/components/schemas/BatchOperation'
        items:
          type: array
          description: Array with catalogs items
          items:
            $ref: '#/components/schemas/ItemDeleteDiscontinuedBatchRecord'
      required:
      - country
      - language
      - operation
      - items
    CatalogsHotelBatchRequest:
      description: Request object to update catalogs hotel items
      type: object
      additionalProperties: false
      properties:
        catalog_type:
          $ref: '#/components/schemas/CatalogsType'
        country:
          $ref: '#/components/schemas/Country'
        language:
          $ref: '#/components/schemas/Language'
        items:
          minItems: 1
          maxItems: 1000
          type: array
          description: Array with catalogs item operations
          items:
            $ref: '#/components/schemas/CatalogsHotelBatchItem'
        catalog_id:
          description: Catalog id pertaining to the hotel item. If not provided, default to oldest hotel catalog
          example: '2680059592705'
          type: string
          pattern: ^\d+$
      required:
      - catalog_type
      - country
      - language
      - items
    CatalogsItemsDeleteBatchRequest:
      description: Request object to delete catalogs items
      type: object
      additionalProperties: false
      properties:
        country:
          $ref: '#/components/schemas/Country'
        language:
          $ref: '#/components/schemas/Language'
        operation:
          $ref: '#/components/schemas/BatchOperation'
        items:
          type: array
          description: Array with catalogs items
          items:
            $ref: '#/components/schemas/ItemDeleteBatchRecord'
      required:
      - country
      - language
      - operation
      - items
    CatalogsCreateCreativeAssetsItem:
      type: object
      description: A creative assets item to be created.
      properties:
        creative_assets_id:
          description: The catalog creative assets id in the merchant namespace
          example: DS0294-M
          type: string
        operation:
          type: string
          enum:
          - CREATE
        attributes:
          $ref: '#/components/schemas/CatalogsCreativeAssetsAttributes'
      required:
      - creative_assets_id
      - operation
      - attributes
    CatalogsHotelAddress:
      type: object
      properties:
        addr1:
          description: Primary street address of hotel.
          type: string
        city:
          description: City where the hotel is located.
          type: string
        region:
          description: State, county, province, where the hotel is located.
          type: string
        country:
          description: Country where the hotel is located.
          type: string
        postal_code:
          description: Required for countries with a postal code system. Postal or zip code of the hotel.
          type: string
    CatalogsHotelGuestRatings:
      type: object
      description: If specified, you must provide all properties
      properties:
        score:
          description: Your hotel's rating.
          type: number
        number_of_reviewers:
          description: Total number of people who have rated this hotel.
          type: integer
        max_score:
          description: Max value for the hotel rating score.
          type: number
        rating_system:
          description: System you use for guest reviews.
          type: string
    BatchOperationStatus:
      description: The status of the operation performed by the batch
      example: PROCESSING
      type: string
      enum:
      - PROCESSING
      - COMPLETED
      - FAILED
    PinMediaSourcePinURL:
      title: Pin URL
      description: Pin URL-based media source for product pin creation. Currently the field is only available to a list of beta users.
      type: object
      properties:
        source_type:
          type: string
          enum:
          - pin_url
        is_affiliate_link:
          type: boolean
          description: This is an affiliate link or sponsored product. The FTC requires disclosure for paid partnerships and affiliate products.
          default: false
      required:
      - source_type
    CreativeType:
      type: string
      description: Ad creative type enum. For update, only draft ads may update creative type. </p><strong>Note:</strong> SHOP_THE_PIN has been deprecated. Please use COLLECTION instead.
      enum:
      - REGULAR
      - VIDEO
      - SHOPPING
      - CAROUSEL
      - MAX_VIDEO
      - SHOP_THE_PIN
      - COLLECTION
      - IDEA
      - SHOWCASE
      - QUIZ
      example: REGULAR
      title: CreativeType
    CatalogsUpsertRetailItem:
      type: object
      description: An item to be upserted
      properties:
        item_id:
          description: The catalog item id in the merchant namespace
          example: DS0294-M
          type: string
        operation:
          type: string
          enum:
          - CREATE
          - UPDATE
          - UPSERT
          - DELETE
        attributes:
          $ref: '#/components/schemas/ItemAttributesRequest'
      required:
      - item_id
      - operation
      - attributes
    CatalogsDeleteCreativeAssetsItem:
      type: object
      description: A creative assets item to be deleted
      properties:
        creative_assets_id:
          description: The catalog creative assets id in the merchant namespace
          example: DS0294-M
          type: string
        operation:
          type: string
          enum:
          - DELETE
      required:
      - creative_assets_id
      - operation
    CatalogsCreateRetailItem:
      type: object
      description: An item to be created
      properties:
        item_id:
          description: The catalog item id in the merchant namespace
          example: DS0294-M
          type: string
        operation:
          type: string
          enum:
          - CREATE
          - UPDATE
          - UPSERT
          - DELETE
        attributes:
          $ref: '#/components/schemas/ItemAttributesRequest'
      required:
      - item_id
      - operation
      - attributes
    CatalogsUpdateCreativeAssetsItem:
      type: object
      description: A creative assets item to be updated.
      properties:
        creative_assets_id:
          description: The catalog creative assets item id in the merchant namespace
          example: DS0294-M
          type: string
        operation:
          type: string
          enum:
          - UPDATE
        attributes:
          $ref: '#/components/schemas/CatalogsUpdatableCreativeAssetsAttributes'
      required:
      - creative_assets_id
      - operation
      - attributes
    CatalogsUpdatableCreativeAssetsAttributes:
      type: object
      properties:
        title:
          description: The name of the creative assets.
          type: string
        description:
          description: Brief description of the creative assets.
          type: string
        link:
          description: Link to the creative assets page.
          type: string
        ios_deep_link:
          description: IOS deep link to the creative assets page.
          type: string
          nullable: true
        android_deep_link:
          description: Link to the creative assets page.
          type: string
          nullable: true
        google_product_category:
          description: 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.
          type: string
          nullable: true
        custom_label_0:
          description: Custom grouping of creative assets.
          type: string
          nullable: true
        custom_label_1:
          description: Custom grouping of creative assets.
          type: string
          nullable: true
        custom_label_2:
          description: Custom grouping of creative assets.
          type: string
          nullable: true
        custom_label_3:
          description: Custom grouping of creative assets.
          type: string
          nullable: true
        custom_label_4:
          description: Custom grouping of creative assets.
          type: string
          nullable: true
        visibility:
          description: 'Visibility of the creative assets. Must be one of the following values (upper or lowercase): visible, hidden.'
          type: string
          nullable: true
    CatalogsItemsBatch:
      type: object
      description: Object describing the catalogs items batch
      properties:
        catalog_type:
          $ref: '#/components/schemas/CatalogsType'
      required:
      - catalog_type
      oneOf:
      - $ref: '#/components/schemas/CatalogsRetailItemsBatch'
      - $ref: '#/components/schemas/CatalogsHotelItemsBatch'
      - $ref: '#/components/schemas/CatalogsCreativeAssetsItemsBatch'
      discriminator:
        propertyName: catalog_type
        mapping:
          RETAIL: '#/components/schemas/CatalogsRetailItemsBatch'
          HOTEL: '#/components/schemas/CatalogsHotelItemsBatch'
          CREATIVE_ASSETS: '#/components/schemas/CatalogsCreativeAssetsItemsBatch'
    Country:
      type: string
      description: Country ID from ISO 3166-1 alpha-2.
      example: US
      enum:
      - 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
    ItemDeleteBatchRecord:
      type: object
      description: Object describing an item batch record to delete items
      properties:
        item_id:
          description: The catalog item id in the merchant namespace
          example: DS0294-M
          type: string
    ItemProcessingStatus:
      description: The status of the item processing record
      example: SUCCESS
      type: string
      enum:
      - SUCCESS
      - FAILURE
      - PROCESSING
    ItemAttributesRequest:
      type: object
      allOf:
      - type: object
        properties:
          additional_image_link:
            description: '<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>'
            example:
            - https://scene.example.com/image/image_v2.jpg
            - https://scene.example.com/image/image_v3.jpg
            type: array
            nullable: true
            items:
              type: string
          image_link:
            description: '<p><= 2000 characters</p>

              <p>The links 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>'
            example:
            - https://scene.example.com/image/image.jpg
            oneOf:
            - description: The list of links to the main product images
              type: array
              minItems: 1
              items:
                type: string
            - description: The main product image link.
              type: string
              nullable: false
      - $ref: '#/components/schemas/UpdatableItemAttributes'
    UpdateMaskFieldType:
      description: The field types supported by the update mask
      example: availability
      type: string
      enum:
      - ad_link
      - adult
      - age_group
      - availability
      - average_review_rating
      - brand
      - checkout_enabled
      - color
      - condition
      - custom_label_0
      - custom_label_1
      - custom_label_2
      - custom_label_3
      - custom_label_4
      - description
      - free_shipping_label
      - free_shipping_limit
      - gender
      - google_product_category
      - gtin
      - item_group_id
      - last_updated_time
      - link
      - material
      - min_ad_price
      - mpn
      - number_of_ratings
      - number_of_reviews
      - pattern
      - price
      - product_type
      - sale_price
      - shipping
      - shipping_height
      - shipping_weight
      - shipping_width
      - size
      - size_system
      - size_type
      - tax
      - title
      - variant_names
      - variant_values
    CatalogsType:
      description: Type of the catalog entity.
      type: string
      enum:
      - RETAIL
      - HOTEL
      - CREATIVE_ASSETS
    Pin:
      title: Pin
      description: Pin
      type: object
      nullable: true
      properties:
        id:
          type: string
          readOnly: true
          example: '813744226420795884'
          pattern: ^\d+$
        created_at:
          type: string
          format: date-time
          readOnly: true
          example: '2020-01-01T20:10:40-00:00'
        link:
          type: string
          nullable: true
          example: https://www.pinterest.com/
          maxLength: 2048
        title:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        dominant_color:
          type: string
          nullable: true
          description: Dominant pin color. Hex number, e.g. \"#6E7874\".
          example: '#6E7874'
        alt_text:
          type: string
          nullable: true
          maxLength: 500
        creative_type:
          readOnly: true
          nullable: true
          type: string
          allOf:
          - $ref: '#/components/schemas/CreativeType'
        board_id:
          description: The board to which this Pin belongs.
          type: string
          pattern: ^\d+$
        board_section_id:
          description: The board section to which this Pin belongs.
          type: string
          pattern: ^\d+$
          nullable: true
        board_owner:
          allOf:
          - $ref: '#/components/schemas/BoardOwner'
          type: object
          readOnly: true
        is_owner:
          description: Whether the "operation user_account" is the Pin owner.
          type: boolean
          readOnly: true
        media:
          allOf:
          - $ref: '#/components/schemas/PinMedia'
          type: object
          readOnly: true
        media_source:
          allOf:
          - $ref: '#/components/schemas/PinMediaSource'
          type: object
          writeOnly: true
        parent_pin_id:
          description: The source pin id if this pin was saved from another pin. <a href="https://help.pinterest.com/article/save-pins-on-pinterest">Learn more</a>.
          type: string
          pattern: ^\d+$
          nullable: true
        is_standard:
          description: Whether the Pin is standard or not. See documentation on <a href="https://developers.pinterest.com/docs/content/update/">Changes to Pin creation</a> for more information.
          type: boolean
        has_been_promoted:
          description: Whether the Pin has been promoted or not.
          type: boolean
          readOnly: true
        note:
          description: Private note for this Pin. <a href="https://help.pinterest.com/en/article/add-notes-to-your-pins">Learn more</a>.
          type: string
          nullable: true
        pin_metrics:
          description: Pin metrics with associated time intervals if any.
          type: object
          nullable: true
          example:
            pin_metrics:
            - 90d:
                pin_click: 7
                impression: 2
                clickthrough: 3
              all_time:
                pin_click: 7
                impression: 2
                clickthrough: 3
                reaction: 10
                comment: 2
            - null
    CatalogsCreativeAssetsItemErrorResponse:
      type: object
      description: Object describing a creative assets item error
      properties:
        catalog_type:
          $ref: '#/components/schemas/CatalogsType'
        creative_assets_id:
          description: The catalog creative assets id in the merchant namespace
          example: DS0294-M
          type: string
        errors:
          description: Array with the errors for the item id requested
          items:
            $ref: '#/components/schemas/ItemValidationEvent'
          type: array
      required:
      - catalog_type
    CatalogsCreativeAssetsBatchItem:
      description: Creative assets batch item
      type: object
      anyOf:
      - $ref: '#/components/schemas/CatalogsCreateCreativeAssetsItem'
      - $ref: '#/components/schemas/CatalogsUpsertCreativeAssetsItem'
      - $ref: '#/components/schemas/CatalogsUpdateCreativeAssetsItem'
      - $ref: '#/components/schemas/CatalogsDeleteCreativeAssetsItem'
      discriminator:
        propertyName: operation
        mapping:
          CREATE: '#/components/schemas/CatalogsCreateCreativeAssetsItem'
          UPSERT: '#/components/schemas/CatalogsUpsertCreativeAssetsItem'
          UPDATE: '#/components/schemas/CatalogsUpdateCreativeAssetsItem'
          DELETE: '#/components/schemas/CatalogsDeleteCreativeAssetsItem'
    CatalogsHotelItemsPostFilter:
      type: object
      properties:
        catalog_type:
          type: string
          enum:
          - HOTEL
        hotel_ids:
          type: array
          minItems: 1
          maxItems: 1000
          items:
            type: string
        catalog_id:
          type: string
          pattern: ^\d+$
          description: Catalog id pertaining to the hotel item. If not provided, default to oldest hotel catalog
      required:
      - catalog_type
      - hotel_ids
  parameters:
    query_catalogs_items:
      deprecated: true
      name: item_ids
      in: query
      description: This parameter is deprecated. Use filters instead.
      example:
      - CR123
      required: false
      schema:
        type: array
        items:
          type: string
    query_catalogs_items_language:
      name: language
      in: query
      description: Language for the Catalogs Items
      example: EN
      required: true
      schema:
        type: string
    path_catalogs_items_batch_id:
      name: batch_id
      in: path
      description: Id of a catalogs items batch to fetch
      example: 595953100599279259-66753b9bb65c46c49bd8503b27fecf9e
      required: true
      schema:
        type: string
    query_ad_account_id:
      name: ad_account_id
      description: Unique identifier of an ad account.
      in: query
      schema:
        type: string
        pattern: ^\d+$
        maxLength: 18
    query_catalogs_items_country:
      name: country
      in: query
      description: Country for the Catalogs Items
      example: US
      required: true
      schema:
        type: string
    query_catalogs_items_filters:
      name: filters
      in: query
      description: Identifies items to be retrieved. This is a required parameter.
      required: false
      style: deepObject
      schema:
        $ref: '#/components/schemas/CatalogsItemsFilters'
  securitySchemes:
    pinterest_oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://www.pinterest.com/oauth/
          tokenUrl: https://api.pinterest.com/v5/oauth/token
          scopes:
            ads:read: See all of your advertising data, including ads, ad groups, campaigns etc.
            ads:write: Create, update, or delete ads, ad groups, campaigns etc.
            billing:read: See all of your billing data, billing profile, etc.
            billing:write: Create, update, or delete billing data, billing profiles, etc.
            biz_access:read: See business access data
            biz_access:write: Create, update, or delete business access data
            boards:read: See your public boards, including group boards you join
            boards:read_secret: See your secret boards
            boards:write: Create, update, or delete your public boards
            boards:write_secret: Create, update, or delete your secret boards
            catalogs:read: See all of your catalogs data
            catalogs:write: Create, update, or delete your catalogs data
            pins:read: See your public Pins
            pins:read_secret: See your secret Pins
            pins:write: Create, update, or delete your public Pins
            pins:write_secret: Create, update, or delete your secret Pins
            user_accounts:read: See your user accounts and followers
            user_accounts:write: Update your user accounts and followers
    conversion_token:
      type: http
      scheme: bearer
      description: This security scheme only applies to the conversion events endpoint (POST /ad_accounts/{ad_account_id}/events). This endpoint requires a bearer token generated via Ads Manager (ads.pinterest.com).
    basic:
      type: http
      scheme: basic
x-tagGroups:
- name: Pin and Boards
  tags:
  - pins
  - boards
  - media
  - aggregated_comments
  - aggregated_pin_data
  - user_account
- name: Campaign Management
  tags:
  - ad_accounts
  - campaigns
  - ad_groups
  - ads
  - product_group_promotions
  - bulk
- name: Targeting
  tags:
  - audiences
  - customer_lists
  - keywords
  - targeting_template
  - audience_insights
  - audience_sharing
- name: Ad Formats
  tags:
  - lead_forms
  - lead_ads
  - leads_export
- name: Billing
  tags:
  - billing
  - order_lines
  - terms_of_service
- name: Business Access
  tags:
  - business_access_assets
  - business_access_invite
  - business_access_relationships
- name: Conversions
  tags:
  - conversion_events
  - conversion_tags
- name: Others
  tags:
  - integrations
  - oauth
  - resources
  - search
  - terms
- name: Shopping
  tags:
  - catalogs
- name: Deprecated
  tags:
  - product_groups