Discard
GuidesAPI ReferenceChangelogDiscussions
GuidesAPI ReferenceChangelogDiscussionsLog In

Balance endpoints

  • A balance represents funds the account can allocate towards campaigns
  • Campaigns must be assigned to spend from at least one balance to serve
  • Balances offer an additional lever to manage budgets in addition to controls at the campaign or line item level
  • Balances are read-only through the API - creation is limited to Admins or Business Managers through your account portal
  • Learn more about balances

Endpoints

  • GET /accounts/{accountId}/balances Get All Balances
  • GET /balances/{balanceId}/campaigns Get All Campaigns on a Specific Balance
  • PUT /balances/{balanceId}/campaigns Add Campaigns to a Specific Balance
  • DELETE /balances/{balanceId}/campaigns Remove Campaigns from a Specific Balance

Request Body Parameters

Parameter

Description

Values

Required

id string

Campaign ID to which balance should be appended or deleted from

int64

Required for POST requests

Balance Response Attributes

Attribute

Description

Values

id string

Balance ID

int64

name string

Balance name

poNumber string

Purchase order number

memo string

Memo

deposited number

Amount of funds deposited, uncapped if null

minimum value must be at least 0

spent number

Amount of funds already spent

minimum value must be at least 0

remaining number

Amount of funds remaining until cap is hit, null if not set

between 0 and deposited

startDate date

Balance start date in the account timeZone

YYYY-MM-DD

endDate date

Balance end date in the account timeZone; available indefinitely if null

YYYY-MM-DD

status enum

Balance status

active, scheduled, ended

createdAt timestamp

Timestamp in UTC of balance creation

ISO-8601

updatedAt timestamp

Timestamp in UTC of last balance update

ISO-8601

Get All Balances

This endpoint lists all balances in an account. Response results will be provided in paginated form.

https://api.criteo.com/2022-04/retail-media/accounts/{accountId}/balances

Sample Request

curl -X GET "https://api.criteo.com/2022-04/retail-media/accounts/18446744073709551616/balances" \
    -H "Authorization: Bearer myaccesstoken"

Sample Response

{
    "data": [
        {
            "type": "RetailMediaBalance",
            "id": "14094543095747588032",
            "attributes": {
                "name": "Balance 123",
                "poNumber": "13993827",
                "memo": "uncapped balance, free to spend!",
                "deposited": null,
                "spent": 42931.28,
                "remaining": null,
                "startDate": "2020-04-06",
                "endDate": null,
                "status": "active",
                "createdAt": "2020-04-06T00:02:41+00:00",
                "updatedAt": "2020-04-06T00:02:41+00:00"    
            }
        },
 
        // ...
 
        {
            "type": "RetailMediaBalance",          
            "id": "4237496305219757554",
            "attributes": {
                "name": "Balance 789",
                "poNumber": null,
                "memo": "10k for the special 2s-day promotion",
                "deposited": 10000.00,
                "spent": 0.00,
                "remaining": 10000.00,
                "startDate": "2222-02-22",
                "endDate": null,
                "status": "scheduled",
                "createdAt": "2020-04-06T00:48:11+00:00",
                "updatedAt": "2020-04-07T22:19:57+00:00"
            }
        }
    ],
    "metadata": {
        "totalItemsAcrossAllPages": 3,
        "currentPageSize": 25,
        "currentPageIndex": 0,
        "totalPages": 1,
        "nextPage": null,
        "previousPage": null
    }
}

Add Campaigns to a Specific Balance

This endpoint adds one or more campaigns to the specified balance. The resulting state of the balance is returned as a single page. In this example, a campaign had already existed on the balance before two new additions.

https://api.criteo.com/2021-10/retail-media//balances/{balanceId}/campaigns/append

Sample Request

curl -X GET "https://api.criteo.com/2022-04/retail-media/balances/14094543095747588032/campaigns/append" \
    -H "Authorization: Bearer myaccesstoken" \
    -H "Content-Type: application/json" \
    -d '{
            "data": [
                {
                    "type": "RetailMediaCampaign",
                    "id": "3683145960016759663"
                },
                {
                    "type": "RetailMediaCampaign",
                    "id": "16108177282234788969"
                }
            ]
        }'

Sample Response

{
    "data": [
        {
            "type": "RetailMediaCampaign",
            "id": "8343086999167541140"
        },
        {
            "type": "RetailMediaCampaign",
            "id": "3683145960016759663"
        },
        {
            "type": "RetailMediaCampaign",
            "id": "16108177282234788969"
        }
    ],
    "metadata": {
        "totalItemsAcrossAllPages": 3,
        "currentPageSize": 3,
        "currentPageIndex": 0,
        "totalPages": 1,
        "nextPage": null,
        "previousPage": null
    }
}

Remove Campaigns from a Specific Balance

This endpoint removes one or more campaigns from the specified balance. The resulting state of the balance is returned as a single page.

https://api.criteo.com/2022-04/retail-media/balances/{balanceId}/campaigns/delete

Sample Request

curl -X POST "https://api.criteo.com/2022-04/retail-media/balances/14094543095747588032/campaigns/delete" \
    -H "Authorization: Bearer myaccesstoken" \
    -H "Content-Type: application/json" \
    -d '{
            "data": [
                {
                    "type": "RetailMediaCampaign",
                    "id": "16108177282234788969"
                }
            ]
        }'

Sample Response

{
    "data": [
        {
            "type": "RetailMediaCampaign",
            "id": "8343086999167541140"
        },
        {
            "type": "RetailMediaCampaign",
            "id": "3683145960016759663"
        }
    ],
    "metadata": {
        "totalItemsAcrossAllPages": 2,
        "currentPageSize": 2,
        "currentPageIndex": 0,
        "totalPages": 1,
        "nextPage": null,
        "previousPage": null
    }
}

Get All Campaigns on a Specific Balance

This endpoint lists all campaigns on the specified balance. Response results will be provided in paginated form.

https://api.criteo.com/2022-04/retail-media/balances/{balanceId}/campaigns

Sample Request

curl -X GET "https://api.criteo.com/2022-04/retail-media/balances/14094543095747588032/campaigns" \
    -H "Authorization: Bearer myaccesstoken"

Sample Response

{
    "data": [
        {
            "type": "RetailMediaCampaign",
            "id": "8343086999167541140"
        },
        {
            "type": "RetailMediaCampaign",
            "id": "3683145960016759663"
        }
    ],
    "metadata": {
        "totalItemsAcrossAllPages": 2,
        "currentPageSize": 25,
        "currentPageIndex": 0,
        "totalPages": 1,
        "nextPage": null,
        "previousPage": null
    }
}

What’s Next
Did this page help you?