Update storefront

curl --request PUT \
  --url https://api.interchange.io/api/v2/storefront \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

import requests

url = "https://api.interchange.io/api/v2/storefront"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

fetch('https://api.interchange.io/api/v2/storefront', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "storefrontId": "1234",
  "platformId": "acme-media",
  "name": "Acme Media",
  "publisherDomain": "acme.com",
  "operatorDomain": "scope3.com",
  "brandName": "Scope3",
  "logoUrl": "<string>",
  "regions": [
    "<string>"
  ],
  "acceptedCountries": [
    "<string>"
  ],
  "acceptsAllCountries": true,
  "advertisingPolicyDisclosure": [],
  "advertisedCountries": [
    "<string>"
  ],
  "advertisedChannels": [
    "<string>"
  ],
  "description": "<string>",
  "channels": [
    "<string>"
  ],
  "website": "<string>",
  "discoveryCard": {
    "storefrontId": "<string>",
    "platformId": "<string>",
    "displayName": "<string>",
    "logoUrl": "<string>",
    "description": "<string>",
    "website": "<string>",
    "brandColors": {},
    "channels": [
      "<string>"
    ],
    "countries": [
      "<string>"
    ],
    "acceptsAllCountries": true,
    "coverageDeclarations": [
      {
        "channels": [
          "<string>"
        ],
        "countries": [
          "<string>"
        ],
        "acceptsAllCountries": true
      }
    ],
    "advertisingPolicies": "<string>",
    "coverage": {},
    "provenance": {
      "identity": {},
      "coverage": {}
    }
  },
  "demandContactName": "<string>",
  "demandContactEmail": "<string>",
  "operatorDomainVerified": true,
  "adapterCredentialMode": "BYOK",
  "plan": "basic",
  "transacting": true,
  "isPaused": true,
  "archivedAt": "2023-11-07T05:31:56Z",
  "capabilities": {
    "offersCreativeReview": false,
    "offersCampaignApproval": false,
    "offersProductComposition": false
  },
  "configuredCapabilities": {
    "offersCreativeReview": false,
    "offersCampaignApproval": false,
    "offersProductComposition": false
  },
  "compositionPricing": {
    "targetPercentile": "p75",
    "rateCard": {
      "facts": []
    }
  },
  "capabilitiesLocked": true,
  "advertiseAsAgent": true,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "businessProfile": {
    "summary": "<string>",
    "agentName": "<string>",
    "agentPersonality": "<string>",
    "propertyCount": 5000,
    "channels": [],
    "regions": [
      "UK",
      "EMEA"
    ],
    "verticals": [
      "sports",
      "entertainment"
    ],
    "publisherDomains": [
      "pitchside.co.uk",
      "football.pitchside.co.uk"
    ],
    "evidenceUrls": [
      "<string>"
    ],
    "notes": "<string>",
    "updatedBy": "<string>"
  },
  "sellsThirdPartyInventory": true,
  "defaultCurrency": "<string>",
  "paymentCurrencies": [
    "<string>"
  ]
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

PUT

storefront

Update storefront

curl --request PUT \
  --url https://api.interchange.io/api/v2/storefront \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

import requests

url = "https://api.interchange.io/api/v2/storefront"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

fetch('https://api.interchange.io/api/v2/storefront', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "storefrontId": "1234",
  "platformId": "acme-media",
  "name": "Acme Media",
  "publisherDomain": "acme.com",
  "operatorDomain": "scope3.com",
  "brandName": "Scope3",
  "logoUrl": "<string>",
  "regions": [
    "<string>"
  ],
  "acceptedCountries": [
    "<string>"
  ],
  "acceptsAllCountries": true,
  "advertisingPolicyDisclosure": [],
  "advertisedCountries": [
    "<string>"
  ],
  "advertisedChannels": [
    "<string>"
  ],
  "description": "<string>",
  "channels": [
    "<string>"
  ],
  "website": "<string>",
  "discoveryCard": {
    "storefrontId": "<string>",
    "platformId": "<string>",
    "displayName": "<string>",
    "logoUrl": "<string>",
    "description": "<string>",
    "website": "<string>",
    "brandColors": {},
    "channels": [
      "<string>"
    ],
    "countries": [
      "<string>"
    ],
    "acceptsAllCountries": true,
    "coverageDeclarations": [
      {
        "channels": [
          "<string>"
        ],
        "countries": [
          "<string>"
        ],
        "acceptsAllCountries": true
      }
    ],
    "advertisingPolicies": "<string>",
    "coverage": {},
    "provenance": {
      "identity": {},
      "coverage": {}
    }
  },
  "demandContactName": "<string>",
  "demandContactEmail": "<string>",
  "operatorDomainVerified": true,
  "adapterCredentialMode": "BYOK",
  "plan": "basic",
  "transacting": true,
  "isPaused": true,
  "archivedAt": "2023-11-07T05:31:56Z",
  "capabilities": {
    "offersCreativeReview": false,
    "offersCampaignApproval": false,
    "offersProductComposition": false
  },
  "configuredCapabilities": {
    "offersCreativeReview": false,
    "offersCampaignApproval": false,
    "offersProductComposition": false
  },
  "compositionPricing": {
    "targetPercentile": "p75",
    "rateCard": {
      "facts": []
    }
  },
  "capabilitiesLocked": true,
  "advertiseAsAgent": true,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "businessProfile": {
    "summary": "<string>",
    "agentName": "<string>",
    "agentPersonality": "<string>",
    "propertyCount": 5000,
    "channels": [],
    "regions": [
      "UK",
      "EMEA"
    ],
    "verticals": [
      "sports",
      "entertainment"
    ],
    "publisherDomains": [
      "pitchside.co.uk",
      "football.pitchside.co.uk"
    ],
    "evidenceUrls": [
      "<string>"
    ],
    "notes": "<string>",
    "updatedBy": "<string>"
  },
  "sellsThirdPartyInventory": true,
  "defaultCurrency": "<string>",
  "paymentCurrencies": [
    "<string>"
  ]
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

API key or access token

Body

application/json

name

string

Updated display name

Required string length: 1 - 255

Example:

"Acme Media Network"

publisherDomain

string

Deprecated legacy singular publisher domain. Use businessProfile.publisherDomains / publisher-domain sync state for the storefront publisher-domain set.

Required string length: 1 - 255

plan

enum<string>

Updated plan tier

Available options:

basic

transacting

boolean

Deprecated compatibility alias for the inverse of isPaused. It is not effective transaction availability.

isPaused

boolean

Compatibility-named seller intake hold. True hides product discovery and blocks new media buys and buyer edits; approved unsent buys wait until it is false. It does not pause existing ad-server delivery. New storefronts default to false; effective transaction availability also depends on readiness and archival state.

sellsThirdPartyInventory

boolean

Set to true to also resell third-party inventory from other Interchange storefronts; false to sell only the storefront’s own inventory sources.

defaultCurrency

string

Seller-confirmed settlement currency (ISO-4217). Required before go-live for Interchange-cleared storefronts; never defaulted silently. Direct sales adapter storefronts run by our expert agents skip settlement-currency readiness checks because Interchange does not pay the seller on that path.

Pattern: ^[A-Z]{3}$

Example:

"EUR"

paymentCurrencies

string[]

ISO-4217 currencies this storefront will be paid in (the payout set). A media buy settles in one of these (the primary defaultCurrency is always included). The buyer payment currency is the seller payout currency unless the marketplace accepts the buyer currency via cross-currency FX, in which case the source cost is converted to the buyer currency at the platform spot rate while the source is still paid in one of these currencies. A pricing option may not use a settlement currency outside this set. Empty falls back to defaultCurrency, so a single-currency storefront need not set it. Duplicates are ignored.

Maximum array length: 25

Pattern: ^[A-Z]{3}$

Example:

["USD", "GBP"]

acceptedCountries

string[] | null

Replace the operator-confirmed exhaustive country allowlist used to route briefs. This is acceptance policy, not Media Kit merchandising. Pass null to mark the scope unconfigured.

Required array length: 1 - 249 elements

Pattern: ^[A-Z]{2}$

Example:

["FR"]

acceptsAllCountries

boolean

Set true to accept briefs from every country. Set false with acceptedCountries: null to clear routing scope to unconfigured.

advertisingPolicyDisclosure

enum<string>[]

Business Rules sections to publish as Advertising Policies on the Discovery Card. Empty hides the disclosure. Approval routing, review mode, and revision notes are never published. Read-only for pass-through storefronts, whose policy comes from upstream AdCP capabilities.

Maximum array length: 2

A Business Rules section the seller elects to disclose publicly as Advertising Policies on its Discovery Card.

Available options:

brief_acceptance,

creative_policy

supportedLanguages

string[]

Languages (BCP-47) the co-branded join/signup surface may localize within.

Required string length: 2 - 35

Example:

["nl", "fr", "en"]

operatorDomain

string

Canonical operator domain for AAO registry lookup. Changing it invalidates description, channels, membershipStatus, and website values curated for the prior identity. Resupply valid values in the same request or acknowledge their removal with confirmOperatorDomainProfileReset.

Required string length: 1 - 255

Example:

"scope3.com"

confirmOperatorDomainProfileReset

boolean

Required when changing operatorDomain would clear profile fields curated for the previous identity: description, channels, membershipStatus, or website. Fields explicitly resupplied in the same request are preserved/replaced. Ignored when the domain is unchanged or no populated fields would be cleared.

brandName

string

Brand name resolved from AAO registry

Maximum string length: 255

Example:

"Scope3"

logoUrl

string<uri>

Logo URL resolved from brand.json

Maximum string length: 2048

logoBackground

enum<string> | null

Backdrop the resolved logo is designed for, from brand.json. Drives the storefront card tile color. Pass null to clear.

Available options:

dark-bg,

light-bg,

transparent-bg

membershipStatus

enum<string>

AAO membership tier displayed on the storefront card. Use NONE to hide the badge.

Available options:

AAO_FOUNDING_MEMBER,

AAO_MEMBER,

NONE

regions

string[]

Compatibility write alias for legacy businessProfile.regions merchandising context. It does not route briefs or define Discovery Card country coverage. Prefer businessProfile.regions when maintaining legacy context.

Maximum array length: 64

Pattern: ^[A-Z0-9_-]{2,32}$

Example:

["NL", "BE", "WORLDWIDE"]

description

string | null

Operator-curated description shown on the storefront card. Overrides brand.json when set.

Maximum string length: 2000

channels

enum<string>[]

ADCP channel codes the storefront offers. Surfaced on the storefront card.

Maximum array length: 16

Legacy V2 storefront channel code. Values round-trip unchanged; the Discovery Card projection, Marketplace filters, and outbound AdCP capabilities normalize audio to canonical streaming_audio.

Available options:

display,

olv,

ctv,

social,

audio,

dooh

Example:

["display", "olv", "ctv"]

website

string<uri>

Operator-curated website URL shown on the storefront card. Overrides brand.json when set.

Maximum string length: 2048

demandContactName

string | null

Name of the person at the publisher who fields buyer inquiries (RFPs, prospective briefs, weekly digests). Must be set together with demandContactEmail. Pass null to clear (both fields must be cleared together).

Required string length: 1 - 255

Example:

"Pia Eberhardt"

demandContactEmail

string<email> | null

Email address for the demand contact. Must be set together with demandContactName. Pass null to clear (both fields must be cleared together).

Maximum string length: 320

Pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$

Example:

"pia@nrcmediagroep.com"

capabilities

object

Legacy v2 capability object. All flags remain persisted for compatibility, but the effective offersProductComposition response and runtime behavior are derived from merchandising access and ready Source product paths. V3 publishes the optional deprecated boolean as a typed no-op, strips it before dispatch, and reports it as ignored.

Show child attributes

setupIntent

enum<string>

Record the operator's declared selling intent. This is descriptive state only: it does not change Source product paths or effective capabilities. Both 'sell_through_scope3' and 'third_party_connect' are accepted regardless of current Source types.

Available options:

third_party_connect,

sell_through_scope3

compositionPricing

object

Replace storefront composition pricing settings: fallback pricing percentile plus seller pricing facts extracted from rate cards, media kits, or operator instructions.

Show child attributes

creativeApproval

enum<string>

Operator setting: how creatives buyers submit are handled on ad-server-backed inventory sources. manual queues each for review; auto approves without review. External sales agents and linked Storefronts keep their own approval settings.

Available options:

auto,

manual

mediaBuyApproval

enum<string>

Operator setting: how new media buys are handled on ad-server-backed inventory sources. manual queues each for review; auto lets the buy start without review. External sales agents and linked Storefronts keep their own approval settings.

Available options:

auto,

manual

businessProfile

object | null

Whole-document replacement for the operator-supplied business profile captured during Murph-led setup. New evidence URLs must use HTTP(S); a previously stored legacy URI may be submitted unchanged so read/modify/write clients can round-trip the profile. Pass null to clear.

Show child attributes

confirmCurrencyCatalogImpact

boolean

Required when changing defaultCurrency on a transacting storefront would hide products currently visible to buyers (operator fixed prices are only shown in the storefront's settlement currency). The request is rejected with the affected product count unless this is true. Ignored when the storefront is not transacting or the currency change has no buyer-visible impact.

acknowledgeNoHumanReview

boolean

Required to move creativeApproval or mediaBuyApproval to auto. In auto, work proceeds without human review. Brief Acceptance qualifies product discovery; automatic media-buy creation adds no second evaluator gate. The request is rejected unless this is true. Ignored when tightening to manual, or when the setting is already auto.

Response

Update storefront

Storefront configuration response

storefrontId

string

required

Surrogate id (BIGINT serialized as string)

Example:

"1234"

platformId

string

required

Public-facing slug

Example:

"acme-media"

name

string

required

Display name

Example:

"Acme Media"

publisherDomain

string | null

required

Publisher domain for the storefront's business profile

Example:

"acme.com"

operatorDomain

string | null

required

Canonical operator domain

Example:

"scope3.com"

brandName

string | null

required

Brand name from AAO registry

Example:

"Scope3"

logoUrl

string | null

required

Logo URL from brand.json

membershipStatus

enum<string> | null

required

AAO membership tier. Null when the operator has not set a value.

Available options:

AAO_FOUNDING_MEMBER,

AAO_MEMBER,

NONE

regions

string[]

required

Legacy merchandising-region context projected from businessProfile. This does not govern brief acceptance or Discovery Card country coverage.

acceptedCountries

string[] | null

required

Operator-confirmed exhaustive country allowlist for brief routing. Null means routing scope has not been confirmed.

Pattern: ^[A-Z]{2}$

acceptsAllCountries

boolean

required

Whether the operator explicitly accepts briefs from every country.

advertisingPolicyDisclosure

enum<string>[]

required

Seller-selected Business Rules sections disclosed publicly as Advertising Policies. Empty means no local disclosure.

A Business Rules section the seller elects to disclose publicly as Advertising Policies on its Discovery Card.

Available options:

brief_acceptance,

creative_policy

advertisedCountries

string[]

required

Standard primary countries advertised by backing AdCP sales agents. Authoritative for a pure pass-through Discovery Card; inventory evidence otherwise.

Pattern: ^[A-Z]{2}$

advertisedChannels

string[]

required

Standard primary channels advertised by backing AdCP sales agents. Authoritative for a pure pass-through Discovery Card; inventory evidence otherwise.

description

string | null

required

Operator-curated description (overrides brand.json).

channels

string[]

required

ADCP channel codes the storefront offers.

website

string | null

required

Operator-curated website URL (overrides brand.json).

discoveryCard

object

required

Canonical buyer-visible storefront identity and coverage. This is distinct from Media Kit merchandising inputs and seller policies.

Show child attributes

demandContactName

string | null

required

Demand contact name. Null when the operator has not set one.

demandContactEmail

string | null

required

Demand contact email. Null when the operator has not set one.

operatorDomainVerified

boolean

required

Whether the operator domain has been verified (email match or manual KYC)

routingMode

enum<string>

required

Which backend function the buyer-facing storefront dispatches to: the Merchandising Agent or an expert-run adapter.

Available options:

CHEF,

ADAPTER

adapterProviderType

enum<string> | null

required

Expert-run adapter provider when routingMode is ADAPTER; null otherwise.

Available options:

amazon,

audiostack,

elevenlabs,

fal,

gemini,

google,

linkedin,

meta,

openai,

pinterest,

reddit,

snap,

spotify,

tiktok,

veo

adapterSourceKind

enum<string> | null

required

Adapter role when routingMode is ADAPTER; null otherwise.

Available options:

sales,

creative,

signals,

measurement,

optimization,

composite

adapterCredentialMode

enum<string> | null

required

Adapter credential mode when routingMode is ADAPTER; null otherwise.

Available options:

BYOK

plan

enum<string>

required

Storefront plan tier

Available options:

basic

transacting

boolean

required

Deprecated compatibility projection of !isPaused; not proof that the storefront currently satisfies readiness.

isPaused

boolean

required

Compatibility-named seller intake hold. True blocks discovery, new buys, and buyer edits but does not pause existing delivery. False is neutral; it does not by itself make the storefront live.

archivedAt

string<date-time> | null

required

When the storefront was archived (read-only thereafter). Null for non-archived storefronts.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

displayStatus

enum<string>

required

Deprecated stored-control display status. This is never proof that the storefront can transact; use the readiness projection.

Available options:

configuring,

transacting,

archived,

neutral,

paused

capabilities

object

required

Effective buyer-facing AdCP capabilities. Product composition derives from merchandising access and ready Source product paths; it is not locked to the legacy configured flag.

Show child attributes

configuredCapabilities

object

required

Persisted operator capability flags before source-topology derivation. Compare this field for declarative writes; capabilities is the effective buyer-facing projection.

Show child attributes

compositionPricing

object

required

Composition pricing settings: fallback pricing percentile plus seller pricing facts. Separate from Scope3 contract/billing rate cards.

Show child attributes

creativeApproval

enum<string>

required

Stored operator setting for creative submissions. It only affects ad-server-backed or product-composition storefronts; pass-through external-agent storefronts ignore this because their sources own review.

Available options:

auto,

manual

mediaBuyApproval

enum<string>

required

Stored operator setting for new media buys. It only affects ad-server-backed or product-composition storefronts; pass-through external-agent storefronts ignore this because Interchange does not insert an approval queue.

Available options:

auto,

manual

capabilitiesLocked

boolean

required

Legacy topology projection: true when the storefront has at least one active ad-server-backed inventory source (executionType=MANAGED_SALES_AGENT). Product composition is now Source-derived, so this value does not authorize or lock capability writes.

advertiseAsAgent

boolean

required

Derived: true when the Storefront has an active Inventory Source, an active embedded Sales Agent, adapter routing, or an advertised Storefront-owned capability. Every active Source remains behind the buyer-facing Storefront AdCP endpoint, including COMPOSING-only Sources.

createdAt

string<date-time>

required

Creation timestamp (ISO 8601)

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

updatedAt

string<date-time>

required

Last update timestamp (ISO 8601)

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

businessProfile

object | null

required

Operator-supplied business profile captured during Murph-led setup. Null when the operator has not shared one.

Show child attributes

logoBackground

enum<string> | null

Backdrop the logo is designed for, from brand.json. Null or absent when unknown; the storefront card falls back to a dark tile.

Available options:

dark-bg,

light-bg,

transparent-bg

setupIntent

enum<string> | null

Declared selling intent from the first onboarding question, or null when the operator has not been asked yet. A record of the operator's answer — what the storefront exposes is always the derived capabilities.

Available options:

third_party_connect,

sell_through_scope3

sellsThirdPartyInventory

boolean

Operator toggle: when true, the storefront also resells third-party inventory from other Interchange storefronts (composition draws from the marketplace in addition to its own sources). When false/absent (default), the storefront sells only its own inventory sources.

defaultCurrency

string | null

Seller-confirmed primary settlement currency (ISO-4217). Null until confirmed; required before go-live for Interchange-cleared storefronts. Direct sales adapter storefronts run by our expert agents skip settlement-currency readiness checks because Interchange does not pay the seller on that path.

paymentCurrencies

string[]

ISO-4217 currencies the storefront will be paid in (the payout set). A media buy settles in one of these. Empty falls back to defaultCurrency. The marketplace may additionally accept buyer currencies outside this set via cross-currency FX, converting each source cost to the buyer currency at the platform spot rate.

⌘I