Skai (Kenshoo) Product Groups API

openapi: 3.2.0
info:
  title: Skai Product Groups API
  description: '# Overview

    Skai APIs provide programmatic access to advertising data and campaign management across Search, Social, and Retail Media publishers.'
  version: 1.0.0
  x-logo:
    url: https://grid.kenshoo.com/resources-frontend/latest/kenshoo_logo/skai-logo-devportal.svg
    backgroundColor: '#FFFFFF'
    altText: Skai
servers:
- url: https://services.kenshoo.com
security:
- BearerAuth: []
tags:
- name: Product Groups
  description: 'Create, update, and retrieve product groups for Shopping campaigns.


    > **Scope:** Covers product group creation and status updates.

    > For bulk product group management use Bulk Update (One File).


    Publishers:

    Search Shopping

    Pinterest Shopping'
paths:
  /api/v1/product_groups:
    post:
      tags:
      - Product Groups
      summary: Create a new product group
      description: 'Create one or more product groups within a Shopping campaign ad group.


        **For bulk product group management** use Bulk Update (One File) with `bulk_update_type=PRODUCT_GROUP`.'
      operationId: createProductGroups
      parameters:
      - $ref: '#/components/parameters/ks'
      requestBody:
        $ref: '#/components/requestBodies/Productgroup'
      responses:
        201:
          $ref: '#/components/responses/EntitySuccessResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        500:
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    ApiResponseStatus:
      type: string
      readOnly: true
      enum:
      - SUCCESS
      - FAILED
      - PARTIAL_SUCCESS
    ApiResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ApiResponseStatus'
        entities:
          type: array
          items:
            $ref: '#/components/schemas/EntityResponse'
    ProductGroupNode:
      required:
      - dimension
      type: object
      properties:
        level:
          type: integer
          description: Required for Google. Defines which level each path represents on the tree.
        type:
          $ref: '#/components/schemas/ProductGroupType'
        dimension:
          type: string
          description: The value of the filter name
        catalog_id:
          type: integer
          description: Required for Pinterest - this represents the ID of the organic product group
    Productgroup:
      required:
      - ad_group_id
      type: object
      properties:
        ad_group_id:
          type: integer
          description: The ID of the ad group this product group is created in
        bid:
          type: number
          description: Bid
        inherit_bid:
          type: boolean
          description: The bid should be inherited from the ad group
          default: false
        tracking_url:
          type: string
          description: Tracking URL
        nodes:
          type: array
          items:
            $ref: '#/components/schemas/ProductGroupNode'
      description: The properties for the newly created product group
      example:
      - bid: 1.0
        nodes:
        - level: 1
          dimension: DIM 1
          type: CUSTOM_ATTRIBUTE_2
        - level: 2
          dimension: DIM 2
          type: CUSTOM_ATTRIBUTE_1
        - level: 3
          dimension: DIM 3
          type: BRAND
        ad_group_id: 1234
      - nodes:
        - level: 1
          dimension: a pinterest product group
          catalog_id: '12345678'
        ad_group_id: 5678
        tracking_url: www.my-url.com
    EntityResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
        success:
          type: boolean
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorField'
    ErrorField:
      type: object
      properties:
        fieldName:
          type: string
          description: The error field
        error:
          type: string
          description: Error message
        parameters:
          type: object
          additionalProperties:
            type: string
          description: Error additional properties
    ProductGroupType:
      type: string
      description: Required for Google. Defines the type of filter for each path in the tree.
      enum:
      - ADWORDS_GROUPING
      - ADWORDS_LABELS
      - BIDDING_CATEGORY_L1
      - BIDDING_CATEGORY_L2
      - BIDDING_CATEGORY_L3
      - BIDDING_CATEGORY_L4
      - BIDDING_CATEGORY_L5
      - BRAND
      - CANONICAL_CONDITION
      - LEGACY_CONDITION
      - CUSTOM_ATTRIBUTE_0
      - CUSTOM_ATTRIBUTE_1
      - CUSTOM_ATTRIBUTE_2
      - CUSTOM_ATTRIBUTE_3
      - CUSTOM_ATTRIBUTE_4
      - OFFER_ID
      - PRODUCT_TYPE_L1
      - PRODUCT_TYPE_L2
      - PRODUCT_TYPE_L3
      - PRODUCT_TYPE_L4
      - PRODUCT_TYPE_L5
      - GTIN
      - MPN
      - CHANNEL
      - CHANNEL_EXCLUSIVITY
      - TYPE_FULL
      - UNSUPPORTED
      - NONE
  requestBodies:
    Productgroup:
      description: The product group details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Productgroup'
      required: true
  responses:
    BadRequest:
      description: Bad request (usually indicates validation failure for client input)
      content:
        application/json:
          schema:
            $ref: '#/components/responses/ApiResponse'
          example:
            status: FAILED
            entities:
            - id: null
              success: false
              errors:
              - field_name: name
                error: ILLEGAL_NAME
    InternalServerError:
      description: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/responses/ApiResponse'
          example:
            status: FAILED
            entities:
            - id: null
              success: false
              errors:
              - field_name: ServerError
                error: Unexpected error occurred.
                parameters: {}
    EntitySuccessResponse:
      description: The entity operations succeeded
      content:
        application/json:
          schema:
            $ref: '#/components/responses/ApiResponse'
          example:
            status: SUCCESS
            entities:
            - id: 1234
              success: true
              errors: []
    ApiResponse:
      $ref: '#/components/schemas/ApiResponse'
  parameters:
    ks:
      name: ks
      in: query
      description: The KS to refer the request to. You can find this ID in the Skai platform under _Administration_ -> _About Skai_ -> _Server ID_
      required: true
      style: form
      explode: true
      schema:
        type: string
      example: '1234'
x-tagGroups:
- name: Reporting
  tags:
  - Available Columns
  - Synchronous Reports
  - Asynchronous Reports
- name: Bulk Operations
  tags:
  - Jobs
  - Bulk Update
- name: AI & MCP
  tags:
  - MCP
- name: Objects
  tags:
  - Profile
  - Campaigns
  - Ad Groups
  - Ads
  - Product Groups
  - Portfolios
  - Meta Campaigns
  - Meta Ad Groups
  - Meta Ads
  - Columns