CreatorIQ Ecommerce APIs

openapi: 3.1.0
info:
  version: 1.0.0
  title: CreatorIQ Ecommerce APIs
  description: CreatorIQ CRM APIs for Ecommerce resource
  termsOfService: 'https://www.creatoriq.com/legal/terms-of-use'
  contact:
    name: CreatorIQ
    url: 'https://www.creatoriq.com'
    email: support@creatoriq.com
  license:
    url: 'https://www.apache.org/licenses/LICENSE-2.0.html'
    name: Apache 2.0
servers:
  - url: 'https://apis.creatoriq.com'
    description: Live
paths:
  '/crm/v1/api/ecommerce/promo-codes/{id}':
    patch:
      tags:
        - Ecommerce
      summary: Update publisher promo code
      description: Update existing publisher promo code by ID. Unique identifier is PromoCodePublisherId which is unique ID of relation between PromoCodeId and PublisherId.
      operationId: patchEcommercePromo-codesId
      parameters:
        - name: id
          in: path
          description: Value of the PromoCodePublisherId
          required: true
          schema:
            type: integer
            examples:
              - 456
          examples:
            default:
              value: 456
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchPromoCodeBody'
      responses:
        '200':
          description: Response 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromoCodeModel'
        '400':
          description: Response 400 (Bad Request)
        '404':
          description: Response 404 (Not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromoCodeNotFoundResponse'
      security:
        - apiKey: []
      servers:
        - url: 'https://apis.creatoriq.com'
          description: Live
  /crm/v1/api/ecommerce/promo-codes/integrations:
    get:
      tags:
        - Ecommerce
      summary: Get integrations to add promo-code(s)
      description: 'Get active integrations list with at least 1 connected account. Note: in case of no connected accounts linked the list will be empty.'
      operationId: getEcommercePromo-codesIntegrations
      responses:
        '200':
          description: Response 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationsResponse'
      security:
        - apiKey: []
      servers:
        - url: 'https://apis.creatoriq.com'
          description: Live
  /crm/v1/api/ecommerce/integrations/accounts:
    get:
      tags:
        - Ecommerce
      summary: Get connected accounts list
      description: Get the list of all the connected accounts for AWIN and CJ integrations.
      operationId: getEcommerceIntegrationsAccounts
      responses:
        '200':
          description: Response 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectedPromoCodeAccountsResponse'
      security:
        - apiKey: []
      servers:
        - url: 'https://apis.creatoriq.com'
          description: Live
  '/crm/v1/api/ecommerce/promo-codes/{promoCodePublisherId}/publisher/{publisherId}':
    delete:
      tags:
        - Ecommerce
      summary: Delete publisher promo-code
      description: Delete promo code by PromoCodePublisherId and PublisherId. After adding promo-code with the same name the promo-codes entity ID i.e. PromoCodeId will not be changed. In case of successful deleting the promo-code empty body with 204 status code will be returned. Promo-code which already has commissions can not be deleted.
      operationId: deleteEcommercePromo-codesPromoCodePublisherIdPublisherPublisherId
      parameters:
        - name: promoCodePublisherId
          in: path
          description: Value of the PromoCodePublisherId
          required: true
          schema:
            type: integer
            examples:
              - 456
          examples:
            default:
              value: 456
        - name: publisherId
          in: path
          description: Value of the CreatorIQ PublisherId
          required: true
          schema:
            type: integer
            examples:
              - 123456
          examples:
            default:
              value: 123456
      responses:
        '204':
          description: Promo-code deleted successful response.
        '400':
          description: Error with deleting promo-code. For example it happens when the promo-code already has commissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletePromoCodesResponse400'
        '404':
          description: PromoCodePublisherId or PublisherId not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromoCodeNotFoundResponse'
      security:
        - apiKey: []
      servers:
        - url: 'https://apis.creatoriq.com'
          description: Live
  /crm/v1/api/ecommerce/promo-codes:
    post:
      tags:
        - Ecommerce
      summary: Create new promo-codes
      description: 'Create promo-codes, 10 items max allowed in 1 request. Different integrations and(or) publishers can be used in 1 request. Also if the integration is CJ and CreatorIQ publisher does not have CJ Promotional Property generated yet than the CJPID(CJ Promotional Property) will be generated using CJ API.'
      operationId: postEcommercePromo-codes
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostPromoCodesBody'
      responses:
        '200':
          description: Response 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePromoCodesResponse200'
        '400':
          description: Response 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePromoCodesResponse400'
      security:
        - apiKey: []
      servers:
        - url: 'https://apis.creatoriq.com'
          description: Live
    get:
      tags:
        - Ecommerce
      summary: Get promo-codes list
      description: Get list of all the promo-codes for all publishers in the network with pagination.
      operationId: getEcommercePromo-codes
      parameters:
        - name: Page
          in: query
          description: 1 by default if no parameter provided.
          required: false
          schema:
            type: integer
            examples:
              - 2
          examples:
            default:
              value: 2
        - name: PageSize
          in: query
          description: 20 by default if no parameter provided.
          required: false
          schema:
            type: integer
            examples:
              - 100
          examples:
            default:
              value: 100
      responses:
        '200':
          description: Response 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPromoCodesResponse'
      security:
        - apiKey: []
      servers:
        - url: 'https://apis.creatoriq.com'
          description: Live
  /crm/v1/api/ecommerce/transactions:
    get:
      tags:
        - Ecommerce
      summary: Get transactions
      description: Get network transactions of the all publishers. Every transaction ID is unique with latest status.
      operationId: getEcommerceTransactions
      parameters:
        - name: Page
          in: query
          description: 1 by default if no parameter provided.
          required: false
          schema:
            type: integer
            examples:
              - 2
          examples:
            default:
              value: 2
        - name: PageSize
          in: query
          description: 20 by default if no parameter provided.
          required: false
          schema:
            type: integer
            examples:
              - 100
          examples:
            default:
              value: 100
        - name: DateType
          in: query
          description: '"TransactionDate" by default if no parameter provided.'
          required: false
          schema:
            type: string
            enum:
              - TransactionDate
              - LastUpdate
            examples:
              - LastUpdate
          examples:
            default:
              value: LastUpdate
        - name: DateFrom
          in: query
          description: 'Two different formats accepted: "2024-02-16" or "2024-02-16 21:30:25".'
          required: false
          schema:
            type: string
            examples:
              - '2024-02-16'
          examples:
            default:
              value: '2024-02-16'
        - name: DateTo
          in: query
          description: 'Two different formats accepted: "2024-02-16" or "2024-02-16 21:30:25".'
          required: false
          schema:
            type: string
            examples:
              - '2024-02-16'
          examples:
            default:
              value: '2024-02-16'
        - name: Status
          in: query
          description: Transaction status.
          required: false
          schema:
            type: string
            examples:
              - approved
          examples:
            default:
              value: approved
        - name: TransactionId
          in: query
          description: Transaction ID.
          required: false
          schema:
            type: string
            examples:
              - asd8E05QYA31XmxF
          examples:
            default:
              value: asd8E05QYA31XmxF
        - name: CampaignId
          in: query
          description: Campaign ID in the CreatorIQ platform.
          required: false
          schema:
            type: integer
            examples:
              - 12345
          examples:
            default:
              value: 12345
        - name: PublisherId
          in: query
          description: Publisher ID in the CreatorIQ platform.
          required: false
          schema:
            type: integer
            examples:
              - 12345
          examples:
            default:
              value: 12345
        - name: OrderId
          in: query
          description: Id of the order.
          required: false
          schema:
            type: string
            examples:
              - '1234265934'
          examples:
            default:
              value: '1234265934'
      responses:
        '200':
          description: Response 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTransactionsResponse200'
        '400':
          description: Response 400 (Bad Request)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoreExceptionResponse400'
      security:
        - apiKey: []
      servers:
        - url: 'https://apis.creatoriq.com'
          description: Live
  /crm/v1/api/ecommerce/transactions/history:
    get:
      tags:
        - Ecommerce
      summary: Get transactions history
      description: 'Get network transactions list of the all publishers. Returns all the transactions history, Transaction ID is not unique.'
      operationId: getEcommerceTransactionsHistory
      parameters:
        - name: Page
          in: query
          description: 1 by default if no parameter provided.
          required: false
          schema:
            type: integer
            examples:
              - 2
          examples:
            default:
              value: 2
        - name: PageSize
          in: query
          description: 20 by default if no parameter provided.
          required: false
          schema:
            type: integer
            examples:
              - 100
          examples:
            default:
              value: 100
        - name: DateType
          in: query
          description: '"TransactionDate" by default if no parameter provided.'
          required: false
          schema:
            type: string
            enum:
              - TransactionDate
              - LastUpdate
            examples:
              - LastUpdate
          examples:
            default:
              value: LastUpdate
        - name: DateFrom
          in: query
          description: 'Two different formats accepted: "2024-02-16" or "2024-02-16 21:30:25".'
          required: false
          schema:
            type: string
            examples:
              - '2024-02-16'
          examples:
            default:
              value: '2024-02-16'
        - name: DateTo
          in: query
          description: 'Two different formats accepted: "2024-02-16" or "2024-02-16 21:30:25".'
          required: false
          schema:
            type: string
            examples:
              - '2024-02-16'
          examples:
            default:
              value: '2024-02-16'
        - name: Status
          in: query
          description: Status of the transaction.
          required: false
          schema:
            type: string
            examples:
              - approved
          examples:
            default:
              value: approved
        - name: TransactionId
          in: query
          description: ID of the transaction.
          required: false
          schema:
            type: string
            examples:
              - asd8E05QYA31XmxF
          examples:
            default:
              value: asd8E05QYA31XmxF
        - name: CampaignId
          in: query
          description: Campaign ID in the CreatorIQ platform.
          required: false
          schema:
            type: integer
            examples:
              - 12345
          examples:
            default:
              value: 12345
        - name: PublisherId
          in: query
          description: Publisher ID in the CreatorIQ platform.
          required: false
          schema:
            type: integer
            examples:
              - 12345
          examples:
            default:
              value: 12345
        - name: OrderId
          in: query
          description: Id of the order.
          required: false
          schema:
            type: string
            examples:
              - '1234265934'
          examples:
            default:
              value: '1234265934'
      responses:
        '200':
          description: Response 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTransactionsResponse200'
        '400':
          description: Response 400 (Bad Request)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoreExceptionResponse400'
      security:
        - apiKey: []
      servers:
        - url: 'https://apis.creatoriq.com'
          description: Live
tags:
  - name: Ecommerce
    description: Ecommerce public API
components:
  securitySchemes:
    apiKey:
      type: apiKey
      name: x-api-key
      in: header
  schemas:
    PatchPromoCodeBody:
      type: object
      properties:
        Instruction:
          type: string
          description: Description to the CreatorIQ publisher how to use the promo-code.
          examples:
            - promo-code instruction
        Percentage:
          type: number
          description: Percent of the discount. If we want to have discount 5.5% the value should be as is 5.5.
          examples:
            - 10.25
        StartDate:
          type: string
          description: Date from when the promo-code is active and the code can be applied.
          examples:
            - '2023-10-10 00:00:00'
        EndDate:
          type: string
          description: Date when the promo-code expires and it will not be applicable any more.
          examples:
            - '2023-10-10 23:59:59'
    PromoCodeModel:
      type: object
      properties:
        PromoCodeId:
          type: integer
          description: ID of the promo-code entity.
          examples:
            - 123
        PromoCodePublisherId:
          type: integer
          description: ID of the promo-code related to a specific publisher.
          examples:
            - 456
        PromoCodeName:
          type: string
          description: Name of the promo-code to apply in the external services.
          examples:
            - PROMO_CODE
        StartDate:
          type: string
          description: Date from when the promo-code is active and the code can be applied.
          examples:
            - '2023-10-10 23:59:59'
        EndDate:
          type:
            - string
            - 'null'
          description: Date when the promo-code expires and it will not be applicable any more.
          examples:
            - '2023-10-20 23:59:59'
        Percentage:
          type:
            - number
            - 'null'
          description: Percent of the discount. If we want to have discount 5.5% the value should be as is 5.5.
          format: float
          examples:
            - 10.25
        IntegrationName:
          type: string
          description: Name of the integration to which promo-code relates to.
          examples:
            - CJ
        PromotionalPropertyId:
          type:
            - integer
            - 'null'
          description: ID of the Promotional Property entity in the external integration.
          examples:
            - 101001234
        Instruction:
          type:
            - string
            - 'null'
          description: Description to the CreatorIQ publisher how to use the promo-code.
          examples:
            - Instruction example for the publisher.
      required:
        - PromoCodeId
        - PromoCodePublisherId
        - PromoCodeName
        - StartDate
        - EndDate
        - Percentage
        - IntegrationName
        - PromotionalPropertyId
        - Instruction
    PromoCodeNotFoundResponse:
      type: object
      properties:
        type:
          type: string
          examples:
            - CoreException
        CoreException:
          type: object
          properties:
            code:
              type: integer
              examples:
                - 404
            message:
              type: string
              examples:
                - Promo code not found
          required:
            - code
            - message
      required:
        - type
        - CoreException
    IntegrationsResponse:
      type: array
      items:
        type: object
        properties:
          Id:
            type: integer
            description: ID of the integration.
            examples:
              - 13
          Name:
            type: string
            description: 'Integration slug, should be used in the API requests.'
            examples:
              - impactSubAffiliate
          DisplayName:
            type: string
            description: This is how this integration will be named on the UI in the CreatorIQ application.
            examples:
              - Impact Sub-affiliate
        required:
          - Id
          - Name
          - DisplayName
    ConnectedPromoCodeAccountsResponse:
      type: object
      properties:
        Code:
          type: integer
          description: 'Status code. Available statuses: 200, 400.'
          examples:
            - 200
        Message:
          type: string
          description: User friendly message about status of the request.
          examples:
            - Connected Accounts list
        Status:
          type: string
          description: 'Status slug. Available statuses: OK.'
          examples:
            - OK
        Items:
          type: object
          properties:
            IntegrationName:
              type: string
              description: Name of the integration.
              examples:
                - CJ
            AccountConfigurationId:
              type: integer
              description: ID of the account configuration in the CreatorIQ platform.
              examples:
                - 13
            AccountDisplayName:
              type: string
              description: Name of the account.
              examples:
                - Test Account
          required:
            - IntegrationName
            - AccountConfigurationId
            - AccountDisplayName
      required:
        - Code
        - Message
        - Status
        - Items
    DeletePromoCodesResponse400:
      type: object
      properties:
        type:
          type: string
          examples:
            - CoreException
        CoreException:
          type: object
          properties:
            code:
              type: integer
              examples:
                - 400
            message:
              type: string
              examples:
                - Promo code already has transactions and it can't be deleted.
          required:
            - code
            - message
      required:
        - type
        - CoreException
    PostPromoCodesBody:
      type: object
      properties:
        Codes:
          type: array
          minItems: 1
          maxItems: 10
          items:
            type: object
            properties:
              Integration:
                type: string
                description: Slug of the active integration.
                examples:
                  - cj
              AccountConfigurationId:
                type: integer
                description: ID of the account configuration in the CreatorIQ platform.
                examples:
                  - 123456
              Code:
                type: string
                description: Name of the promo-code to apply in the external services.
                examples:
                  - PROMO_CODE
              Percentage:
                type: number
                description: Percent of the discount. If we want to have discount 5.5% the value should be as is 5.5.
                examples:
                  - 10.25
              StartDate:
                type: string
                description: Date from when the promo-code is active and the code can be applied.
                examples:
                  - '2023-10-10 00:00:00'
              EndDate:
                type: string
                description: Date when the promo-code expires and it will not be applicable any more.
                examples:
                  - '2023-11-10 23:59:59'
              Instruction:
                type:
                  - string
                  - 'null'
                description: Description to the CreatorIQ publisher how to use the promo-code.
                examples:
                  - promo-code instruction for the specific publisher.
              PublisherId:
                type: integer
                description: PublisherId in the CreatorIQ platform.
                examples:
                  - 123456
            required:
              - Integration
              - AccountConfigurationId
              - Code
              - Percentage
              - StartDate
              - PublisherId
      required:
        - Codes
    CreatePromoCodesResponse200:
      type: object
      properties:
        Code:
          type: integer
          description: 'Status code of creating all the promo-codes. Available statuses: 200, 400.'
          examples:
            - 200
        Message:
          type: string
          description: User friendly message about status of the request.
          examples:
            - Promo codes created
        Status:
          type: string
          description: 'Status slug regarding creating the promo-code. Available statuses: CREATED or INVALID_ARGUMENT.'
          examples:
            - CREATED
        Codes:
          type: object
          properties:
            Items:
              type: array
              minItems: 1
              items:
                $ref: '#/components/schemas/PromoCodeModel'
      required:
        - Code
        - Message
        - Status
        - Codes
    CreatePromoCodesResponse400:
      type: object
      properties:
        Code:
          type: integer
          examples:
            - 400
        Message:
          type: string
          examples:
            - Some of items are invalid
        Status:
          type: string
          examples:
            - INVALID_ARGUMENT
        Codes:
          type: object
          properties:
            Errors:
              type: array
              minItems: 1
              items:
                type: object
                properties:
                  Item:
                    type: object
                    properties:
                      Integration:
                        type: string
                        examples:
                          - cj
                      Code:
                        type: string
                        examples:
                          - PROMO_CODE
                      Percentage:
                        type:
                          - number
                          - 'null'
                        format: float
                        examples:
                          - 10.25
                      StartDate:
                        type: string
                        examples:
                          - '2023-10-10 23:59:59'
                      EndDate:
                        type:
                          - string
                          - 'null'
                        examples:
                          - '2023-10-20 23:59:59'
                      Instruction:
                        type:
                          - string
                          - 'null'
                        examples:
                          - Text instructions for publisher.
                      PublisherId:
                        type: integer
                        examples:
                          - 9876543
                    required:
                      - Integration
                      - Code
                      - Percentage
                      - StartDate
                      - EndDate
                      - Instruction
                      - PublisherId
                  Errors:
                    type: array
                    minItems: 1
                    items:
                      $ref: '#/components/schemas/PromoCodeErrorModel'
          required:
            - Errors
      required:
        - Code
        - Message
        - Status
        - Codes
    PromoCodeErrorModel:
      type: object
      properties:
        Type:
          type: string
          description: 'Slug name of the error. Available values: ValidationError, DataError, CJAPIError. CJAPIError happens when the CJ API returns unexpected response, for example 500 or 502 status code.'
          examples:
            - ValidationError
        Code:
          type: integer
          description: 'Error code, for now always 0.'
          examples:
            - 0
        Field:
          type: string
          description: Field name where error happened. For example in case of invalid format of the StartDate provided the value will be StartDate.
          examples:
            - Code
        Path:
          type: string
          description: Path to the item where error happened. For example for the 3th item with error in StartDate the value will be Codes.2.StartDate
          examples:
            - Codes.0.Code
        Reason:
          type: string
          description: Human readable error why and where error happened
          examples:
            - CJ Promo-code PROMO_CODE already exists for this configuration.
      required:
        - Type
        - Code
        - Field
        - Path
        - Reason
    GetPromoCodesResponse:
      type: object
      properties:
        count:
          type: integer
          description: Count of all the items.
          examples:
            - 527
        page:
          type: integer
          description: Page number.
          examples:
            - 1
        size:
          type: integer
          description: Page size.
          examples:
            - 20
        Code:
          type: integer
          description: 'Status code of creating all the promo-codes. Available statuses: 200, 400.'
          examples:
            - 200
        Message:
          type: string
          description: User friendly message about status of the request.
          examples:
            - Promo codes list
        Status:
          type: string
          description: 'Status slug regarding creating the promo-code. Available statuses: CREATED or INVALID_ARGUMENT.'
          examples:
            - OK
        Items:
          type: array
          items:
            $ref: '#/components/schemas/PromoCodeListItem'
      required:
        - count
        - page
        - size
        - Code
        - Message
        - Status
        - Items
    PromoCodeListItem:
      type: object
      properties:
        PromoCodePublisherId:
          type: integer
          description: ID of the promo-code in the CreatorIQ platform.
          examples:
            - 456
        PublisherId:
          type: integer
          description: ID of the publisher in the CreatorIQ platform.
          examples:
            - 123
        PromoCodeName:
          type: string
          description: Name of the promo-code.
          examples:
            - PROMO_CODE
        IntegrationName:
          type: string
          description: Name of the integration to which promo-code relates to.
          examples:
            - CJ
        PublisherName:
          type: string
          description: Name of the publisher in the CreatorIQ platform.
          examples:
            - Test
      required:
        - PromoCodePublisherId
        - PublisherId
        - PromoCodeName
        - IntegrationName
        - PublisherName
    GetTransactionsResponse200:
      type: object
      properties:
        count:
          type: integer
          description: Count of all the items.
          examples:
            - 527
        page:
          type: integer
          description: Page number.
          examples:
            - 1
        size:
          type: integer
          description: Page size.
          examples:
            - 20
        data:
          type: array
          items:
            $ref: '#/components/schemas/TransactionModel'
      required:
        - count
        - page
        - size
        - data
    TransactionModel:
      type: object
      properties:
        CiqTransactionId:
          type: string
          description: ID of the transaction.
          examples:
            - c36ce8feXYqlk81
        NetworkTransactionId:
          type: string
          description: ID of the network transaction.
          examples:
            - '1234544145'
        NetworkName:
          type: string
          description: Name of the network.
          examples:
            - Rakuten Advertising
        NetworkAdvertiserId:
          type: string
          description: Network advertiser ID.
          examples:
            - Asdob36a
        AdvertiserName:
          type: string
          description: Advertiser name.
          examples:
            - Test advertiser
        OrderId:
          type: string
          description: Id of the order.
          examples:
            - '1234499551'
        OrderCountry:
          type: string
          description: Country of the customer who made the order.
          examples:
            - TH
        TransactionDate:
          type: string
          description: Date of the transaction.
          examples:
            - '2024-02-05 11:24:13'
        DeviceType:
          type:
            - string
            - 'null'
          description: Type of the device.
          examples:
            - Smartphone
        OsType:
          type:
            - string
            - 'null'
          description: Operating system name.
          examples:
            - iOS
        NetworkChannelId:
          type:
            - string
            - 'null'
          description: Network channel ID.
          examples:
            - Q5f1nY51
        ChannelName:
          type:
            - string
            - 'null'
          description: Name of the channel.
          examples:
       

# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/creatoriq/refs/heads/main/openapi/creatoriq-ecommerce-openapi.yml