Know What’s Not Billable
Several response statuses are free — you’re not charged when these fire:| Status | Why It’s Free |
|---|---|
message_too_short | Under 10 words — no extraction attempted |
message_too_long | Over 10,000 characters — rejected before processing |
blocked_keyword | Hard stop keyword matched |
country_not_allowed | Non-US country code |
ip_country_not_allowed | IP resolved to non-US |
language_not_allowed | Non-English detected |
no_offer status is billable — ChatAds processed the message but couldn’t find a match. The tips below help you reduce these.
Know What ChatAds Tries Not to Charge You For
We employ a classifier to identify whether a message is conversational or product-related. If it looks conversational, ChatAds short-circuits before extraction — returning in under 50ms and not billing you. This isn’t 100% accurate, but in testing it catches roughly 80% of conversational messages. So you shouldn’t worry about sending messages like “There are a few approaches to improving your sleep schedule. Start by keeping a consistent bedtime and limiting screen time an hour before bed.” — we’ll not only fail fast, we won’t charge you. In these cases, the response will show"status": "no_offer" with "billed": false. This means you don’t need to build your own filter for non-product messages. Just send everything and let ChatAds sort it out.
Pass the country Parameter
If you know the user’s country, pass it in the country parameter. ChatAds will reject non-US traffic for free. Without it, ChatAds falls back to the ip parameter for geo-detection — and if neither is provided, it assumes US and processes the request, meaning you’ll pay for a no_offer result on traffic that was never going to convert.
Pass the ip Parameter
If you’re serving international traffic, pass the user’s IP address in the ip parameter. ChatAds will detect non-US traffic and reject it for free. Without ip or country, ChatAds assumes US and processes the request — meaning you’ll pay for a no_offer result on traffic that was never going to convert.
Turn On Brand-Only Mode
When Brand Only is enabled, ChatAds checks for brand-like words in the message before processing. If no brand is detected, the request is rejected early and not billed. Pros:- Reduces billable
no_offerresults on generic messages (“I need a good laptop”) - Branded matches tend to convert better since users already have a product in mind
- Lower fill rate — generic product mentions like “yoga mat” or “running shoes” won’t match
- Misses opportunities where a generic term could have resolved to a popular product
Use Image Sparingly
Image requests (input_type=image_url or image_file) count as 3x the cost of text requests. Use text mode when possible — if the AI response already mentions the product by name, text extraction will find it without the image premium.
Check billed in the Response
Every response includes a data.billed field. Use it to track how many of your requests are actually costing you money. If you see a high ratio of billed: true with returned: 0, review the tips above to reduce waste.