Patch storefront capabilities

curl --request PATCH \
  --url https://api.interchange.io/api/v2/storefront \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "capabilities": {
    "offersCreativeReview": true,
    "offersCampaignApproval": true,
    "offersProductComposition": true
  }
}
'

import requests

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

payload = { "capabilities": {
        "offersCreativeReview": True,
        "offersCampaignApproval": True,
        "offersProductComposition": True
    } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

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

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": {}
  }
}

PATCH

storefront

Patch storefront capabilities

curl --request PATCH \
  --url https://api.interchange.io/api/v2/storefront \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "capabilities": {
    "offersCreativeReview": true,
    "offersCampaignApproval": true,
    "offersProductComposition": true
  }
}
'

import requests

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

payload = { "capabilities": {
        "offersCreativeReview": True,
        "offersCampaignApproval": True,
        "offersProductComposition": True
    } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

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

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

Request body for patching storefront capability flags (creative review, campaign approval, product composition) and/or recording the declared selling intent.

capabilities

object

Patch one or more capability flags; omitted flags are left unchanged. Rejected with a VALIDATION error if the storefront is locked (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 also passed, applies the matching preset: 'sell_through_scope3' turns product composition on; 'third_party_connect' turns all flags off (clean pass-through). Rejected on storefronts with ad-server-backed sources.

Available options:

third_party_connect,

sell_through_scope3

Response

Patch storefront capabilities

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.

Create storefront Get Demo Storefront

⌘I