Search
K

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.

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