⚠️

Documentation Disclaimer

This documentation is not exhaustive and does not guarantee system behavior. Integrators are responsible for testing against actual API responses. See Documentation Disclaimer for full details.

Budget & Billing Reference

This page covers everything related to budgets, billing cycles, proration, and monetary behavior in the Yelp Ads API.

Table of Contents

• Budget Formatting
• Setting & Changing Budgets
• Fee Periods
• Proration
• Budget Caps & Over-Delivery
• Promotions & Budget Thresholds
• Edge Cases

---

Budget Formatting

All budget and bid values are in cents (integer), not dollars.

Sending 25 when you mean $25.00 will be rejected or result in a $0.25 budget. This is the most common misconfiguration.

Minimum monthly budget: 2500 ($25.00)

Bids (max_bid) follow the same format. Minimum: 50 ($0.50).

---

Setting & Changing Budgets

At creation: Pass budget as a query parameter on POST /v1/reseller/program/create.

Immediate change: Pass budget on POST /{program_id}/edit without future_budget_date.

Scheduled change: Pass both budget and future_budget_date on edit to apply the change at a specific future date.

Budget can be changed at any time within a billing cycle — there is no restriction on frequency.

Warning: Depending on the magnitude of a budget change, Yelp's backend may terminate the existing program and create a new one. If this happens, the new program starts with no active features — SCT, CLT, and all other features must be re-applied on the new program_id. See Campaign Management Behavior & Nuances for details.

---

Fee Periods

The fee_period parameter determines the billing cycle for CPC programs:

fee_period cannot be changed once a program has started. It is locked at creation time. To change the fee period, you must terminate the program and create a new one.

---

Proration

If a program starts or ends mid-month, Yelp generally prorates the budget by the number of active days. Exact proration behavior has nuances — contact [email protected] for specifics.

Enhanced Profile products are not prorated. Once purchased, an EP runs until explicitly ended — no partial-month billing.

---

Budget Caps & Over-Delivery

Yelp operates on a hard budget cap model:

• The monthly budget is the maximum charged — it will never be exceeded
• Yelp may over-deliver impressions without charging for the overage
• Unused budget does not roll over to the next month

---

Promotions & Budget Thresholds

If a program has an associated promo campaign, be aware:

• Reducing the primary campaign budget below the promo threshold will cause the promo campaign to be automatically terminated (via a nightly job)
• Increasing the budget above the original promo threshold does not generate a new or larger promo campaign
• Promo budgets are fixed at the time of the original creation

See Campaign Management Behavior & Nuances for full promo lifecycle details.

---

Edge Cases

Budget edit while business is delinquent:
Editing a budget while the associated business account is in a delinquent state may have unintended effects on other active programs for that business. Confirm account standing before submitting budget modifications.

Cannot decrease below amount already spent:
If you attempt to lower the budget below the amount already spent in the current billing period, the job will be REJECTED with error CANNOT_DECREASE_BUDGET_BELOW_AMOUNT_ALREADY_SPENT.

Budget and bid in same request:
max_bid can only be changed if the program was originally created with is_autobid=false. Minimum max_bid is 50 ($0.50).