Update inventory source

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

import requests

url = "https://api.interchange.io/api/v2/storefront/inventory-sources/{sourceId}"

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/inventory-sources/{sourceId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "<string>",
  "sourceId": "<string>",
  "name": "<string>",
  "agentId": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "connectionType": "AD_SERVER",
  "adServerProvider": "citrusad",
  "endpointUrl": "<string>",
  "description": "<string>",
  "authConfigured": true,
  "oauth": {
    "authorizationUrl": "<string>",
    "agentId": "<string>",
    "agentName": "<string>"
  },
  "managedSa": {
    "connectionId": "<string>",
    "tenantId": "<string>",
    "adServer": {
      "type": "google_ad_manager",
      "networkCode": "12345678"
    },
    "lastError": "<string>",
    "lastErrorCode": "<string>",
    "lastTestedAt": "2023-11-07T05:31:56Z",
    "provisionedAt": "2023-11-07T05:31:56Z",
    "deactivatedAt": "2023-11-07T05:31:56Z"
  },
  "linkedStorefront": {
    "buyer": {
      "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>"
      ]
    },
    "seller": {
      "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>"
      ]
    },
    "requestMessage": "<string>",
    "responseMessage": "<string>",
    "requestedAt": "2023-11-07T05:31:56Z",
    "respondedAt": "2023-11-07T05:31:56Z",
    "cancelledAt": "2023-11-07T05:31:56Z"
  },
  "isAdapterSource": true,
  "agentCapabilityUid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "productModeReasons": [],
  "productPaths": [
    {
      "ready": true,
      "reasons": []
    }
  ]
}

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

inventory-sources

{sourceId}

Update inventory source

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

import requests

url = "https://api.interchange.io/api/v2/storefront/inventory-sources/{sourceId}"

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/inventory-sources/{sourceId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "<string>",
  "sourceId": "<string>",
  "name": "<string>",
  "agentId": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "connectionType": "AD_SERVER",
  "adServerProvider": "citrusad",
  "endpointUrl": "<string>",
  "description": "<string>",
  "authConfigured": true,
  "oauth": {
    "authorizationUrl": "<string>",
    "agentId": "<string>",
    "agentName": "<string>"
  },
  "managedSa": {
    "connectionId": "<string>",
    "tenantId": "<string>",
    "adServer": {
      "type": "google_ad_manager",
      "networkCode": "12345678"
    },
    "lastError": "<string>",
    "lastErrorCode": "<string>",
    "lastTestedAt": "2023-11-07T05:31:56Z",
    "provisionedAt": "2023-11-07T05:31:56Z",
    "deactivatedAt": "2023-11-07T05:31:56Z"
  },
  "linkedStorefront": {
    "buyer": {
      "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>"
      ]
    },
    "seller": {
      "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>"
      ]
    },
    "requestMessage": "<string>",
    "responseMessage": "<string>",
    "requestedAt": "2023-11-07T05:31:56Z",
    "respondedAt": "2023-11-07T05:31:56Z",
    "cancelledAt": "2023-11-07T05:31:56Z"
  },
  "isAdapterSource": true,
  "agentCapabilityUid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "productModeReasons": [],
  "productPaths": [
    {
      "ready": true,
      "reasons": []
    }
  ]
}

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

Path Parameters

sourceId

string

required

Inventory source ID

Minimum string length: 1

Body

application/json

Request body for updating an inventory source. Only the documented fields are writable. Unknown v2 extension keys are tolerated and ignored solely for legacy client compatibility.

name

string

Updated display name

Required string length: 1 - 255

executionType

enum<string>

AGENT inventory sources can be updated here. MANAGED_SALES_AGENT and MODULAR_SOURCE lifecycle transitions happen through dedicated flows; LINKED_STOREFRONT sources are resolved at runtime from the ambient wholesale pool and have no lifecycle endpoint. Storefront-level ADAPTER dispatch is configured on the storefront, not as an inventory source.

Available options:

AGENT

status

enum<string>

Updated source status (PENDING → ACTIVE, ACTIVE → DISABLED)

Available options:

PENDING,

ACTIVE,

DISABLED

description

string

Updated agent description

Maximum string length: 2000

endpointUrl

string<uri>

Updated agent endpoint URL

Maximum string length: 2048

protocol

enum<string>

Updated agent protocol

Available options:

MCP,

A2A

authenticationType

enum<string>

Updated agent authentication type

Available options:

API_KEY,

NO_AUTH,

JWT,

OAUTH,

BASIC_AUTH

auth

object

Updated authentication credentials. Omit to keep existing credentials. For BASIC_AUTH agents, use { type: "basic", username, password }.

Option 1
Option 2
Option 3
Option 4

Show child attributes

oauthAudience

string<uri>

OAuth audience / resource indicator for OAUTH agents (the protected-resource URI the agent gateway validates). Setting it re-mints the token with this aud claim and returns a fresh authorization URL to re-consent. Sent as both Auth0 audience and RFC 8707 resource.

Maximum string length: 2048

Example:

"https://platform.example.com"

Response

Update inventory source

Inventory source response

string

required

Globally unique surrogate id (BIGINT serialized as string). Use this when acting on rows the caller does not own (e.g. a seller approving an inbound link).

sourceId

string

required

Storefront-scoped identifier — unique within the row owner's storefront. Use this for actions on the caller's own rows; use id for cross-customer actions.

name

string

required

Display name

executionType

enum<string>

required

Execution type

Available options:

AGENT,

MANAGED_SALES_AGENT,

LINKED_STOREFRONT,

MODULAR_SOURCE

status

enum<string>

required

Source lifecycle status

Available options:

PENDING,

ACTIVE,

DISABLED

agentId

string | null

required

Linked agent ID (when executionType is agent)

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

connectionType

enum<string>

Public connection family for a preconfigured ad-server source. Omitted for other inventory-source families.

Available options:

AD_SERVER

adServerProvider

enum<string>

Ad-server provider for a preconfigured ad-server source. Omitted for other inventory-source families.

Available options:

citrusad

type

enum<string> | null

Agent type

Available options:

SALES,

SIGNAL,

CREATIVE,

OUTCOME

endpointUrl

string | null

Agent endpoint URL

protocol

enum<string> | null

Agent protocol

Available options:

MCP,

A2A

description

string | null

Agent description

authenticationType

enum<string> | null

Agent authentication type

Available options:

API_KEY,

NO_AUTH,

JWT,

OAUTH,

BASIC_AUTH

authConfigured

boolean

Whether the agent has authentication configured

oauth

object

OAuth authorization info (for OAUTH agents)

Show child attributes

managedSa

object | null

Embedded-sales-agent state when executionType is MANAGED_SALES_AGENT. Null/absent for external AGENT-type sources. The current REST surface (/api/v2/storefront/esa/...) remains the way to mutate this state today; subsequent PRs will move those actions under /api/v2/storefront/inventory-sources/:sourceId/....

Show child attributes

linkedStorefront

object | null

Always null. Storefront interchange runs through the ambient wholesale pool: a curator discovers any LISTED storefront’s wholesale inventory automatically, with no per-counterparty link to establish. Retained for response-shape stability.

Show child attributes

reportingType

enum<string> | null

How the underlying agent reports delivery (WEBHOOK, BUCKET, POLLING). Mirrors the AdCP-spec values used when connecting the source. Projected from storefront_agent_source; null for non-AGENT sources.

Available options:

WEBHOOK,

BUCKET,

POLLING

reportingPollingCadence

enum<string> | null

Polling cadence (DAILY, MONTHLY) — only meaningful when reportingType is POLLING. Projected from storefront_agent_source; null for non-AGENT sources or non-polling reporting.

Available options:

DAILY,

MONTHLY

isAdapterSource

boolean

True when this source is routed through an official Scope3-hosted adapter (storefront routing_mode is ADAPTER and the source_id matches the configured adapter). When true, the UI labels this as an official adapter rather than a generic external sales agent.

agentCapabilityUid

string<uuid> | null

Explicit reusable SALES Agent capability connected to this Source. Null means the Source requires governed connection reconciliation; endpoint similarity is never used.

Pattern:

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

declaredAgentProductMode

enum<string> | null

The backing Agent completeness contract. Managed ESA and initial modular Sources project their fixed WHOLESALE contract.

Available options:

WHOLESALE,

COMPOSING,

BOTH

bindingProductMode

enum<string> | null

Source product-path selection only when the Agent declares BOTH; null for single-mode Agents.

Available options:

WHOLESALE,

COMPOSING,

BOTH

effectiveProductMode

enum<string> | null

Effective mode for new discovery. Null when the explicit Agent connection or declaration is unresolved.

Available options:

WHOLESALE,

COMPOSING,

BOTH

productModeReasons

enum<string>[]

Bounded reconciliation reasons when effective mode cannot be resolved.

Available options:

SOURCE_NOT_ACTIVE,

AGENT_BINDING_MISSING,

AGENT_MODE_UNDECLARED,

BOTH_SELECTION_REQUIRED,

MERCHANDISING_ACCESS_INACTIVE,

WHOLESALE_CATALOG_NOT_READY

productPaths

object[]

Readiness for the Agent-supplied and Storefront-built product paths. BOTH exposes both entries; neither path silently replaces the other.

Show child attributes

⌘I