openapi: 3.1.0
info:
  title: Brand Product Catalogs API
  version: v11
  description: "Manage product catalogs and the items within them. While catalogs themselves are managed via the web app, \nthis API allows for the programmatic creation, retrieval, updating, and deletion of individual products \nand bulk updates to item data.\n"
servers:
- url: https://api.impact.com
security:
- basicAuth: []
paths:
  /Advertisers/{AccountSID}/Catalogs:
    get:
      operationId: listCatalogs
      tags:
      - Product Catalogs
      summary: List all catalogs
      description: Returns a list of all product catalogs in your program.
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
        description: Your unique account identifier.
      - name: CampaignId
        in: query
        description: Filter catalogs by the ID of the program (campaign) they belong to.
        schema:
          type: integer
      - name: Status
        in: query
        description: Filter catalogs by their current state of use.
        schema:
          type: string
          enum:
          - ACTIVE
          - CLOSED
          - DEACTIVATED
          - PENDING
      responses:
        '200':
          description: A list of catalogs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Catalogs:
                    type: array
                    items:
                      $ref: '#/components/schemas/Catalog'
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/Catalogs' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Accept: */*'
  /Advertisers/{AccountSID}/Catalogs/{CatalogId}:
    get:
      operationId: getCatalog
      tags:
      - Product Catalogs
      summary: Retrieve a catalog
      description: Retrieves metadata for a specific product catalog.
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
        description: Your unique account identifier.
      - name: CatalogId
        in: path
        required: true
        schema:
          type: string
        description: Unique identifier for the catalog.
      responses:
        '200':
          description: Catalog details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Catalog'
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/Catalogs/{CatalogId}' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Accept: */*'
  /Advertisers/{AccountSID}/Catalogs/{CatalogId}/Items:
    get:
      operationId: listCatalogItems
      tags:
      - Catalog Items
      summary: List all items for a catalog
      description: Returns a list of items within a specific catalog with advanced filtering and search.
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
        description: Your unique account identifier.
      - name: CatalogId
        in: path
        required: true
        schema:
          type: string
        description: Unique identifier for the catalog.
      - name: Keyword
        in: query
        schema:
          type: string
      - name: Query
        in: query
        description: "Complex query string (e.g., CurrentPrice > 10.00 AND Manufacturer = 'Acme'). Eligible fields: `CatalogItemId`, `Name`, `Description`, `Labels`, `Manufacturer`, `CurrentPrice`, `StockAvailability`, `Gtin`, `Category`, `DiscountPercentage`, `Gender`, `Color`, `Size`."
        schema:
          type: string
      - name: PromotionIds
        in: query
        description: Use 'null' to find items with no promotions, or '!=null' for items with promotions.
        schema:
          type: string
      - name: SortBy
        in: query
        description: "Sort results by a specific attribute (e.g., 'CurrentPrice'). Eligible fields: `CatalogItemId`, `Name`, `Description`, `Labels`, `Manufacturer`, `CurrentPrice`, `StockAvailability`, `Gtin`, `Category`, `DiscountPercentage`, `Gender`, `Color`, `Size`."
        schema:
          type: string
      responses:
        '200':
          description: A list of items.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Items:
                    type: array
                    items:
                      $ref: '#/components/schemas/CatalogItem'
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/Catalogs/{CatalogId}/Items' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Accept: */*'
    post:
      operationId: createCatalogItem
      tags:
      - Catalog Items
      summary: Create an item for a catalog
      description: Creates a new catalog item. Google Merchant Formatting is highly recommended.
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
        description: Your unique account identifier.
      - name: CatalogId
        in: path
        required: true
        schema:
          type: string
        description: Unique identifier for the catalog.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - CatalogItemId
              - Name
              - Url
              properties:
                CatalogItemId:
                  type: string
                  example: ABC123
                Name:
                  type: string
                  example: Acme Tennis Balls (One Dozen)
                Url:
                  type: string
                  example: https://acme.example.com/product/12345
                Description:
                  type: string
                  example: High-performance tennis balls.
                CurrentPrice:
                  type: number
                  example: 29.99
                StockAvailability:
                  type: string
                  enum:
                  - InStock
                  - OutOfStock
                  - BackOrder
                  - PreOrder
                  - LimitedAvailability
                  example: InStock
      responses:
        '200':
          description: Item created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemResponse'
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --request POST \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/Catalogs/{CatalogId}/Items' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Content-Type: application/json' \
            --header 'Accept: */*'
  /Advertisers/{AccountSID}/Catalogs/{CatalogId}/Items/{CatalogItemId}:
    get:
      operationId: getCatalogItem
      tags:
      - Catalog Items
      summary: Retrieve an item from a catalog
      description: Retrieves details of a specific item within a catalog.
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
        description: Your unique account identifier.
      - name: CatalogId
        in: path
        required: true
        schema:
          type: string
        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: Catalog item details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogItem'
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/Catalogs/{CatalogId}/Items/{CatalogItemId}' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Accept: */*'
    put:
      operationId: updateCatalogItem
      tags:
      - Catalog Items
      summary: Update a catalog item
      description: Update specific fields of an existing catalog item.
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
        description: Your unique account identifier.
      - name: CatalogId
        in: path
        required: true
        schema:
          type: string
        description: Unique identifier for the catalog.
      - name: CatalogItemId
        in: path
        required: true
        schema:
          type: string
        description: Unique identifier for the catalog item.
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CatalogItem'
      responses:
        '200':
          description: Item updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemResponse'
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --request PUT \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/Catalogs/{CatalogId}/Items/{CatalogItemId}' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Content-Type: application/json' \
            --header 'Accept: */*'
    delete:
      operationId: deleteCatalogItem
      tags:
      - Catalog Items
      summary: Delete an item for a catalog
      description: Permanently deletes a catalog item.
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
        description: Your unique account identifier.
      - name: CatalogId
        in: path
        required: true
        schema:
          type: string
        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: Item deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Status:
                    type: string
                    example: DELETED
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --request DELETE \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/Catalogs/{CatalogId}/Items/{CatalogItemId}' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Accept: */*'
  /Advertisers/{AccountSID}/Catalogs/{CatalogId}/bulkUpdate:
    put:
      operationId: bulkUpdateCatalogItems
      tags:
      - Catalog Items
      summary: Bulk update items for a catalog
      description: Update up to 500 products at once using a JSON array.
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
        description: Your unique account identifier.
      - name: CatalogId
        in: path
        required: true
        schema:
          type: string
        description: Unique identifier for the catalog.
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CatalogItem'
      responses:
        '200':
          description: Bulk update processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemResponse'
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --request PUT \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/Catalogs/{CatalogId}/bulkUpdate' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Content-Type: application/json' \
            --header 'Accept: */*'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Use your AccountSID as the username and AuthToken as the password.
  schemas:
    Catalog:
      type: object
      properties:
        Id:
          type: string
          example: '99999'
          description: Unique identifier for the catalog (the impact.com Catalog Id).
        Name:
          type: string
          example: Acme Sports Catalog
          description: Name of the catalog.
        Language:
          type: string
          example: ENGLISH
        Filename:
          type: string
          example: acme_sports.csv
          description: Name of the file that contains the catalog.
        AdvertiserId:
          type: string
          example: '1000'
          description: Id of the brand (formerly known as advertiser) that owns the catalog.
        CampaignId:
          type: string
          example: '1000'
          description: Id of the program (formerly known as campaign) to which the catalog belongs.
        Status:
          type: string
          enum:
          - ACTIVE
          - CLOSED
          - DEACTIVATED
          - PENDING
          example: ACTIVE
          description: State of use the catalog is in (e.g., `ACTIVE`, `CLOSED`, `DEACTIVATED`, `PENDING`).
        NumberOfItems:
          type: integer
          example: 1000
          description: Number of items in the catalog.
        DateLastUpdated:
          type: string
          format: date-time
          example: '2026-01-15T10:00:00-08:00'
          description: Date and time the catalog was last updated (ISO 8601).
        Currency:
          type: string
          example: USD
          description: Currency in which the items' prices are listed. See ISO 4217.
        UploadMethod:
          type: string
          enum:
          - DIRECT_UPLOAD
          - IMPACT_RADIUS_FTP_SERVER
          - IR_SFTP
          - PULL_FROM_URL
          - SHOPPING_CART_PULL
          example: IR_SFTP
          description: How the catalog was uploaded (e.g., `DIRECT_UPLOAD`, `IR_SFTP`, `SHOPPING_CART_PULL`).
        ItemsUri:
          type: string
          format: uri-reference
          example: /Advertisers/<AccountSID>/Catalogs/99999/Items
          description: URI to view this catalog's items.
        Uri:
          type: string
          format: uri-reference
          example: /Advertisers/<AccountSID>/Catalogs/99999
          description: Direct URI to this catalog.
    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.
        CurrentPrice:
          type: number
          example: 29.99
          description: Current consumer price of the item.
        OriginalPrice:
          type: number
          example: 39.99
          description: Original consumer price of the item.
        Currency:
          type: string
          example: USD
          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`).
        Manufacturer:
          type: string
          description: The person or group that makes the item.
        Url:
          type: string
          description: URL that leads to the item's online store listing.
        ImageUrl:
          type: string
          description: URL that leads to the item's image.
        Category:
          type: string
          example: Sports
          description: Group or kind of products with which the item is associated.
        Condition:
          type: string
          description: Condition the item is in when sold (`New`, `Used`, `Refurbished`, `OEM`, `OpenBox`).
        Inventory:
          type: integer
          description: Item's inventory count.
        Uri:
          type: string
          format: uri-reference
          example: /Advertisers/<AccountSID>/Catalogs/<CatalogId>/Items/<CatalogItemId>
          description: URI that points directly to this catalog item.
    ItemResponse:
      type: object
      properties:
        Status:
          type: string
          example: OK
        Uri:
          type: string
x-default-client: cURL
