Introduction

Spend Cap APIs allow platforms to create, read, update, and list spend caps programmatically, and to associate campaigns with a specific spend cap during campaign management workflows.

Common workflow

A typical Spend Cap workflow looks like this:

1. Create a spend cap for the correct ad account.
2. Store the returned spend_cap.id.
3. Create a campaign and pass spend_cap_id in the campaign request.
4. Read, list, or update spend caps as needed for audit and budget management workflows.

1. Create a Spend Cap

Use CreateSpendCap to create a new spend cap within an ad account.

Key request fields:

• title schedule.start
• schedule.end (optional)
• budget.period
• budget.amount.currency
• budget.amount.amount_micro
• comment (optional)

{
  "title": "Q2 2026 - Brand Campaign IO",
  "schedule": {
    "start": "2026-04-01T00:00:00Z",
    "end": "2026-06-30T23:59:59Z"
  },
  "budget": {
    "period": "TOTAL",
    "amount": {
      "currency": "USD",
      "amount_micro": "50000000000"
    }
  },
  "comment": "Payer XYZ"
}

The response returns a **spend_cap **object including the new spend_cap.id, which should be stored and reused in later API calls.

2. Assign a Spend Cap to a campaign

When creating a campaign, pass the spend_cap_id returned by CreateSpendCap or ReadSpendCap.

New field:

• spend_cap_id: the ID of the spend cap associated with the campaign

{
  "campaign": {
    "title": "Spring Promo - Display",
    "spend_cap_id": "sc_abc123def456",
    "ad_type": "ITEM"
  }
}

The campaign response now also includesspend_cap_idso the association is visible in downstream reads.

3. Update a Spend Cap

Use UpdateSpendCap when budget values, dates, status, or reference information need to change.

Typical updates:

• change the title;
• extend or shorten the schedule;
• increase or decrease the budget;
• activate or pause the spend cap;
• update the comment/reference field.

{
  "spend_cap": {
    "schedule": {
      "start": "2026-04-01T00:00:00Z",
      "end": "2026-07-31T23:59:59Z"
    },
    "budget": {
      "period": "TOTAL",
      "amount": {
        "currency": "USD",
        "amount_micro": "75000000000"
      }
    },
    "status": "ACTIVE",
    "comment": "Payer Name XYZ"
  }
}

4. Read and List Spend Caps

These APIs are straightforward and can be used for audit, reconciliation, and integration checks.

• ReadSpendCap: Returns the current details of a single spend cap by ID.
• ListSpendCaps: Returns a paginated list of spend caps within the specified ad account. A status filter is supported.

5. Campaign Read and List updates

Spend Cap support also affects campaign read/list responses.

• ListCampaigns: Each campaign object in ListCampaigns now includes campaigns[].spend_cap_id.
• ReadCampaign: ReadCampaign now returns spend_cap_id. This field is null if no spend cap is assigned.

6. Status values

Spend cap status values include:

• SCHEDULED
• ACTIVE
• INACTIVE
• ENDED
• DEPLETED
• ERROR

📘

Note

All monetary values are expressed in micro-units and passed as strings. For example, $50,000 USD is represented as 50000000000.

Related documentation

If your platform uses Spend Cap, see these related sections:

• Spend Cap for product-level concepts and use cases.
• Financial Data for Spend Cap Daily Summary export schema and delivery details.