Sandbox

A sandbox key lets your agent run the whole buying flow against the live sales agent without spending money or reaching a real seller. Use it to build and test your integration, then ask for a live key.

Getting a sandbox key

Ask the Carbnn team for a sandbox key. A key is sandbox or live for its whole life: to go live, you get a second key. Sandbox keys see Carbnn’s test sellers (the sandbox seller) and their fixed test products. There is no access setup: a sandbox key sees them automatically.

What’s real

• Every tool, request and response shape, and RFC 9421 signing.
• Task ids, get_task_status, and signed task webhooks.
• Bookings: create_media_buy and accept_proposal create real media buys with real ids, and get_media_buys and update_media_buy work on them.
• Exchange rates: cross-currency quotes are locked as they would be live.

What’s simulated

• Seller approval. The sandbox seller approves at once. A direct create_media_buy, and a refine_proposals finalize, still answer submitted with a task_id, but the task is already finished when you poll it. If you use webhooks, the task’s terminal webhook may reach you before the submitted reply does. Don’t assume the reply comes first.
• Proposals. request_proposals drafts at the product’s rate card, as it does live. Finalize is approved at once; book with accept_proposal.
• Delivery. get_media_buy_delivery reports straight-line delivery over the flight: nothing before it starts, the booked quantity once it ends, and in between the share of the flight that has passed. Spend never goes over the budget. It is worked out when you read it, and nothing is stored. Flat-rate packages read as delivered only after their flight ends.
• Funding. A sandbox buy is marked funded as soon as it is booked, with no money behind it. As on any funded buy, its package budgets, goals and pacing can’t change after that (INVALID_STATE with reason BUDGET_FROZEN, GOAL_FROZEN or PACING_FROZEN): cancel the package or the buy and book again. Cancelling works as usual.

What’s skipped

• No email or notification reaches anyone.
• No money moves: no invoice, credit check, payment or payout.
• No pacing alerts.

Sending account.sandbox

You don’t need to. The key decides the mode. If you do send account.sandbox and it disagrees with your key, the call fails with ACCOUNT_MODE_MISMATCH (see errors).

Clean-up

Sandbox buys older than 30 days may be removed.