Sandbox Mode

Overview

Sandbox mode supports the platform’s no-spend test workflows when they use a sandbox account and a reviewed provider test context. It does not make every provider account or every execution request non-deliverable on its own.

Supported integration testing

Validate supported workflows with a sandbox account and the provider test context they require.

Account-scoped routing

Supported account resolution and synchronization retain the sandbox setting for the selected account.

How It Works

Sandbox is set on the advertiser, not per request. It is AdCP’s own sandbox flag, fixed when the advertiser is created, and it travels with the AdCP account identity {brand, operator, sandbox} that supported account resolution and synchronization use. Your Apostra buyer account has no sandbox or live mode of its own: what it can do is worked out for each operation (see What sandbox work needs). Keep sandbox advertisers separate from production advertisers. When you create an advertiser with sandbox: true, supported platform account resolution and synchronization use sandbox context. A request that names an account_id relies on that account’s own sandbox semantics. The advertiser flag alone does not prove that an arbitrary provider account cannot reserve, deliver, or otherwise act on a request. Use the provider’s documented test account and the reviewed provider test context before executing a test. The platform preserves its sandbox context for supported flows; it does not replace the provider’s account controls.

What sandbox work needs

A buyer account is not switched into a sandbox or live state. Each operation is checked against the account’s own facts, and the sandbox flag on the advertiser decides which checks apply. Sandbox work (sandbox advertisers, their campaigns and their media buys) needs:

a Buyer account, with no unresolved account hold;
the current Terms of Service accepted by an organization administrator;
a plan selected; and
a verified organization identity: a usable operator domain, with your organization’s control of it proved.

It needs no payment route. You do not need billing details, payment terms or a media-buying entitlement to run a sandbox campaign. One step is relaxed: creating, updating or archiving a sandbox advertiser, and configuring its tracking, does not wait for the operator identity, so you can set an advertiser up before claiming it. Creating a campaign or a media buy under it does wait. Live spend (non-sandbox advertisers and their media buys) needs everything above, plus:

the media-buying entitlement on your plan; and
when the seller is billed through Apostra consolidated billing, your organization’s billing details (payer name, street address and country) and the payment terms Apostra asks sellers for. A seller you pay directly needs neither.

A seller that bills through Apostra consolidated billing is asked for a proposal on behalf of a sandbox advertiser only when it declares sandbox support (AdCP’s account.sandbox capability). The Apostra synthetic seller and Demo Storefronts do, so a sandbox advertiser can request proposals from them with no billing details. A live advertiser never gets that exception. Terms of Service are enforced at the request edge too: until they are accepted, v2 endpoints return TOS_ACCEPTANCE_REQUIRED (HTTP 403). Only the endpoints needed to accept them stay reachable: account, contract, billing-account and notification management.

Seller ad-server setup

For an ad-server-backed storefront, Apostra also needs a dedicated advertiser/account inside the seller’s ad server. Keep it separate from every production advertiser. The seller can either:

Create or designate a sandbox advertiser/account and assign it to Apostra service account, then map it as the storefront’s sandbox advertiser; or
Grant Apostra service account permission to create advertisers so Apostra can provision Apostra - Sandbox automatically.

Until one of those paths is complete, Apostra will recommend the setup in storefront readiness and may send a reviewed seller Nudge. This recommendation does not block live selling, but smoke tests will not run through a production or default advertiser as a fallback. On a Google Ad Manager storefront run by Apostra’s managed sales agent, every buyer sandbox account books on that sandbox advertiser. The seller does not map each sandbox account to an advertiser. The buyer’s sandbox account still needs agent billing.

For protocol-level details on how sandbox mode works, see the AdCP Sandbox documentation.

Creating a Sandbox Advertiser

Via API

Set sandbox: true in the create advertiser request body:

curl -X POST "https://api.apostra.com/api/v2/buyer/advertisers" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp (Sandbox)",
    "description": "Integration testing advertiser",
    "sandbox": true
  }'

const response = await fetch('https://api.apostra.com/api/v2/buyer/advertisers', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SCOPE3_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Acme Corp (Sandbox)',
    description: 'Integration testing advertiser',
    sandbox: true,
  }),
})

const { data } = await response.json()
console.log('Sandbox advertiser:', data.id, data.sandbox) // sandbox: true

import requests, os

response = requests.post(
    'https://api.apostra.com/api/v2/buyer/advertisers',
    headers={
        'Authorization': f'Bearer {os.environ["SCOPE3_API_KEY"]}',
        'Content-Type': 'application/json',
    },
    json={
        'name': 'Acme Corp (Sandbox)',
        'description': 'Integration testing advertiser',
        'sandbox': True,
    },
)

advertiser = response.json()['data']
print('Sandbox advertiser:', advertiser['id'], advertiser['sandbox'])

Response:

{
  "data": {
    "id": "adv_abc123",
    "name": "Acme Corp (Sandbox)",
    "description": "Integration testing advertiser",
    "status": "active",
    "sandbox": true,
    "createdAt": "2026-02-22T21:35:44Z",
    "updatedAt": "2026-02-22T21:35:44Z",
    "linkedBrand": null,
    "brand": null,
    "brandWarning": null
  }
}

Via UI

When creating an advertiser in the dashboard, toggle the Sandbox switch before saving. Sandbox advertisers are shown with a badge in the advertiser list for easy identification.

Sandbox is permanent. Once an advertiser is created with sandbox: true, the flag cannot be changed. This protects against accidentally switching an advertiser from sandbox to production after campaigns have been configured.An update that carries sandbox is refused, whatever its value: PUT /api/v2/buyer/advertisers/{id} returns HTTP 400 with the error code IMMUTABLE_FIELD and field: "sandbox", and nothing in the request is applied. The v2 buyer MCP update_advertiser operation and Murph refuse it the same way, and so does V3 save_advertiser. To move from sandbox to live, create a new advertiser without sandbox.

Using Sandbox

Supported sandbox workflows use the same API endpoints as production. Before executing one, confirm that the selected account is a sandbox account and that the provider’s reviewed test context supports the operation you intend to run. For example, executing a campaign:

curl -X POST "https://api.apostra.com/api/v2/buyer/campaigns/{campaignId}/execute" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json"

The platform keeps sandbox context during supported account resolution and synchronization. If this request names an account_id, the provider action still relies on that account’s sandbox semantics and the provider’s reviewed test context. A sandbox advertiser flag by itself does not prove that every provider response is simulated or that an arbitrary provider account cannot reserve, deliver, or spend.

Media Company V3 preview

Every Media Company can create a sandbox Advertiser, Campaign, Creative, Proposal request, and staged MediaBuy through /mcp/v3 without switching to a Buyer account. The preview exposes save_advertiser, save_campaign, save_creative, save_creative_collection, request_proposals, and save_media_buy in the Seller account. No entitlement or beta grant is required for this no-spend workflow. Live Media Company-managed campaigns use the same tools and come with Merchandising: an organization on a current Merchandising plan has them, and a Listing plan keeps sandbox only. Live operations retain normal approval, creative, financial, publisher, and inventory-source readiness checks; Merchandising does not bypass them. Giving clients access to operate their own campaigns is separate and uses the storefront-self-service-buyers rollout. Neither expands an Advertiser’s durable Storefront scope. This path is deliberately confined:

save_advertiser creates a no-spend Advertiser with sandbox: true; when the organization has live managed campaigns, omitting sandbox creates a live Advertiser;
the advertiser and campaign remain owned by the authenticated Media Company;
Campaign creation is pinned server-side to the company’s own Storefront, even when sellerIds is omitted; and
Proposal requests can address only that Storefront;
Proposal acceptance and direct MediaBuy staging reject foreign qualified Proposal and Product IDs; and
existing MediaBuy updates require every line item to resolve durably to that Storefront.

Integrated buyer search and get can inspect an authorized sandbox or live Advertiser, Campaign, Creative, Proposal, and MediaBuy. Opening the company’s own Seller with include: ["products"] returns its wholesale Products, including any eligible signal_targeting_options; pass a selected Signal through that Product’s targetingOverlay when staging the MediaBuy. After launch, get_delivery({ report: "live_campaign_delivery", ... }) reads bounded delivery live for one exact own-supply campaign. It accepts the campaign ID and date range, not warehouse metrics, dimensions, other filters, or pagination. The stored aggregate contract remains available as campaign_delivery. Seller Accounts also get a route-backed organization workspace selector. Inventory keeps the existing seller experience; Campaigns lists the account’s sandbox Advertisers, plus its live own-supply Advertisers when the account has live managed campaigns, and opens the shared Campaigns and Creative Pages. The native roster read stays fail-closed to sandbox for an account without live managed campaigns; it does not grant general Buyer REST access. Two additional read-only compatibility calls hydrate those shared Pages: Campaign listing requires an explicit, durably bound advertiserId in either environment and removes Campaigns outside own supply; the promoted Creative list requires the same bound Advertiser and exposes no attach or generation actions. Advertiser, Campaign, and Creative detail, mutations, and reporting remain V3-only for the Seller Account. Agents appears in the same selector when the organization separately has Agent workspace access. Within a browser session, returning to Campaigns restores the last Advertiser that was successfully resolved from that roster; an invalid or foreign Advertiser ID returns to account scope instead. Creating an Advertiser or requesting Reporting from the Campaigns workspace stages an Apostra request, so the guarded V3 flow remains the only write and delivery path — the workspace’s ”+ Add advertiser” control stages a sandbox-creation prompt today; an account with live managed campaigns can ask Apostra directly to create a live Advertiser. Browse media partners, Connections, Buyer Setup, and unbound production Advertisers remain outside this preview. Independent Buyer Accounts and their existing sandbox workflows are unchanged.

Validate an Agent in sandbox

Agent validation now uses the Agent’s public validationSkill and the ordinary V3 Buyer workflow. Resolve the exact Agent with get({ kind: "agent" }), select a profile from its returned plan, fetch the versioned skill, and follow that skill without substituting legacy test wrappers or generic V2 api_call orchestration. Run the profile with sandbox inputs first. The workflow uses the same typed V3 objects and operations a Buyer uses: Advertiser, Campaign, Creative, Proposal, MediaBuy, and bounded delivery reads. It preserves normal confirmation before mutations and never treats a simulated run as certification. After the run or an intentional stop, read the same Agent with include: ["validationRuns", "diagnostics"]. Pass an exact validationRunId to inspect its bounded trace. If the run selected Products from a Source, open that Source’s diagnostics as well. Report which assertions were observed, failed, unavailable, or unexercised, and report cleanup separately. The Test Runs Page is retired, and historical Apostra test-run records are no longer a launch surface or readiness authority. Agent validation evidence and Source diagnostics are the canonical history. A source’s latest tests are available from get({ "kind": "inventory_source", "include": ["testRuns"] }).

Filtering Sandbox Advertisers

The sandbox field is returned on every advertiser response. Use the optional sandbox query parameter to filter:

# List only sandbox advertisers
curl "https://api.apostra.com/api/v2/buyer/advertisers?sandbox=true" \
  -H "Authorization: Bearer your-api-key"

# List only production advertisers
curl "https://api.apostra.com/api/v2/buyer/advertisers?sandbox=false" \
  -H "Authorization: Bearer your-api-key"

In the dashboard, sandbox advertisers are shown with a Sandbox badge so they are easy to distinguish from production advertisers at a glance.

Key Constraints

Constraint	Detail
Immutable flag	`sandbox` cannot be changed after advertiser creation. An update that names it is refused with `IMMUTABLE_FIELD` (HTTP 400).
No payment route for sandbox work	Sandbox advertisers, campaigns and media buys need Terms, a plan and a verified organization, not billing details, payment terms or the media-buying entitlement. Live spend needs those too.
Apostra separation	Sandbox advertiser records and supported account context stay separate from production in Apostra. This does not turn a provider account into a sandbox account.
Provider test context required	Use the provider’s own sandbox or test account and its documented test context for every provider call. The advertiser flag alone does not guarantee that a provider cannot reserve, deliver, or spend.

Next Steps

Advertiser API Reference

Full schema for POST /advertisers, including the sandbox field.

AdCP Sandbox Docs

Protocol-level details on how sandbox mode works in AdCP.

Quickstart

Get up and running with Apostra API.

Start here

Buy media

Sell media

Help and updates

Overview

Supported integration testing

Account-scoped routing

How It Works

What sandbox work needs

Seller ad-server setup

Creating a Sandbox Advertiser

Via API

Via UI

Using Sandbox

Media Company V3 preview

Validate an Agent in sandbox

Filtering Sandbox Advertisers

Key Constraints

Next Steps

Advertiser API Reference

AdCP Sandbox Docs

Quickstart

​Overview

Supported integration testing

Account-scoped routing

​How It Works

​What sandbox work needs

​Seller ad-server setup

​Creating a Sandbox Advertiser

​Via API

​Via UI

​Using Sandbox

​Media Company V3 preview

​Validate an Agent in sandbox

​Filtering Sandbox Advertisers

​Key Constraints

​Next Steps

Advertiser API Reference

AdCP Sandbox Docs

Quickstart

Overview

How It Works

What sandbox work needs

Seller ad-server setup

Creating a Sandbox Advertiser

Via API

Via UI

Using Sandbox

Media Company V3 preview

Validate an Agent in sandbox

Filtering Sandbox Advertisers

Key Constraints

Next Steps