ads_campaigns_budget_usage
Real-time budget consumption for campaigns — how much of today's budget is already spent, so you can see which campaigns are about to stop serving.
readAmazon Adsads.sp
This is live intraday data the synced report warehouse cannot provide. Amazon Ads API · spCampaignsBudgetUsage · POST /sp/campaigns/budget/usage Amazon Ads API · sbCampaignsBudgetUsage · POST /sb/campaigns/budget/usage Amazon Ads API · sdCampaignsBudgetUsage · POST /sd/campaigns/budget/usage Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/Budget-Usage/operation/spCampaignsBudgetUsage Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-brands/3-0/openapi/prod#tag/Budget-usage/operation/sbCampaignsBudgetUsage Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-display/3-0/openapi#tag/Budget-Usage/operation/sdCampaignsBudgetUsage
Call it
In an AI client (MCP)
{
"name": "ads_campaigns_budget_usage",
"arguments": {
"store": "myStore-US",
"countryCode": "<countryCode>",
"adProduct": "<adProduct>",
"ids": []
}
}From code (Tool API)
curl -X POST https://api.sellersheetai.com/api/v1/tools/ads_campaigns_budget_usage \
-H "Authorization: Bearer $SELLERSHEET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"store":"myStore-US","countryCode":"<countryCode>","adProduct":"<adProduct>","ids":[]}'Arguments
| Name | Type | Description |
|---|---|---|
storerequired | string | the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim. |
countryCoderequired | string | the Ads profile's 2-letter country code (e.g. 'US'). |
adProductrequired | string | SPONSORED_PRODUCTS | SPONSORED_BRANDS | SPONSORED_DISPLAY. |
idsrequired | object[] | 1-100 campaign ids, as strings, from ads_query_campaign. Amazon rejects >100 per call — chunk larger sets. |
Result
Every tool answers {notification, data, human_action}; data carries:
- 207, one result per item; an item whose code is not "Ok" (or that is listed under error / failures) failed — read its details.
Body (Amazon schema)
campaignIds: [string] (1–100)Gotchas
- A partial result is still HTTP-success — always inspect data.result.error[] (per-id failures: unknown id, no active budget) alongside success[]; index matches the position in your ids list.
- budgetUsagePercent is spend / available budget under the current budget policy; usageUpdatedTimestamp is when Amazon last evaluated usage — always relay it, the figure is not instantaneous.
- Campaigns near 100% are about to stop serving; for SPONSORED_PRODUCTS, ads_sp_get_budget_recommendations suggests a raise.