Budget REST API

This API defines operations to allow management of the spending limits in effect for inventory items within the Cxense Advertising platform.

Budgets specify spending limits for inventory elements below them.

The API can be accessed by users with the appropriate permissions to manage Budgets and supports the following combination of operations on Budget domain objects:

Budget types

There are two broad classes of budgets based on how they are measured:

Counter Budgets

Counter budgets simply count the number of impression or click events that are tallied against the inventory. Counter budgets have 3 different types:

• IMPRESSION_BALANCE: These are used on CPM style campaigns. If an advertiser buys 1,000,000 impressions for a CPM campaign, the limit is enforced by a counter budget, typically placed at the campaign folder. The budget's amount is set to 1,000,000 and its initial balance is set to 0. As impressions are recorded against ads in the campaign the balance is incremented. When the balance finally reaches the amount value (1,000,000) the campaign is disabled. These budgets cannot be set arbitrarily, they are created automatically upon creation of a CPM contract, see the Campaign and Contract REST API for details on setting up contracts. Hence, this REST API does not support creating/modifying or deleting these budgets. You can, however, retrieve them using a GET call.

• IMPRESSION_CAP: These budgets enforce an absolute limit on the number of impressions allowed on the Campaign/Ad they are applied to during the period of the budget. Unlike IMPRESSION_BALANCE budgets they can apply on Ads/Campaigns using any product type, not just CPM and are user settable.

• CLICK_CAP: Like IMPRESSION_CAP budgets except that they apply on clicks, i.e. once the number of clicks exceed the budget the Adserver will stop showing the Ad. Note that due to the fact that the Adserver has no direct control on clicks once an impression is made, there is a higher risk of encountering overage with these types of budgets.

• Budget types

  • Counter Budgets

  • Currency Budgets

• Operational Constraints

• BudgetLists

  • GET

  • POST

• Individual Budgets

  • GET

  • PUT

  • DELETE

Counter budgets have the following data fields (remember, you can only read IMPRESSION_BALANCE budgets, i.e. no creation/modification/deletion):

Currency Budgets

Currency budgets count against the monetary cost of events that occur against the inventory. These are typically used on CPC campaigns. Supposing an advertiser wishes to spend a maximum of USD 1,000.00 a day, accordingly he sets a daily currency budget of USD 10,000.00 against his campaign. The the budget's amount value is set to USD 1,000.00 while its initial balance is set to USD 0.00 and its period is set to DAILY. As clicks are recorded against ads in the campaign the balance is incremented by the cost of the clicks as determined by the CPC auction results. If the balance reaches USD 1,000.00 before the end of the day the campaign is disabled temporarily. It will be re-enabled on the next day with its balance reset to USD 0.00.

Unlike counter budgets, advertisers are free to create, modify and delete currency budgets.

Currency budgets have the following data fields (all fields mandatory unless otherwise indicated):

See Budgeting for further details.

Operational Constraints

• You cannot create, modify or delete an IMPRESSION_BALANCE budget

• You cannot create more than one budget of the same type on a single folder

• Budgets can be modified but the only field you can modify is the amount, all the others are immutable once the budget is created. Of course, you can always delete a budget and create a new one if you make a mistake.

BudgetLists

Like most other cxad inventory types, Budgets are located under folders. If you have a folderId you can create a new Budget under it by POSTing to it and you can get the list of all Budgets under a folder (and its descendents) by GETting from it.
The GET operation is supported for listing existing Budgets.

GET

Retrieve the list of all Budgets created at any point under a folder.

https://{cxadbaseurl}/api/secure/budgets/{folderid}

Parameters:

• cxadbaseurl the base URL of the Cxense Advertising system

• folderid the folder id under which to search for budgets

Example command:

curl -s -H "Content-type: text/xml" -u jsmith123:password1 -X GET https://cxad.cxense.com/api/secure/budgets/0000123ef4ab3c3b

Example result:

<?xml version="1.0"?>
<cx:budgets xmlns:cx="http://cxense.com/cxad/api/cxad">
    <cx:budget id="0034eb789abcdef0">
        <cx:context>
          <cx:ref>./folder/0000000000000000</cx:ref>
          <cx:ref>./broker/00000000214bfc57</cx:ref>
          <cx:ref>./folder/ffffffff9a47f646</cx:ref>
          <cx:ref>./folder/000000000f28c5c4</cx:ref>
          <cx:ref>./folder/000000000001467f</cx:ref>
          <cx:ref>./campaign/0000000000014699</cx:ref>
        </cx:context>
        <cx:amount class="counter" value="100000"/>
        <cx:startTime>2011-02-25T00:00:00.000Z</cx:startTime>
        <cx:endTime>2011-03-07T23:59:59.999Z</cx:endTime>
        <cx:smoothed>true</cx:smoothed>
        <cx:periodBalance class="counter" value="25000"></cx:periodBalance>
        <cx:periodRemainingBalance class="counter" value="75000">
        <cx:type>IMPRESSION_BALANCE</cx:type>
    </cx:budget>
    <cx:budget id="43a82358c14511e0">
        <cx:context>
          <cx:ref>./folder/0000000000000000</cx:ref>
          <cx:ref>./broker/00000000214bfc57</cx:ref>
          <cx:ref>./folder/ffffffff9a47f646</cx:ref>
          <cx:ref>./folder/000000000f28c5c4</cx:ref>
          <cx:ref>./folder/000000000001467f</cx:ref>
          <cx:ref>./campaign/0000000000014699</cx:ref>
        </cx:context>
        <cx:amount class="currency" currencyCode="USD" value="1000.00"/>
        <cx:startTime>2011-02-25T00:00:00.000Z</cx:startTime>
        <cx:periodType>DAILY<cx:periodType>
        <cx:smoothed>false</cx:smoothed>
        <cx:periodStartTime>2011-02-26T00:00:00.000Z</cx:periodStartTime>
        <cx:periodEndTime>2011-02-26T23:59:59.999Z</cx:periodEndTime>
        <cx:periodBalance class="currency" currencyCode="AUD" value="75.000000"></cx:periodBalance>
        <cx:periodRemainingBalance class="currency" currencyCode="AUD" value="25.000000"></cx:periodRemainingBalance>
        <cx:periodProRata>false</cx:periodProRata>
        <cx:type>CURRENCY_CAP</cx:type>
   </cx:budget>
</cx:budgets>

POST

Create a new currency Budget under the Folder with the given folderId. Remember, you cannot create a new IMPRESSION_BALANCE budget.

https://{cxadbaseurl}/api/secure/budgets/{folderId}

Parameters:

• cxadbaseurl the base URL of the Cxense Advertising system

• folderId the id of the Folder under which the new Budget is to be created.

Example command:

curl -s -H "Content-type: text/xml" -u jsmith123:password1 -X POST https://cxad.cxense.com/api/secure/budgets/0000000000000111 -d @/home/jsmith123/tmp/create-budget.xml

This XML example shows the contents required to be POSTed when creating a currency Budget:

XML example:

<?xml version="1.0"?>
<cx:budget xmlns:cx="http://cxense.com/cxad/api/cxad">
    <cx:amount class="currency" currencyCode="USD" value="1000.00"/>
    <cx:startTime>2011-02-25T00:00:00.000Z</cx:startTime>
    <cx:endTime>2011-03-07T23:59:59.999Z</cx:endTime>
    <cx:periodType>DAILY</cx:periodType>
    <cx:smoothed>false</cx:smoothed>
    <cx:type>CURRENCY_CAP</cx:type>
 </cx:budget>

The result of a successful POST will be the full xml content of the newly created budget.

Individual Budgets

The GET, PUT and DELETE operations are supported for management of individual Budgets.

GET

Retrieve the Budget with the given budgetId

https://{cxadbaseurl}/api/secure/budget/{budgetId}

Parameters:

• cxadbaseurl the base URL of the Cxense Advertising system

• budgetId the id of the Budget to be retrieved

Example command:

curl -s -H "Content-type: text/xml" -u jsmith123:password1 -X GET https://cxad.cxense.com/api/secure/budget/5511ef92c14611e0

XML example:

<?xml version="1.0"?>
<cx:budget id="5511ef92c14611e0">
    <cx:context>
      <cx:ref>./folder/0000000000000000</cx:ref>
      <cx:ref>./broker/00000000214bfc57</cx:ref>
      <cx:ref>./folder/ffffffff9a47f646</cx:ref>
      <cx:ref>./folder/000000000f28c5c4</cx:ref>
      <cx:ref>./folder/000000000001467f</cx:ref>
      <cx:ref>./campaign/0000000000014699</cx:ref>
    </cx:context>
    <cx:amount class="currency" currencyCode="USD" value="1000.00"/>
    <cx:startTime>2011-02-25T00:00:00.000Z</cx:startTime>
    <cx:periodType>DAILY<cx:periodType>
    <cx:smoothed>false</cx:smoothed>
    <cx:periodStartTime>2011-02-26T00:00:00.000Z</cx:periodStartTime>
    <cx:periodEndTime>2011-02-26T23:59:59.999Z</cx:periodEndTime>
    <cx:periodBalance class="currency" currencyCode="AUD" value="75.000000"></cx:periodBalance>
    <cx:periodRemainingBalance class="currency" currencyCode="AUD" value="25.000000"></cx:periodRemainingBalance>
    <cx:periodProRata>false</cx:periodProRata>
    <cx:type>CURRENCY_BALANCE</cx:type>
</cx:budget>

PUT

Update the Budget with the given budgetId. Note that only the amount value can be updated and IMPRESSION_BALANCE budgets cannot be updated.

https://{cxadbaseurl}/api/secure/budget/{budgetId}?amount={amount}

Parameters:

• cxadbaseurl the base URL of the Cxense Advertising system

• budgetId the id of the Budget to be retrieved

• amount a positive decimal value for the new amount

Example command:

curl -s -H "Content-type: text/xml" -u jsmith123:password1 -X PUT https://cxad.cxense.com/api/secure/budget/5511ef92c14611e0?amount=1234

DELETE

Delete the Budget with the given budgetId. Remember IMPRESSION_BALANCE budgets cannot be deleted.

https://{cxadbaseurl}/api/secure/budget/{budgetId}

Parameters:

• cxadbaseurl the base URL of the Cxense Advertising system

• budgetId the id of the Budget to be retrieved

Example command:

curl -s -H "Content-type: text/xml" -u jsmith123:password1 -X DELETE https://cxad.cxense.com/api/secure/budget/eb2911aec14611e0

Last updated: January 19, 2022