Managing Budget Caps

Introduction

The budget cap is the entity where you set budget constraints for your targeting groups. A budget cap can have daily, monthly and total limits. Campaigns can have multiple budget caps and apply them differently for each targeting group within a campaign.

For example:

  • A campaign can have a total budget cap with a monthly limit. In this case all your targeting groups within this campaign would fall under this cap.

  • If you want to allocate more spend to certain targeting groups within this campaign, this API allows you to adjust each individual budget cap for the targeting groups.

Important! Listed below methods work for all campaign types except interstitial_video.

Getting the list of budget caps

https://prod.adjoe.zone/v2/campaign-management-api/public/%TOKEN%/budget-caps

  • %TOKEN%

    The token is a hex string, which is given to the advertiser by the account manager.

  • Method:

    The http request type

    GET

  • URL Query Parameters

    It is possible to query only active budget caps.

    Optional:

    active_only=true

    paging_key=eyJLZXkiOiJhYmMxMjMifQ==

    limit=100

  • Success Response:

    When successful, the API responds with a http OK status code and a valid json array.

    • Code: 200

      Content-Type: application/json; charset=utf-8

      Content:

      {
  "Content": [
    {
        "BudgetCapsUUID": "00b8aaf6-b51c-407f-a680-cfba796779ad",
        "ExternalID": "abc123",
        "Name": "US_App_Male",
        "Daily": 100.5,
        "Monthly": 10000.8,
        "Total": 100000.9,
        "Active": true,
        "StartAt": "2020-06-01T12:00:00.000Z",
        "StopAt": "2035-05-31T00:00:00.000Z"
    }
  ],
  "NextKey": "eyJLZXkiOiJhYmMxMjMifQ=="
}

    JSON schema definition

  • Error Response:

    The API does respond with different status codes, depending on the error:

    • Code: 401 UNAUTHORIZED

      If the authorization fails, the API returns status code 401 with error message.

      Content-Type: application/json; charset=utf-8

      Content:

      {
    "error" : "invalid token"
}

    • Code: 400 BAD REQUEST

      If one of the URL parameters has a wrong format, the API returns status code 400 with error specific message.

      Content-Type: application/json; charset=utf-8

      Content:

      {
    "error": "active_only format is wrong. Please use true or false."
}

  • Sample Curl Call:

    curl -X GET \
 'https://prod.adjoe.zone/v2/campaign-management-api/public/%TOKEN%/budget-caps?active_only=true&limit=100'

Updating a single budget cap

https://prod.adjoe.zone/v2/campaign-management-api/public/%TOKEN%/budget-caps/%BUDGET_CAPS_UUID%

  • %TOKEN%

    The token is a hex string, which is given to the advertiser by the account manager.

  • %BUDGET_CAPS_UUID%

    The unique UUID of the budget caps entity obtained by previously fetching the available budget caps.

  • Method:

    The http request type

    PUT

  • Request body

    Content

     {
   "Daily": 210.5
 }

    Fields that are not included in the json body are considered to be un-changed.

  • Success Response:

    When successful, the API responds with a http OK status code and a valid json object.

    • Code: 200

      Content-Type: application/json; charset=utf-8

      Content:

      {
    "BudgetCapsUUID": "00b8aaf6-b51c-407f-a680-cfba796779ad",
    "ExternalID": "abc123",
    "Name": "US_App_Male",
    "Daily": 210.5,
    "Monthly": 10000.8,
    "Total": 100000.9,
    "Active": true,
    "StartAt": "2020-06-01T12:00:00.000Z",
    "StopAt": "2035-05-31T00:00:00.000Z"
}

    JSON schema definition

  • Error Response:

    The API does respond with different status codes, depending on the error:

    • Code: 401 UNAUTHORIZED

      If the authorization fails, the API returns status code 401 with error message.

      Content-Type: application/json; charset=utf-8

      Content:

      {
    "error" : "invalid token"
}

    • Code: 404 NOT FOUND

      If the budget caps entity does not exist.

      Content-Type: application/json; charset=utf-8

      Content:

      {
    "error": "resource is unknown"
}

  • Sample Curl Call:

          curl -X PUT \
      'https://prod.adjoe.zone/v2/campaign-management-api/public/%TOKEN%/budget-caps/26ab1520-8a30-4712-b046-94421d49dd6a' \
      --data-raw '{"Daily":210.5}'

Getting a single budget cap by UUID

https://prod.adjoe.zone/v1/campaign-management-api/public/%TOKEN%/budget-caps/%BUDGET_CAPS_UUID%

  • %TOKEN%

    The token is a hex string, which is given to the advertiser by the account manager.

  • %BUDGET_CAPS_UUID%

    The key is a UUIDV4 string, which is assigned to a budget caps resource on creation.

  • Method:

    The http request type

    GET

  • Success Response:

    When successful, the API responds with a http OK status code and a valid json array.

    • Code: 200

      Content-Type: application/json; charset=utf-8

      Content:

      {
    "BudgetCapsUUID": "00b8aaf6-b51c-407f-a680-cfba796779ad",
    "ExternalID": "abc123",
    "Name": "US_App_Male",
    "Daily": 100.5,
    "Monthly": 10000.8,
    "Total": 100000.9,
    "Active": true,
    "StartAt": "2020-06-01T12:00:00.000Z",
    "StopAt": "2035-05-31T00:00:00.000Z"
}

    JSON schema definition

  • Error Response:

    The API does respond with different status codes, depending on the error:

    • Code: 401 UNAUTHORIZED

      If the authorization fails, the API returns status code 401 with error message.

      Content-Type: application/json; charset=utf-8

      Content:

      {
    "error" : "invalid token"
}

    • Code: 400 BAD REQUEST

      If one of the URL parameters has a wrong format, the API returns status code 400 with error specific message.

      Content-Type: application/json; charset=utf-8

      Content:

      {
    "error": "active_only format is wrong. Please use true or false."
}

  • Sample Curl Call:

          curl -X GET \
      'https://prod.adjoe.zone/v2/campaign-management-api/public/%TOKEN%/budget-caps/%BUDGET_CAPS_UUID%'

PreviousManaging Targeting Groups

Last updated