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>"
  ],
  "description": "<string>",
  "channels": [
    "<string>"
  ],
  "website": "<string>",
  "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
  },
  "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>"
  ],
  "description": "<string>",
  "channels": [
    "<string>"
  ],
  "website": "<string>",
  "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
  },
  "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

Seller-owned pause override. New storefronts default to false; effective transaction availability is derived from pause, 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"]

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

Required string length: 1 - 255

Example:

"scope3.com"

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 businessProfile.regions, projected onto the storefront card and qualification path. Prefer businessProfile.regions. When both fields are sent they must match. Mix of ISO 3166-1 alpha-2 country codes and group codes (WORLDWIDE, EMEA, NORAM, LATAM, APAC, EU).

Maximum array length: 64

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

Example:

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

description

string

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

ADCP channel code. olv is "online video"; the full set is display, olv, ctv, social, audio, dooh.

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 demand signals (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

Patch one or more capability flags. Rejected with VALIDATION error if the storefront is locked because it has ad-server-backed inventory sources and the patch would turn any capability off.

Show child attributes

setupIntent

enum<string>

Record the operator's declared selling intent. Unless capabilities is patched explicitly in the same request, this applies the matching preset: 'sell_through_scope3' turns product composition on; 'third_party_connect' turns all capability flags off (clean pass-through). Rejected with VALIDATION error if set to 'third_party_connect' on a storefront with ad-server-backed inventory sources — an embedded sales agent is not a pass-through.

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

Operator-supplied business profile captured during Murph-led setup. 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.

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

Current Business Profile regions projected for storefront-card and qualification consumers, with the legacy regions column used only when no profile regions exist.

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).

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

Seller-owned pause override. 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

Which AdCP capabilities the storefront advertises. Locked on for ad-server-backed storefronts; opt-in for third-party.

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

True when the storefront has at least one ad-server-backed inventory source (executionType=MANAGED_SALES_AGENT). Locked storefronts reject capability writes that would turn any capability off.

advertiseAsAgent

boolean

required

Derived: capabilitiesLocked || any(capabilities). When true, the storefront exposes itself as an AdCP agent and buyers should call the storefront URL. When false, the storefront is not advertised as a public agent; pass-through behavior is handled by the storefront wrapper when a buyer call reaches it.

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.

Get storefront Create storefront

⌘I