CreatorIQ Ecommerce API

openapi: 3.2.0
info:
  version: 1.0.0
  title: CreatorIQ Ecommerce API
  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
security:
- apiKey: []
tags:
- name: Ecommerce
  description: Ecommerce public API
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
components:
  schemas:
    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
    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'
    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
    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
    CoreExceptionResponse400:
      type: object
      properties:
        type:
          type: string
          examples:
          - CoreException
        CoreException:
          type: object
          properties:
            code:
              type: integer
              examples:
              - 400
            message:
              type: string
              examples:
              - Human readable text message.
          required:
          - code
          - message
      required:
      - type
      - CoreException
    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
    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
    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
    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
    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
    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
    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:
          - Test channel name
        DeclineReason:
          type:
          - string
          - 'null'
          description: Reason why order was declined.
          examples:
          - Test decline reason
        TransactionCurrency:
          type: string
          description: Currency of the transaction.
          examples:
          - USD
        SaleAmount:
          type:
          - number
          - 'null'
          description: Amount of the same.
          examples:
          - 25.15
        CommissionAmount:
          type:
          - number
          - 'null'
          description: Amount of the commission.
          examples:
          - 0.25
        Status:
          type: string
          description: Transaction status.
          examples:
          - Confirmed
        StatusUpdatedAt:
          type:
          - string
          - 'null'
          description: Last date when transaction status was updated.
          examples:
          - '2024-02-05 11:24:13'
        CouponCode:
          type:
          - string
          - 'null'
          description: Name of the promo-code applied.
          examples:
          - COUPON_CODE
        LastUpdate:
          type:
          - string
          - 'null'
          description: Date of the last data update of the transaction in the CreatorIQ platform.
          examples:
          - '2024-02-05 09:51:22.0000000'
        PublisherId:
          type: integer
          description: Publisher ID in the CreatorIQ platform.
          examples:
          - 123456
        CampaignId:
          type: integer
          description: Campaign ID in the CreatorIQ platform.
          examples:
          - 54321
        TrackingItemsPromotionId:
          type:
          - integer
          - 'null'
          description: TrackingItemsPromotionId ID in the CreatorIQ platform.
          examples:
          - 56457842
          x-deprecated: true
        TrackingItemId:
          type:
          - integer
          - 'null'
          description: TrackingItemId ID in the CreatorIQ platform.
          examples:
          - 56457842
        CiqPartnerId:
          type: integer
          description: ID of the partner in the CreatorIQ platform.
          examples:
          - 123
        CreatedAt:
          type: string
          description: Date when the data was collected first time to the CreatorIQ platform.
          examples:
          - '2024-02-05 09:51:22.0000000'
        ValidationDate:
          type:
          - string
          - 'null'
          description: After this Date the transaction becomes inaccessible for any further modifications or changes.
          examples:
          - '2024-02-05 09:51:22.0000000'
      required:
      - CiqTransactionId
      - NetworkTransactionId
      - NetworkName
      - NetworkAdvertiserId
      - AdvertiserName
      - OrderId
      - OrderCountry
      - TransactionDate
      - DeviceType
      - OsType
      - NetworkChannelId
      - Channel

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