Criteo Balance API

openapi: 3.2.0
info:
  title: Criteo Balance API
  description: Criteo API - RetailMedia
  version: 2026-07
servers:
- url: https://api.criteo.com
security:
- oauth: []
tags:
- name: Balance
paths:
  /2026-07/retail-media/accounts/{account-id}/balances:
    post:
      tags:
      - Balance
      summary: /2026-07/retail-media/accounts/{account-id}/balances
      description: Create balance for the given account id
      operationId: CreateBalanceByAccountId
      parameters:
      - name: account-id
        in: path
        description: The account to create balances for
        required: true
        schema:
          type: string
      requestBody:
        description: An object that represents the available options to set when creating a Retail Media Balance
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBalanceV3Request'
        required: true
        x-bodyName: createBalance
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceResponseV3Response'
      security:
      - oauth:
        - RetailMedia_Balance_Manage
  /2026-07/retail-media/accounts/{account-id}/balances/{balance-id}:
    patch:
      tags:
      - Balance
      summary: /2026-07/retail-media/accounts/{account-id}/balances/{balance-id}
      description: Modify a balance for the given account id
      operationId: UpdateBalanceV1
      parameters:
      - name: account-id
        in: path
        description: The account of the balance
        required: true
        schema:
          type: string
      - name: balance-id
        in: path
        description: The balance to change the dates
        required: true
        schema:
          type: string
      requestBody:
        description: An object that represents the available options to modify a balance.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValueResourceInputOfUpdateBalanceModelV1'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityResourceOutcomeOfBalanceResponseV1'
      security:
      - oauth:
        - RetailMedia_Balance_Manage
    get:
      tags:
      - Balance
      summary: /2026-07/retail-media/accounts/{account-id}/balances/{balance-id}
      description: Get a balance for the given account id and balance id
      operationId: GetBalanceByAccountAndBalanceId
      parameters:
      - name: account-id
        in: path
        description: The account of the balance
        required: true
        schema:
          type: string
      - name: balance-id
        in: path
        description: The balance id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceResponseV2Response'
      security:
      - oauth:
        - RetailMedia_Balance_Read
  /2026-07/retail-media/accounts/{account-id}/balances/{balance-id}/add-funds:
    post:
      tags:
      - Balance
      summary: /2026-07/retail-media/accounts/{account-id}/balances/{balance-id}/add-funds
      description: Add funds to a balance for the given account id
      operationId: AddFundsByAccountAndBalanceId
      parameters:
      - name: account-id
        in: path
        description: The account of the balance
        required: true
        schema:
          type: string
      - name: balance-id
        in: path
        description: The balance to add funds to
        required: true
        schema:
          type: string
      requestBody:
        description: An object that represents the available options of adding funds to a balance.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddFundsToBalanceV3Request'
        required: true
        x-bodyName: addFundsToBalance
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceResponseV3Response'
      security:
      - oauth:
        - RetailMedia_Balance_Manage
  /2026-07/retail-media/accounts/{account-id}/balances/{balance-id}/change-dates:
    post:
      tags:
      - Balance
      summary: /2026-07/retail-media/accounts/{account-id}/balances/{balance-id}/change-dates
      description: Change dates of a balance for the given account id
      operationId: ChangeDatesByAccountAndBalanceId
      parameters:
      - name: account-id
        in: path
        description: The account of the balance
        required: true
        schema:
          type: string
      - name: balance-id
        in: path
        description: The balance to change the dates
        required: true
        schema:
          type: string
      requestBody:
        description: An object that represents the available options to modify schedule of a balance.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeDatesOfBalanceV2Request'
        required: true
        x-bodyName: changeDatesOfBalance
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceResponseV2Response'
      security:
      - oauth:
        - RetailMedia_Balance_Manage
  /2026-07/retail-media/accounts/{accountId}/balances:
    get:
      tags:
      - Balance
      summary: /2026-07/retail-media/accounts/{accountId}/balances
      description: Gets page of balance objects for the given account id.
      operationId: GetPageOfBalancesV1
      parameters:
      - name: accountId
        in: path
        description: The account to get balances for.
        required: true
        schema:
          type: string
      - name: limit
        in: query
        description: The number of elements to be returned.
        schema:
          maximum: 500
          minimum: 1
          type: integer
          format: int32
          default: 25
      - name: limit-to-id
        in: query
        description: The balance ids which the result is limited to.
        schema:
          maxItems: 50
          type: array
          items:
            type: string
      - name: offset
        in: query
        description: The (zero-based) starting offset in the collection.
        schema:
          maximum: 2147483647
          minimum: 0
          type: integer
          format: int32
          default: 0
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityResourceCollectionOutcomeBalanceV1AndMetadata'
      security:
      - oauth:
        - RetailMedia_Balance_Read
  /2026-07/retail-media/balances/{balance-id}/campaigns:
    get:
      tags:
      - Balance
      summary: /2026-07/retail-media/balances/{balance-id}/campaigns
      description: Gets page of campaigns for the given balanceId
      operationId: GetCampaignsByBalanceId
      parameters:
      - name: balance-id
        in: path
        description: The balance to get campaigns from
        required: true
        schema:
          type: string
      - name: limitToId
        in: query
        description: The ids that you would like to limit your result set to
        schema:
          type: array
          items:
            type: string
      - name: pageIndex
        in: query
        description: The 0 indexed page index you would like to receive given the page size
        schema:
          maximum: 2147483647
          minimum: 0
          type: integer
          format: int32
          default: 0
      - name: pageSize
        in: query
        description: The maximum number of items you would like to receive in this request
        schema:
          maximum: 2147483647
          minimum: 1
          type: integer
          format: int32
          default: 25
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceCampaign202110PagedListResponse'
      security:
      - oauth:
        - RetailMedia_Balance_Read
  /2026-07/retail-media/balances/{balanceId}:
    get:
      tags:
      - Balance
      summary: /2026-07/retail-media/balances/{balanceId}
      description: Get a balance for the given balance id.
      operationId: GetBalanceV1
      parameters:
      - name: balanceId
        in: path
        description: The balance id.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityResourceOutcomeBalanceV1'
      security:
      - oauth:
        - RetailMedia_Balance_Read
  /2026-07/retail-media/balances/{balanceId}/history:
    get:
      tags:
      - Balance
      summary: /2026-07/retail-media/balances/{balanceId}/history
      description: Gets the balance's historical change data.
      operationId: GetBalanceHistoryV1
      parameters:
      - name: balanceId
        in: path
        description: Balance id.
        required: true
        schema:
          type: string
      - name: limit
        in: query
        description: The number of elements to be returned.
        schema:
          maximum: 500
          minimum: 1
          type: integer
          format: int32
          default: 25
      - name: limitToChangeTypes
        in: query
        description: Comma separated change types string that will be queried.
        schema:
          type: string
      - name: offset
        in: query
        description: The (zero-based) starting offset in the collection.
        schema:
          maximum: 2147483647
          minimum: 0
          type: integer
          format: int32
          default: 0
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValueResourceCollectionOutcomeBalanceHistoryChangeDataCaptureV1AndMetadata'
      security:
      - oauth:
        - RetailMedia_Balance_Read
components:
  schemas:
    CommonProblem:
      type: object
      properties:
        code:
          type:
          - string
          - 'null'
          description: A machine-readable error code, expressed as a string value.
        detail:
          type:
          - string
          - 'null'
          description: A human-readable explanation specific to this occurrence of the problem
        instance:
          type:
          - string
          - 'null'
          description: A URI that identifies the specific occurrence of the problem.
        source:
          type:
          - object
          - 'null'
          additionalProperties:
            type: string
          description: A machine-readable structure to reference to the exact location(s) causing the error(s)
        stackTrace:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
          description: A short human-readable description of the problem type
        traceId:
          type:
          - string
          - 'null'
          description: The request correlation ID this problem comes from.
        traceIdentifier:
          type:
          - string
          - 'null'
          description: The request correlation ID this problem comes from. (deprecated, use traceId instead)
        type:
          enum:
          - unknown
          - access-control
          - authentication
          - authorization
          - availability
          - deprecation
          - quota
          - validation
          type:
          - string
          - 'null'
          description: The problem's category.
      description: Common problem object.
    ChangeDatesOfBalanceV2:
      type: object
      properties:
        endDate:
          type: string
          description: End date of the balance in the format YYYY-MM-DD.
        memo:
          type: string
          description: Memo.
        startDate:
          type: string
          description: Start date of the balance in the format YYYY-MM-DD.
      description: An object that represents the available options to modify schedule of a balance.
    BalanceResponseV3Response:
      type:
      - object
      - 'null'
      properties:
        data:
          $ref: '#/components/schemas/ResourceOfBalanceResponseV3'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/CommonProblem'
          readOnly: true
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/CommonProblem'
          readOnly: true
      description: A top-level object that encapsulates a Criteo API response for a single entity
    BalanceCampaign202110PagedListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ResourceOfBalanceCampaign202110'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/CommonProblem'
          readOnly: true
        metadata:
          $ref: '#/components/schemas/PageMetadata'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/CommonProblem'
          readOnly: true
      description: Data model for a paged list of response resources
    PageMetadata:
      required:
      - currentPageIndex
      - currentPageSize
      type: object
      properties:
        currentPageIndex:
          type: integer
          format: int32
        currentPageSize:
          type: integer
          format: int32
        nextPage:
          type:
          - string
          - 'null'
        previousPage:
          type:
          - string
          - 'null'
        totalItemsAcrossAllPages:
          type:
          - integer
          - 'null'
          format: int64
        totalPages:
          type:
          - integer
          - 'null'
          format: int64
      additionalProperties: false
      description: Metadata related to the current request
    ChangeDetailsV1:
      type: object
      properties:
        changeValue:
          type:
          - string
          - 'null'
          description: Change amount of a property of the insertion order.
        currentValue:
          type:
          - string
          - 'null'
          description: Current value of a property of the insertion order.
        previousValue:
          type:
          - string
          - 'null'
          description: Previous value of a property of the insertion order.
      additionalProperties: false
      description: Change details of a property of the balance.
    EntityResourceOfBalanceResponseV1:
      type:
      - object
      - 'null'
      properties:
        attributes:
          $ref: '#/components/schemas/BalanceResponseV1'
        id:
          type:
          - string
          - 'null'
          description: Unique id of the entity.
        type:
          type:
          - string
          - 'null'
          description: Type of the resource.
      additionalProperties: false
      description: A domain entity exposed by the API, identified by a unique id.
    BalanceResponseV3:
      required:
      - name
      - startDate
      - balanceType
      - spendType
      - privateMarketBillingType
      type:
      - object
      - 'null'
      properties:
        balanceType:
          enum:
          - unknown
          - capped
          - uncapped
          type: string
          description: Type of the balance.
        createdAt:
          type: string
          description: Creation time of the balance.
          format: date-time
        deposited:
          type:
          - number
          - 'null'
          description: Amount of billable funds allotted to the balance.
          format: double
        endDate:
          type:
          - string
          - 'null'
          description: End date of the balance in the format YYYY-MM-DD.
        memo:
          type:
          - string
          - 'null'
          description: Memo.
        name:
          type: string
          description: Name of the balance.
        privateMarketBillingType:
          enum:
          - notApplicable
          - billByRetailer
          - billByCriteo
          - unknown
          type: string
          description: Billing type for Private Market of the balance.
        remaining:
          type:
          - number
          - 'null'
          description: Amount of remaining funds of the balance.
          format: double
        retailerPoNumber:
          type:
          - string
          - 'null'
          description: Purchase Order number.
        spendType:
          enum:
          - Onsite
          - Offsite
          - OffsiteAwareness
          type: string
          description: Spend Type of the balance.
        spent:
          type:
          - number
          - 'null'
          description: Amount of spent funds of the balance.
          format: double
        startDate:
          type: string
          description: Start date of the balance in the format YYYY-MM-DD.
        status:
          enum:
          - unknown
          - scheduled
          - active
          - ended
          type: string
          description: Status of the balance.
        updatedAt:
          type: string
          description: Update time of the balance.
          format: date-time
      description: A Retail Media Balance used to determine the funds available for any or all campaigns in an account
    EntityResourceCollectionOutcomeBalanceV1AndMetadata:
      type: object
      properties:
        data:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/EntityResourceBalanceV1'
        errors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/SdkApiRestCommonProblem'
          description: Errors that occured during this call.
          readOnly: true
        metadata:
          $ref: '#/components/schemas/Metadata'
        warnings:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/SdkApiRestCommonProblem'
          description: Warnings that occured during this call.
          readOnly: true
      additionalProperties: false
      description: A top-level object that encapsulates a Criteo API response for several entities and metadata.
    ResourceOfCreateBalanceV3:
      type: object
      properties:
        attributes:
          $ref: '#/components/schemas/CreateBalanceV3'
        id:
          type: string
          description: Id of the entity
        type:
          type: string
          description: Canonical type name of the entity
      description: A class that represents a domain entity exposed by an API
    ResourceOfAddFundsToBalanceV3:
      type: object
      properties:
        attributes:
          $ref: '#/components/schemas/AddFundsToBalanceV3'
        id:
          type: string
          description: Id of the entity
        type:
          type: string
          description: Canonical type name of the entity
      description: A class that represents a domain entity exposed by an API
    ValueResourceBalanceHistoryChangeDataCaptureV1:
      type: object
      properties:
        attributes:
          $ref: '#/components/schemas/BalanceHistoryChangeDataCaptureV1'
        type:
          type:
          - string
          - 'null'
          description: Type of the resource.
      additionalProperties: false
      description: A value resource exposed by the API.
    EntityResourceOutcomeOfBalanceResponseV1:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/EntityResourceOfBalanceResponseV1'
        errors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/SdkApiRestCommonProblem'
          description: Errors that occured during this call.
          readOnly: true
        warnings:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/SdkApiRestCommonProblem'
          description: Warnings that occured during this call.
          readOnly: true
      additionalProperties: false
      description: A top-level object that encapsulates a Criteo API response for a single entity.
    AddFundsToBalanceV3:
      required:
      - deltaAmount
      type: object
      properties:
        deltaAmount:
          type: number
          description: Amount of billable funds to be added / decreased allotted to the balance.
          format: double
        memo:
          type: string
          description: Memo
        retailerPoNumber:
          type: string
          description: Purchase Order number.
      description: An object that represents the available options of adding funds to a balance.
    BalanceResponseV2:
      required:
      - name
      - startDate
      - balanceType
      - spendType
      - privateMarketBillingType
      type:
      - object
      - 'null'
      properties:
        balanceType:
          enum:
          - unknown
          - capped
          - uncapped
          type: string
          description: Type of the balance.
        createdAt:
          type: string
          description: Creation time of the balance.
          format: date-time
        deposited:
          type:
          - number
          - 'null'
          description: Amount of billable funds allotted to the balance.
          format: double
        endDate:
          type:
          - string
          - 'null'
          description: End date of the balance in the format YYYY-MM-DD.
        memo:
          type:
          - string
          - 'null'
          description: Memo.
        name:
          type: string
          description: Name of the balance.
        poNumber:
          type:
          - string
          - 'null'
          description: Purchase Order number.
        privateMarketBillingType:
          enum:
          - notApplicable
          - billByRetailer
          - billByCriteo
          - unknown
          type: string
          description: Billing type for Private Market of the balance.
        remaining:
          type:
          - number
          - 'null'
          description: Amount of remaining funds of the balance.
          format: double
        spendType:
          enum:
          - Onsite
          - Offsite
          - OffsiteAwareness
          type: string
          description: Spend Type of the balance.
        spent:
          type:
          - number
          - 'null'
          description: Amount of spent funds of the balance.
          format: double
        startDate:
          type: string
          description: Start date of the balance in the format YYYY-MM-DD.
        status:
          enum:
          - unknown
          - scheduled
          - active
          - ended
          type: string
          description: Status of the balance.
        updatedAt:
          type: string
          description: Update time of the balance.
          format: date-time
      description: A Retail Media Balance used to determine the funds available for any or all campaigns in an account
    UpdateBalanceModelV1:
      type: object
      properties:
        endDate:
          $ref: '#/components/schemas/NillableOfNullableOfDateOnly'
        memo:
          type:
          - string
          - 'null'
          description: Memo.
        name:
          type:
          - string
          - 'null'
          description: Name of the balance.
        retailerPoNumber:
          type:
          - string
          - 'null'
          description: Purchase Order number.
        startDate:
          type:
          - string
          - 'null'
          description: Start date of the balance in the format YYYY-MM-DD.
      additionalProperties: false
      description: An object that represents the available options to set when updating a Retail Media Balance.
    BalanceResponseV2Response:
      type:
      - object
      - 'null'
      properties:
        data:
          $ref: '#/components/schemas/ResourceOfBalanceResponseV2'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/CommonProblem'
          readOnly: true
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/CommonProblem'
          readOnly: true
      description: A top-level object that encapsulates a Criteo API response for a single entity
    ValueResourceInputOfUpdateBalanceModelV1:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ValueResourceOfUpdateBalanceModelV1'
      additionalProperties: false
      description: A top-level object that encapsulates a Criteo API request for a single value object.
    NillableOfNullableOfDateOnly:
      type:
      - object
      - 'null'
      properties:
        value:
          type:
          - string
          - 'null'
          description: Underlying actual value
      additionalProperties: false
      description: represents a value that can be set to null explicitly
    EntityResourceOutcomeBalanceV1:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/EntityResourceBalanceV1'
        errors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/SdkApiRestCommonProblem'
          description: Errors that occured during this call.
          readOnly: true
        warnings:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/SdkApiRestCommonProblem'
          description: Warnings that occured during this call.
          readOnly: true
      additionalProperties: false
      description: A top-level object that encapsulates a Criteo API response for a single entity.
    ResourceOfBalanceCampaign202110:
      type: object
      properties:
        attributes:
          $ref: '#/components/schemas/BalanceCampaign202110'
        id:
          type:
          - string
          - 'null'
          description: Id of the entity
        type:
          type:
          - string
          - 'null'
          description: Canonical type name of the entity
      description: A class that represents a domain entity exposed by an API
    BalanceResponseV1:
      required:
      - balanceType
      - createdAt
      - deposited
      - endDate
      - memo
      - name
      - privateMarketBillingType
      - remaining
      - retailerPoNumber
      - spendType
      - spent
      - startDate
      - status
      - updatedAt
      type:
      - object
      - 'null'
      properties:
        balanceType:
          enum:
          - unknown
          - capped
          - uncapped
          type: string
          description: Type of the balance.
        createdAt:
          type: string
          description: Creation time of the balance.
          format: date-time
        deposited:
          type:
          - number
          - 'null'
          description: Amount of billable funds allotted to the balance.
          format: double
        endDate:
          type:
          - string
          - 'null'
          description: End date of the balance in the format YYYY-MM-DD.
        memo:
          type:
          - string
          - 'null'
          description: Memo.
        name:
          type: string
          description: Name of the balance.
        privateMarketBillingType:
          enum:
          - notApplicable
          - billByRetailer
          - billByCriteo
          - unknown
          type: string
          description: Billing type for Private Market of the balance.
        remaining:
          type:
          - number
          - 'null'
          description: Amount of remaining funds of the balance.
          format: double
        retailerPoNumber:
          type:
          - string
          - 'null'
          description: Purchase Order number.
        spendType:
          enum:
          - unknown
          - onsite
          - offsite
          - offsiteAwareness
          type: string
          description: Spend Type of the balance.
        spent:
          type:
          - number
          - 'null'
          description: Amount of spent funds of the balance.
          format: double
        startDate:
          type: string
          description: Start date of the balance in the format YYYY-MM-DD.
        status:
          enum:
          - unknown
          - scheduled
          - active
          - ended
          type: string
          description: Status of the balance.
        updatedAt:
          type: string
          description: Update time of the balance.
          format: date-time
      additionalProperties: false
      description: A Retail Media Balance used to determine the funds available for any or all campaigns in an account
    Metadata:
      required:
      - limit
      - offset
      type:
      - object
      - 'null'
      properties:
        count:
          type:
          - integer
          - 'null'
          format: int64
        limit:
          type: integer
          description: The number of elements to be returned.
          format: int32
        offset:
          type: integer
          description: The (zero-based) starting offset in the collection.
          format: int32
      additionalProperties: false
      description: Metadata related to the current request.
    BalanceV1:
      required:
      - balanceType
      - createdAt
      - deposited
      - name
      - privateMarketBillingType
      - remaining
      - spendType
      - spent
      - startDate
      - status
      - updatedAt
      type:
      - object
      - 'null'
      properties:
        balanceType:
          enum:
          - unknown
          - capped
          - uncapped
          type: string
          description: Type of the balance.
        createdAt:
          type: string
          description: Creation time of the balance.
          format: date-time
        criteoPoNumber:
          type:
          - string
          - 'null'
          description: Criteo purchase order number.
        deposited:
          type: number
          description: Amount of billable funds allotted to the balance.
          format: double
        endDate:
          type:
          - string
          - 'null'
          description: End date of the balance in the format YYYY-MM-DD.
        memo:
          type:
          - string
          - 'null'
          description: Memo.
        name:
          type: string
          description: Name of the balance.
        privateMarketBillingType:
          enum:
          - notApplicable
          - billByRetailer
          - billByCriteo
          - unknown
          type: string
          description: Billing type for Private Market of the balance.
        remaining:
          type: number
          description: Amount of remaining funds of the balance.
          format: double
        retailerId:
          type:
          - string
          - 'null'
          description: The billing retailer id.
        retailerPoNumber:
          type:
          - string
          - 'null'
          description: Retailer purchase order number.
        spendType:
          enum:
          - onsite
          - offsite
          - offsiteAwareness
          - lockout
          - unknown
          type: string
          description: Spend Type of the balance.
        spent:
          type: number
          description: Amount of spent funds of the balance.
          format: double
        startDate:
          type: string
          description: Start date of the balance in the format YYYY-MM-DD.
        status:
          enum:
          - unknown
          - scheduled
          - active
          - ended
          type: string
          description: S

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