Skip to main content
PATCH
Update Retailer
Connector tool: update_retailer

Access

Call this endpoint with your API key, or with a Subtotal: For Brands OAuth token that includes retailers:write. A token without retailers:write receives 403 insufficient_scope. Partner app tokens don’t include it.

Enable or disable a retailer

Disabling removes your configuration for the retailer. Links you’ve already shared stop working, and re-enabling issues a new link_url with link_visibility reset to everyone.
link_visibility sets who sees the retailer on the Subtotal Link retailer-selection page: everyone, restricted (only consumers matching link_audience), or hidden. The retailer’s link_url works regardless of visibility.
  • Fields you omit are left unchanged.
  • link_audience replaces the stored lists. Send both lists to keep entries you want.
  • restricted needs at least one email or domain, counting lists already stored.
  • Link settings need the retailer enabled. Send "enabled": true in the same request to enable and configure it at once.

Errors

Authorizations

Authorization
string
header
required

Partner OAuth: send Authorization: Bearer <access_token>, an OAuth access token from Subtotal's authorization server with the scope this endpoint needs.

Path Parameters

retailer_id
string
required

Body

application/json

Retailer update body. Every field is optional; an omitted field is left unchanged.

enabled
boolean | null

true enables the retailer for the client; false disables it. Disabling removes the client's configuration for the retailer: a later re-enable issues a new link_url and resets link_visibility to everyone.

Who sees the retailer on the Subtotal Link retailer-selection page: everyone | restricted (only consumers matching link_audience) | hidden. Requires the retailer to be enabled.

Available options:
everyone,
restricted,
hidden
Example:

"restricted"

Replaces the stored allow-lists used when link_visibility is restricted. Requires the retailer to be enabled.

Response

Successful Response

One retailer, with whether it's enabled for this client.

retailer_id
string
required

Retailer slug — the exact value passed to the retailers[] filter across surfaces.

Example:

"walmart"

name
string
required

Retailer display name.

Example:

"Walmart"

images
RetailerImages · object
required

Logos and icons for the retailer.

status
string
required

Platform status: active | limited | inactive.

Example:

"active"

enabled
boolean
required

Whether this retailer is enabled for this client.

URL to launch Subtotal Link for the retailer. Present only when the retailer is enabled.

Example:

"https://link.subtotal.com/a1b2c3d4"

Who sees the retailer on the Subtotal Link retailer-selection page: everyone | restricted (only consumers matching link_audience) | hidden. link_url works regardless. Present only when the retailer is enabled.

Available options:
everyone,
restricted,
hidden
Example:

"everyone"

Allow-lists applied when link_visibility is restricted. Present only when the retailer is enabled.