Environments and testing
Carrot Ads requests run against an Instacart environment. Use the host and credentials Instacart assigned for that environment, and keep test traffic out of production campaigns.
Environments overview
| Environment | Ads data host | What it is for |
|---|---|---|
| Development | The development domain Instacart assigned to your integration | Build and validate your integration against mock ads. |
| Staging | connect-ian.stg.instacart.com | End-to-end testing of Carrot Ads requests with production API contracts and real ads from test campaigns. |
| Production | The production host Instacart assigned. The typical host is connect-ian.instacart.com. | Serve live ads to customers. |
The OAuth token host can differ from the ads data host. Use the hosts Instacart assigned for your integration. Staging is an exception: a token minted on the production token host is valid against the staging data host. For more information, see Staging authentication.
For more information about minting a token, see Authentication.
Development environment and mock responses
In development, Get sponsored products and Get display placements return deterministic mock ads from a fixed fixture set for your retailer. Documentation examples that use values such as fake_rrc and fake_rrc_2 are placeholders. The development environment returns retailer-specific numeric RRC or UPC values from your fixture set.
Write lookup code that resolves whatever identifier the response includes (rrc, upc, or product_id). Do not hard-code the placeholder values from these docs.
Testing with test campaigns
Set session_context.test_only to true to restrict responses to test campaigns.
The flag does not change development responses. Development always returns mock ads from a fixed fixture set.
On staging, set test_only to true so you do not accidentally serve live campaigns.
Set test_only to false, or omit it, before you launch to production. Leaving test_only set to true in production means production campaigns do not participate, which can prevent live ads and associated revenue from being served.
Move from development to production
Before you send live traffic, complete the following checks:
- Set
test_onlytofalse, or omit the field. - Replace the development or staging ads data host with the production host.
- Confirm you are using production credentials.
- Verify RRC and UPC mapping against your production catalog. For more information, see Filters and catalog identifiers.
- Send one live request for each page-query and placement pairing you support.
- Confirm ad events reach the Track ad events endpoint.
- In production, ingest orders through Ingest orders within three days of order creation. Orders ingestion is not available in staging.
Staging authentication
Staging supports end-to-end testing of Carrot Ads requests using production API contracts and real ads from test campaigns. Send ads requests to connect-ian.stg.instacart.com. Mint the token on the production token host, typically connect-ian.instacart.com. A production token is valid against the staging data host.
Orders ingestion is not supported on staging.
Do not send staging test traffic to a production ads data host.
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
401 with the given location code doesn't match the oauth token used. | The location_code, X-Retailer-Id slug, or token does not belong together. | Use the retailer slug, location code, and token Instacart issued for the same banner and country. For more information, see Identifiers. |
401 after a token that is still within 24 hours of created_at | The token is not valid for this data host, retailer slug, or country. | Mint a token on the host Instacart assigned for this integration and retry. For staging, use a production token against the staging data host. See 401 Unauthorized responses. |
Ads look like documentation placeholders (fake_rrc) in development | Your code expects the example values from these docs. | Resolve rrc, upc, or product_id from the response. Development returns retailer-specific IDs. |
| Production responses contain only test campaigns, or live campaigns never appear | test_only is still true. | Set test_only to false or omit it. |