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

  Attribute	Type	Description
  BudgetCapsUUID	uuid_v4	The unique UUID of the budget caps in the adjoe system.
  ExternalID	string	The partners external ID for these budget caps.
  Name	string	The name for the budget caps set by the advertiser.
  Daily	float	The daily budget limit for the targeting groups that have these budget caps.
  Monthly	float	The monthly budget limit for the targeting groups that have these budget caps.
  Total	float	The total budget limit for the targeting groups that have these budget caps.
  Active	bool	The status of the budget caps, can be either true or false.
  StartAt	timestamp	The timestamp the budget caps should start to apply.
  StopAt	timestamp	The timestamp the budget caps should stop to apply.

• 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

  Attribute	Type	Description
  BudgetCapsUUID	uuid_v4	The unique UUID of the budget caps in the adjoe system.
  ExternalID	string	The advertisers external ID for these budget caps.
  Name	string	The name for the budget caps set by the advertiser.
  Daily	float	The daily budget limit for the targeting groups that have these budget caps.
  Monthly	float	The monthly budget limit for the targeting groups that have these budget caps.
  Total	float	The total budget limit for the targeting groups that have these budget caps.
  Active	bool	The status of the budget caps, can be either true or false.
  StartAt	timestamp	The timestamp the budget caps should start to apply.
  StopAt	timestamp	The timestamp the budget caps should stop to apply.

• 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

  Attribute	Type	Description
  BudgetCapsUUID	uuid_v4	The unique UUID of the budget caps in the adjoe system.
  ExternalID	string	The partners external ID for these budget caps.
  Name	string	The name for the budget caps set by the advertiser.
  Daily	float	The daily budget limit for the targeting groups that have these budget caps.
  Monthly	float	The monthly budget limit for the targeting groups that have these budget caps.
  Total	float	The total budget limit for the targeting groups that have these budget caps.
  Active	bool	The status of the budget caps, can be either true or false.
  StartAt	timestamp	The timestamp the budget caps should start to apply.
  StopAt	timestamp	The timestamp the budget caps should stop to apply.

• 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%'