Impact Radius Catalog Items API

openapi: 3.2.0
info:
  title: Brand API - Product Catalogs Catalog Items API
  description: 'API for managing Product Catalogs and their items. This allows for programmatic updates to catalog settings, file uploads, and CRUD operations on individual items.

    Note: Creating and deleting the catalogs themselves must be done in the impact.com web app.'
  version: v14
servers:
- url: https://api.impact.com
security:
- basicAuth: []
tags:
- name: Catalog Items
paths:
  /Advertisers/{AccountSID}/Catalogs/{CatalogId}/Items:
    get:
      summary: List Catalog Items
      description: Returns a list of items for a specific catalog, with support for keyword search, filtering, and sorting. This endpoint has a paging limit of 20,000 total records.
      operationId: listCatalogItems
      tags:
      - Catalog Items
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
        description: Your unique account identifier.
      - name: CatalogId
        in: path
        required: true
        schema:
          type: integer
        description: Unique identifier for the catalog.
      - name: Keyword
        in: query
        schema:
          type: string
        description: Search for a word or phrase across all item attributes.
      - name: PromotionIds
        in: query
        schema:
          type: string
        description: Use 'null' to find items with no promotions, or '!=null' for items with promotions.
      - name: Query
        in: query
        schema:
          type: string
        description: 'Advanced search query using operators like ''>'', ''<'', ''='', ''!='', ''~'', ''AND'', ''OR'', ''IN''. Eligible fields: `CatalogItemId`, `Name`, `Description`, `Labels`, `Manufacturer`, `CurrentPrice`, `StockAvailability`, `Gtin`, `Category`, `DiscountPercentage`, `Gender`, `Color`, `Size`.'
      - name: SortBy
        in: query
        schema:
          type: string
        description: 'Sort results by a specific attribute (e.g., ''CurrentPrice''). Use SortOrder for direction. Eligible fields: `CatalogItemId`, `Name`, `Description`, `Labels`, `Manufacturer`, `CurrentPrice`, `StockAvailability`, `Gtin`, `Category`, `DiscountPercentage`, `Gender`, `Color`, `Size`.'
      responses:
        '200':
          description: A paginated list of catalog item objects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Items:
                    type: array
                    items:
                      $ref: '#/components/schemas/CatalogItem'
      x-codeSamples:
      - lang: cURL
        source: "curl -L \\\n  --url 'https://api.impact.com/Advertisers/{AccountSID}/Catalogs/{CatalogId}/Items' \\\n  --user '{AccountSID}:{AuthToken}' \\\n  --header 'Accept: */*'"
    post:
      summary: Create a Catalog Item
      description: Creates a new item within a specified catalog.
      operationId: createCatalogItem
      tags:
      - Catalog Items
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
        description: Your unique account identifier.
      - name: CatalogId
        in: path
        required: true
        schema:
          type: integer
        description: Unique identifier for the catalog.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CatalogItemCreate'
      responses:
        '200':
          description: The request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessUriResponse'
      x-codeSamples:
      - lang: cURL
        source: "curl -L \\\n  --request POST \\\n  --url 'https://api.impact.com/Advertisers/{AccountSID}/Catalogs/{CatalogId}/Items' \\\n  --user '{AccountSID}:{AuthToken}' \\\n  --header 'Content-Type: application/json' \\\n  --header 'Accept: */*'"
  /Advertisers/{AccountSID}/Catalogs/{CatalogId}/Items/{CatalogItemId}:
    get:
      summary: Get Catalog Item Details
      description: Retrieves the details of an existing catalog item by its unique ID.
      operationId: getCatalogItemById
      tags:
      - Catalog Items
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
        description: Your unique account identifier.
      - name: CatalogId
        in: path
        required: true
        schema:
          type: integer
        description: Unique identifier for the catalog.
      - name: CatalogItemId
        in: path
        required: true
        schema:
          type: string
        description: Unique identifier for the catalog item.
      responses:
        '200':
          description: A single catalog item object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogItem'
      x-codeSamples:
      - lang: cURL
        source: "curl -L \\\n  --url 'https://api.impact.com/Advertisers/{AccountSID}/Catalogs/{CatalogId}/Items/{CatalogItemId}' \\\n  --user '{AccountSID}:{AuthToken}' \\\n  --header 'Accept: */*'"
    put:
      summary: Update a Single Catalog Item
      description: Updates a single specified catalog item by setting the values of the parameters passed.
      operationId: updateCatalogItem
      tags:
      - Catalog Items
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
        description: Your unique account identifier.
      - name: CatalogId
        in: path
        required: true
        schema:
          type: integer
        description: Unique identifier for the catalog.
      - name: CatalogItemId
        in: path
        required: true
        schema:
          type: string
        description: Unique identifier for the catalog item.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CatalogItem'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CatalogItem'
      responses:
        '200':
          description: The request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessUriResponse'
      x-codeSamples:
      - lang: cURL
        source: "curl -L \\\n  --request PUT \\\n  --url 'https://api.impact.com/Advertisers/{AccountSID}/Catalogs/{CatalogId}/Items/{CatalogItemId}' \\\n  --user '{AccountSID}:{AuthToken}' \\\n  --header 'Content-Type: application/json' \\\n  --header 'Accept: */*'"
    delete:
      summary: Delete a Catalog Item
      description: Permanently deletes a catalog item. This cannot be undone.
      operationId: deleteCatalogItem
      tags:
      - Catalog Items
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
        description: Your unique account identifier.
      - name: CatalogId
        in: path
        required: true
        schema:
          type: integer
        description: Unique identifier for the catalog.
      - name: CatalogItemId
        in: path
        required: true
        schema:
          type: string
        description: Unique identifier for the catalog item.
      responses:
        '200':
          description: The item was deleted successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Status:
                    type: string
                    example: DELETED
      x-codeSamples:
      - lang: cURL
        source: "curl -L \\\n  --request DELETE \\\n  --url 'https://api.impact.com/Advertisers/{AccountSID}/Catalogs/{CatalogId}/Items/{CatalogItemId}' \\\n  --user '{AccountSID}:{AuthToken}' \\\n  --header 'Accept: */*'"
  /Advertisers/{AccountSID}/Catalogs/{CatalogId}/BulkUpdate:
    put:
      summary: Bulk Update Catalog Items
      description: Updates multiple catalog items in a single request. The request body must be a JSON array of item objects, with each object containing its CatalogItemId. A maximum of 500 products can be updated per call.
      operationId: bulkUpdateCatalogItems
      tags:
      - Catalog Items
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
        description: Your unique account identifier.
      - name: CatalogId
        in: path
        required: true
        schema:
          type: integer
        description: Unique identifier for the catalog.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CatalogItem'
            example:
            - CatalogItemId: '12345'
              Name: Anvil
            - CatalogItemId: '67890'
              CurrentPrice: '50.00'
      responses:
        '200':
          description: The request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessUriResponse'
      x-codeSamples:
      - lang: cURL
        source: "curl -L \\\n  --request PUT \\\n  --url 'https://api.impact.com/Advertisers/{AccountSID}/Catalogs/{CatalogId}/BulkUpdate' \\\n  --user '{AccountSID}:{AuthToken}' \\\n  --header 'Content-Type: application/json' \\\n  --header 'Accept: */*'"
components:
  schemas:
    CatalogItemCreate:
      type: object
      description: Request body for creating a new catalog item. CatalogItemId, Name, and Url are required.
      required:
      - CatalogItemId
      - Name
      - Url
      allOf:
      - $ref: '#/components/schemas/CatalogItem'
    CatalogItem:
      type: object
      properties:
        CatalogItemId:
          type: string
          example: ABC123
          description: Unique identifier for the catalog item.
        Name:
          type: string
          example: Acme Tennis Balls (One Dozen)
          description: Name of the item.
        Description:
          type: string
          example: High-performance tennis balls.
          description: Description of the item — information about what it is or what it does.
        Multipack:
          type: string
          example: '1'
          description: Whether the item represents a merchant-defined multi-pack (`YES`/`NO`).
        Bullets:
          type: array
          items:
            type: string
          description: Short bullet descriptions of the product.
        Labels:
          type: array
          items:
            type: string
          description: Key terms to help partners find the item.
        Manufacturer:
          type: string
          example: Acme
          description: The person or group that makes the item.
        Url:
          type: string
          format: uri
          example: https://acme.example.com/product/12345
          description: URL that leads to the item's online store listing.
        MobileUrl:
          type: string
          format: uri
          example: https://m.acme.example.com/product/12345
          description: URI that points directly to the item's mobile listing.
        ImageUrl:
          type: string
          format: uri
          example: https://acme.example.com/images/12345.jpg
          description: URL that leads to the item's image.
        AdditionalImageUrls:
          type: array
          items:
            type: string
          description: List of additional image URLs for the product.
        PromotionIds:
          type: array
          items:
            type: string
          description: List of promotion Ids that identify the item as part of a promotion.
        CurrentPrice:
          type: number
          format: decimal
          example: 29.99
          description: Current consumer price of the item.
        OriginalPrice:
          type: number
          format: decimal
          example: 39.99
          description: Original consumer price of the item.
        DiscountPercentage:
          type: integer
          example: 25
          description: Percent discount a consumer can get when they purchase the product.
        ManufacturingCost:
          type: number
          format: decimal
          description: Cost to produce the item.
        Currency:
          type: string
          description: Currency in which the item's price is listed (ISO 4217).
        StockAvailability:
          type: string
          enum:
          - InStock
          - OutOfStock
          - BackOrder
          - PreOrder
          - LimitedAvailability
          description: Status of the product's backstock (`InStock`, `OutOfStock`, `BackOrder`, `PreOrder`, `LimitedAvailability`).
        EstimatedShipDate:
          type: string
          format: date
          description: Date the item will begin shipping (ISO 8601).
        LaunchDate:
          type: string
          format: date-time
          description: Date the item becomes (or became) available (ISO 8601).
        ExpirationDate:
          type: string
          format: date-time
          description: Date the item will be removed from the catalog (ISO 8601).
        Gtin:
          type: string
          description: Global Trade Item Number.
        GtinType:
          type: string
          enum:
          - EAN
          - UPC
          - ISBN
          - JAN
          description: Type of GTIN number the item uses (`EAN`, `UPC`, `ISBN`, `JAN`).
        Asin:
          type: string
          description: Item's Amazon Standard Identification Number.
        Mpn:
          type: string
          description: Manufacturing Part Number.
        ShippingRate:
          type: number
          format: decimal
          description: Standard rate to ship the item.
        ShippingWeight:
          type: number
          format: decimal
          description: Weight of the shipping parcel.
        ShippingWeightUnit:
          type: string
          enum:
          - lb
          - oz
          - g
          - kg
          - mg
          description: Unit for the shipping parcel's weight (`lb`, `oz`, `g`, `kg`, `mg`).
        ShippingLength:
          type: number
          format: decimal
          description: Length of the shipping parcel.
        ShippingWidth:
          type: number
          format: decimal
          description: Width of the shipping parcel.
        ShippingHeight:
          type: number
          format: decimal
          description: Height of the shipping parcel.
        ShippingLengthUnit:
          type: string
          enum:
          - in
          - cm
          description: Unit for the shipping parcel's dimensions (`in`, `cm`).
        ShippingLabel:
          type: string
          description: Label of the shipping parcel.
        Category:
          type: string
          description: Group or kind of products with which the item is associated.
        OriginalFormatCategory:
          type: string
          description: Category breadcrumb used to locate the item.
        OriginalFormatCategoryId:
          type: string
          description: Id of the category the item is in.
        ParentName:
          type: string
          description: If the item has a parent item, the parent item's name.
        ParentSku:
          type: string
          description: If the item has a parent item, the parent item's SKU.
        IsParent:
          type: boolean
          description: Whether this item represents a bundle of items.
        ItemGroupId:
          type: string
          description: Groups product variants that only differ by attributes like size, color, pattern, age group, or gender.
        Colors:
          type: array
          items:
            type: string
          description: Primary colors of the item.
        Material:
          type: string
          description: Primary material of the item.
        Pattern:
          type: string
          description: Pattern of the item.
        Size:
          type: string
          description: Numerical size of the item.
        SizeUnit:
          type: string
          description: Item's size unit of measurement (e.g., `Inches`, `Centimeters`, `Pounds`, `Kilograms`).
        Weight:
          type: number
          format: decimal
          description: Weight of the item.
        WeightUnit:
          type: string
          enum:
          - lb
          - oz
          - g
          - kg
          - mg
          description: Item's weight unit of measurement (`lb`, `oz`, `g`, `kg`, `mg`).
        Condition:
          type: string
          enum:
          - New
          - Used
          - Refurbished
          - OEM
          - OpenBox
          description: Condition the item is in when sold (`New`, `Used`, `Refurbished`, `OEM`, `OpenBox`).
        AgeGroup:
          type: string
          enum:
          - Newborn
          - Infant
          - Toddler
          - Kids
          - Adult
          description: Age group the item targets (`Newborn`, `Infant`, `Toddler`, `Kids`, `Adult`).
        AgeRangeMin:
          type: integer
          description: Minimum age for whom the item is intended.
        AgeRangeMax:
          type: integer
          description: Maximum age for whom the item is intended.
        AgeRangeUnit:
          type: string
          enum:
          - Months
          - Years
          description: Unit of the age range (`Months`, `Years`).
        Gender:
          type: string
          enum:
          - Male
          - Female
          - Unisex
          description: Gender for whom the item is intended (`Male`, `Female`, `Unisex`).
        Adult:
          type: boolean
          description: Whether the item is only intended for adults.
        ProductBid:
          type: string
          description: How much the partner will be paid for driving a conversion on the product.
        Inventory:
          type: integer
          description: Item's inventory count.
        Text1:
          type: string
          description: General text field that accepts any text data you want to send. Appears in your reports.
        Text2:
          type: string
          description: General text field that accepts any text data you want to send. Appears in your reports.
        Text3:
          type: string
          description: General text field that accepts any text data you want to send. Appears in your reports.
        Numeric1:
          type: number
          format: decimal
          description: General numeral field that accepts any numeric data you want to send. Appears in your reports.
        Numeric2:
          type: number
          format: decimal
          description: General numeral field that accepts any numeric data you want to send. Appears in your reports.
        Numeric3:
          type: number
          format: decimal
          description: General numeral field that accepts any numeric data you want to send. Appears in your reports.
        Money1:
          type: string
          description: General numeral field that accepts any money or financial data you want to send. Appears in your reports.
        Money2:
          type: string
          description: General numeral field that accepts any money or financial data you want to send. Appears in your reports.
        Money3:
          type: string
          description: General numeral field that accepts any money or financial data you want to send. Appears in your reports.
        Uri:
          type: string
          format: uri-reference
          example: /Advertisers/<AccountSID>/Catalogs/<CatalogId>/Items/<CatalogItemId>
          description: URI that points directly to this catalog item.
    SuccessUriResponse:
      type: object
      properties:
        Status:
          type: string
          example: OK
          description: Indicates whether the operation was successful (e.g., `OK`).
        Uri:
          type: string
          format: uri-reference
          description: URI of the affected resource.
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Use your AccountSID as the username and AuthToken as the password.
x-default-client: cURL