Skip to main content

One Time Budgets

Overview​

Alongside Monthly Budgets set in the Job Campaign object, One Time budgets are an additional method you can choose to fund a Campaign or Event. One Time Budgets can be used in addition to Monthly Budgets, or can be used as the sole source of funding for a Campaign or Event. One Time Budgets are their own entity and have their own set of One Time Budget endpoints for management.

Creating a One Time Budget​

There are 4 main fields that must be passed when creating a One Time Budget:

  • campaignId: The corresponding Job Campaign Id this One Time Budget is going to be applied to
  • startDate: The date (YYYY-MM-DD) at which this One Time Budget should be applied
    • This date can not be in the past
  • launchOnStart: A flag indicating whether or not this budget should push its Job Campaign live on its startDate
    • This can be useful so that you do not have to make additional calls to launch a Job Campaign if the One Time Budget is helping fund the Job Campaign
    • Note: By default, this value is set to true. This can be set to false and you can choose to launch the Job Campaign with a separate API call
  • rollover: A flag indicating whether or not this One Time Budget should expire at the end of the month, or continue to be valid until spent completely
    • A value of false indicates that this budget should expire at the end of the calendar month
    • A value of true will direct the system to automatically create a new One Time Budget for the following month with a budgetCents value equal to the remaining budget that was not used in the previous month
  • budgetCents: This is the budget that should become available to the Job Campaign on the One Time Budget's start

The following example request to the POST /campaigns/{campaignId}/scheduling/one-time-budgets endpoint would create a new One Time Budget for a Job Campaign (id:12345) with a startDate of "2023-04-10" and a budget of 1,000,000 cents ($10,000) that would not rollover to the subsequent month and will not automatically launch a UNDER_DEVELOPMENT or OUT OF BUDGET campaign:

curl -X 'POST' \
  'https://api.talroo.com/v5/campaigns/12345/scheduling/one-time-budgets' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "start": "2023-04-10",
  "budgetCents": "1000000",
  "rollover": false,
  "launchOnStart": false
}'
tip

While it is possible to fund an Event using the jobCampaign.monthlyBudget field, given the nature of Events this is not recommended. Instead, it is highly recommended to utilize One Time Budgets with rollover set to true to fund your Event.

Retrieving your One Time Budgets​

While there is a Campaign Report that you can include on your API calls when retrieving Job Campaigns that will include your Job Campaigns' One Time Budgets, you can also call the One Time Budget endpoints directly to retrieve a Job Campaign's One Time Budgets.

The following example request to the GET /campaigns/{campaignId}/scheduling/one-time-budgets endpoint would retrieve all active One Time Budgets for a Job Campaign with the Id:12345 :

curl -X 'GET' \
  'https://api.stage.talroo.com/v5/campaigns/12345/scheduling/one-time-budgets?page=0&size=20' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {accessToken}'

Updating Active One Time Budgets​

If you need to add additional budget to an active One Time Budget, you can update it using the PATCH /scheduling/one-time-budgets/{oneTimeBudgetId} endpoint. This is useful when you want to increase the budget of an existing One Time Budget without creating a new one.

First, you'll need to get the One Time Budget ID using the GET /campaigns/{campaignId}/scheduling/one-time-budgets endpoint. Then, you can update the budget using the following example:

curl -X 'PATCH' \
  'https://api.talroo.com/v5/scheduling/one-time-budgets/67890' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'Content-Type: application/json' \
  -d '{
    "budgetCents": "2000000"
  }'
note
  • You can only update the budget amount of an active One Time Budget
  • The new budget amount must be greater than the campaign's current mtdSpend
  • The update will take effect immediately