Update inventory source

PUT /api/v2/storefront/inventory-sources/{sourceId} Updates an AGENT inventory source. Updates are partial — send any subset of fields. Status transitions manage the linked agent lifecycle. MANAGED_SALES_AGENT, LINKED_STOREFRONT, and MODULAR_SOURCE lifecycles use their dedicated flows instead.

Request

curl -X PUT https://api.interchange.io/api/v2/storefront/inventory-sources/retail-network-agent \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Retail Network Agent (Primary)",
    "status": "ACTIVE",
    "description": "On-site display and CTV inventory"
  }'

{
  "authenticationType": "API_KEY",
  "auth": { "type": "bearer", "token": "<NEW_SOURCE_API_KEY>" }
}

{
  "authenticationType": "OAUTH",
  "oauthAudience": "https://platform.retail-network.example.com"
}

Parameters

Field	Type	Required	Notes
`sourceId`	string (path)	Yes	Storefront-scoped inventory source ID
`name`	string	No	Display name (1–255 chars)
`executionType`	enum	No	`AGENT` only
`status`	enum	No	`PENDING`, `ACTIVE`, or `DISABLED`
`description`	string	No	Agent description (max 2000)
`endpointUrl`	string (uri)	No	Updated executable URL from the selected AAO `authorized_agents[].url` entry (max 2048). A publisher `adagents.json` URL or `authoritative_location` is not an agent endpoint
`protocol`	enum	No	`MCP` or `A2A`
`authenticationType`	enum	No	`API_KEY`, `JWT`, `BASIC_AUTH`, `NO_AUTH`, or `OAUTH`
`auth`	object	No	Updating `auth` rotates the stored credential. Omit to keep existing credentials, and always omit for `OAUTH` and `NO_AUTH`. OAuth credentials are managed by the consent flow; use `oauthAudience` to change its resource and start reauthorization. Same API-key / Basic / JWT shapes as create
`oauthAudience`	string (public URI)	No	Compatibility override for an `OAUTH` agent whose gateway validates a resource-specific audience. Interchange stores it and sends it as both Auth0 `audience` and RFC 8707 `resource`. When discovery and flow storage succeed, the response includes a fresh `oauth.authorizationUrl`; the operator must complete that consent flow before the new token can be used.

Allowed status transitions: PENDING → ACTIVE, PENDING → DISABLED, and ACTIVE ↔ DISABLED. A source cannot transition back to PENDING. Setting status: ACTIVE requires the backing agent to be authenticated. AAO compliance is surfaced as an advisory signal, not an activation blocker.

Response

200 OK with the updated InventorySourceResponse:

{
  "id": "900123456789",
  "sourceId": "retail-network-agent",
  "name": "Retail Network Agent (Primary)",
  "executionType": "AGENT",
  "status": "ACTIVE",
  "agentId": "agent_01HX...",
  "type": "SALES",
  "endpointUrl": "https://agent.retail-network.example.com/mcp",
  "protocol": "MCP",
  "authenticationType": "API_KEY",
  "authConfigured": true,
  "isAdapterSource": false,
  "createdAt": "2026-04-25T12:05:00Z",
  "updatedAt": "2026-05-02T09:14:00Z"
}

When oauthAudience is supplied and OAuth flow creation succeeds, the response also includes oauth.authorizationUrl. Redirect the operator there and complete consent; the stored audience does not make the new token usable by itself. If the update succeeds without an oauth field, the audience is stored but a temporary discovery or flow-storage failure prevented consent from starting. Retry the same update to request a fresh URL.

Errors

400 VALIDATION_ERROR — invalid status transition, malformed auth, auth supplied for an OAUTH or NO_AUTH source, a non-public endpointUrl or oauthAudience, an endpointUrl that names an adagents.json identity document, or no fields supplied.
401 UNAUTHORIZED — missing or invalid API key.
404 NOT_FOUND — no source with this sourceId on your storefront.

See Errors for the full error contract.

Inventory source tasks

All operations

Inventory sources overview

Concepts and lifecycle

Get inventory source

Read one source by ID

Delete inventory source

Remove a source

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Update inventory source

Request

Parameters

Response

Errors

Inventory source tasks

Inventory sources overview

Get inventory source

Delete inventory source

​Request

​Parameters

​Response

​Errors

​Related

Inventory source tasks

Inventory sources overview

Get inventory source

Delete inventory source

Request

Parameters

Response

Errors

Related