openapi: 3.2.0
info:
  title: NewsBreak Advertising Account Billing API
  version: v1
  description: 'The NewsBreak Advertising API (NewsBreak API for Business) lets technology companies, direct advertisers and agencies programmatically manage the NewsBreak Ads Manager at scale: create and manage organizations, ad accounts and ad-account users; build campaigns, ad sets and ads; upload creative assets to the NewsBreak CDN; configure audience targeting and inventory platforms; manage account spending caps; read conversion tracking events; and run multidimensional performance reports.


    This document was generated by API Evangelist from the operations NewsBreak publishes in its Ad Manager API reference (https://advertising-api.newsbreak.com/hc/en-us). NewsBreak does not publish a machine-readable OpenAPI definition; every path, method, parameter, enumeration and response field here is transcribed from the published reference articles, which are linked per operation via externalDocs.'
  termsOfService: https://www.newsbreak.com/terms
  contact:
    name: NewsBreak Ad Support
    email: adsupport@newsbreak.com
    url: https://advertising-api.newsbreak.com/hc/en-us
servers:
- url: https://business.newsbreak.com/business-api/v1
  description: NewsBreak Advertising API production
security:
- AccessToken: []
tags:
- name: Account Billing
  description: Account-level spending caps and remaining budget.
paths:
  /balance/getAccountBudgetInfo:
    post:
      operationId: getAccountSpendingCap
      tags:
      - Account Billing
      summary: Get account spending cap
      description: Get account remaining budget, account lifetime spending cap and account total spend by account IDs. Users only receive accounts that have an account-level cap and that they have access to. The number of account IDs cannot be 0 or more than 500.
      externalDocs:
        description: 'NewsBreak reference: Get Account Spending Cap'
        url: https://advertising-api.newsbreak.com/hc/en-us/articles/40262348828173-Get-Account-Spending-Cap
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetAccountBudgetRequest'
      responses:
        '200':
          description: 'Successful response. Check `code` in the body: 0 is success, any other value is an error (see Return Codes).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountBudgetResponse'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '403':
          description: Permission denied, not logged in, invalid access token, or rate limit exceeded (return codes 403 / 4031 / 4033 / 4034).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /balance/updateAccountsBudget:
    post:
      operationId: updateAccountSpendingCap
      tags:
      - Account Billing
      summary: Update account spending cap
      description: Update account-level spending caps for multiple ad accounts. Only the organization admin can update the spending cap. Each account is processed individually and a per-account result is returned.
      externalDocs:
        description: 'NewsBreak reference: Update Account Spending Cap'
        url: https://advertising-api.newsbreak.com/hc/en-us/articles/40484091417485-Update-Account-Spending-Cap
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAccountsBudgetRequest'
      responses:
        '200':
          description: 'Successful response. Check `code` in the body: 0 is success, any other value is an error (see Return Codes).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateAccountBudgetResponse'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '403':
          description: Permission denied, not logged in, invalid access token, or rate limit exceeded (return codes 403 / 4031 / 4033 / 4034).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
components:
  schemas:
    UpdateAccountBudgetResponse:
      type: object
      description: Envelope carrying a per-account spending cap update result.
      properties:
        code:
          type: integer
          description: Status code. 0 is successful; see Return Codes.
        errMsg:
          type: string
          description: Error message when code != 0.
        data:
          type: object
          properties:
            list:
              type: array
              items:
                type: object
                properties:
                  adAccountId:
                    type: string
                    description: Ad account ID.
                  message:
                    type: string
                    description: Success or failure message describing the result for this account.
    UpdateAccountsBudgetRequest:
      type: object
      properties:
        adAccountsBudgetUpdate:
          type: array
          description: List of account spending cap updates.
          items:
            type: object
            properties:
              adAccountId:
                type: string
                description: Ad account ID (numeric string).
              budget:
                type: integer
                format: int64
                description: New spending cap in cents. Must be between 0 and 10,000,000,000 cents ($0-$100M), and greater than the account current total spend. If no cap is currently set, this enables and sets it.
                minimum: 0
                maximum: 10000000000
            required:
            - adAccountId
            - budget
      required:
      - adAccountsBudgetUpdate
    GetAccountBudgetRequest:
      type: object
      properties:
        accountIds:
          type: array
          description: IDs of ad accounts. Must be between 1 and 500 IDs.
          items:
            type: string
      required:
      - accountIds
    Envelope:
      type: object
      description: The standard NewsBreak response envelope. Every operation returns HTTP 200 with a `code` field; code 0 means success and any other value is an error (see Return Codes).
      properties:
        code:
          type: integer
          description: Status code. 0 is successful; see Return Codes.
        errMsg:
          type: string
          description: Error message when code != 0.
        data:
          type: object
          description: Response object.
    AccountBudgetResponse:
      type: object
      description: Envelope carrying per-account budget information.
      properties:
        code:
          type: integer
          description: Status code. 0 is successful; see Return Codes.
        errMsg:
          type: string
          description: Error message when code != 0.
        data:
          type: object
          properties:
            list:
              type: array
              items:
                type: object
                properties:
                  accountId:
                    type: string
                    description: Ad account ID.
                  accountRemaining:
                    type: number
                    format: double
                    description: Budget remaining in the account.
                  accountSpendingCap:
                    type: number
                    format: double
                    description: Account-level spending cap.
                  accountTotalSpend:
                    type: number
                    format: double
                    description: Total spent in the account.
                  canViewBudget:
                    type: boolean
                    description: Whether the caller can view this account's budget.
                  failMessage:
                    type: string
                    description: Reason the caller cannot view this account's budget.
  securitySchemes:
    AccessToken:
      type: apiKey
      in: header
      name: Access-Token
      description: Authorized access token. Generate it in the NewsBreak Ad Manager under Resources -> API Access Tokens ("Generate Token"). The token carries the permissions granted by the advertiser. Keep it secret.
externalDocs:
  description: NewsBreak Ad Manager API reference
  url: https://advertising-api.newsbreak.com/hc/en-us