> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subtotal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Retailer

> Update a retailer for the client. Every field is optional and omitted fields are unchanged: `enabled` turns the retailer on or off; `link_visibility` and `link_audience` set who sees it on the Subtotal Link selection page (`link_audience` replaces the stored allow-lists). Link settings need the retailer enabled, already or in the same request. Idempotent; returns the retailer row after the update. Disabling removes the client's configuration for the retailer: a later re-enable issues a new link_url and resets link_visibility to everyone.

## Access

Call this endpoint with your API key, or with a Subtotal Data MCP connector's OAuth token that includes `retailers:write`. A token without `retailers:write` receives `403 insufficient_scope`. [Partner app](/docs/partner-apps/introduction#fixed-permissions) tokens don't include it.

## Enable or disable a retailer

```bash theme={null}
curl --request PATCH 'https://api.subtotal.com/retailers/walmart' \
  --header "x-api-key: $SUBTOTAL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"enabled": true}'
```

<Warning>
  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`.
</Warning>

## Control who sees a retailer in Subtotal Link

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

```bash theme={null}
curl --request PATCH 'https://api.subtotal.com/retailers/walmart' \
  --header "x-api-key: $SUBTOTAL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "link_visibility": "restricted",
    "link_audience": {"allowed_emails": ["tester@example.com"], "allowed_domains": ["example.com"]}
  }'
```

* 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

| Status | When                                                                                                                                         |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `404`  | Unknown `retailer_id`, or Link settings for a retailer that isn't enabled                                                                    |
| `422`  | Invalid body: an empty body, unknown fields, invalid emails or domains, `restricted` with no audience, or Link settings sent while disabling |


## OpenAPI

````yaml patch /retailers/{retailer_id}
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers: []
security: []
paths:
  /retailers/{retailer_id}:
    patch:
      tags:
        - merchant
      summary: Update Retailer
      description: >-
        Update a retailer for the client. Every field is optional and omitted
        fields are unchanged: `enabled` turns the retailer on or off;
        `link_visibility` and `link_audience` set who sees it on the Subtotal
        Link selection page (`link_audience` replaces the stored allow-lists).
        Link settings need the retailer enabled, already or in the same request.
        Idempotent; returns the retailer row after the update. Disabling removes
        the client's configuration for the retailer: a later re-enable issues a
        new link_url and resets link_visibility to everyone.
      operationId: update_retailer_retailers__retailer_id__patch
      parameters:
        - name: retailer_id
          in: path
          required: true
          schema:
            type: string
            title: Retailer Id
        - name: authorization
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Authorization
        - name: x-api-key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRetailerRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetailerListItem'
        '404':
          description: >-
            Unknown retailer_id, or Link settings for a retailer that isn't
            enabled.
        '422':
          description: Invalid body, e.g. restricted visibility with no audience.
components:
  schemas:
    UpdateRetailerRequest:
      properties:
        enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Enabled
          description: >-
            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.
        link_visibility:
          anyOf:
            - $ref: '#/components/schemas/LinkVisibility'
            - type: 'null'
          description: >-
            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.
          examples:
            - restricted
        link_audience:
          anyOf:
            - $ref: '#/components/schemas/LinkAudience'
            - type: 'null'
          description: >-
            Replaces the stored allow-lists used when link_visibility is
            restricted. Requires the retailer to be enabled.
      additionalProperties: false
      type: object
      title: UpdateRetailerRequest
      description: >-
        The shared retailer update body (ENG-2121), used by every retailer
        update entry point.


        Every field is optional; an omitted field is left unchanged.
    RetailerListItem:
      properties:
        retailer_id:
          type: string
          title: Retailer Id
          description: >-
            Retailer slug — the exact value passed to the `retailers[]` filter
            across surfaces.
          examples:
            - walmart
        name:
          type: string
          title: Name
          description: Retailer display name.
          examples:
            - Walmart
        images:
          $ref: '#/components/schemas/RetailerImages'
          description: Logos and icons for the retailer.
        status:
          type: string
          title: Status
          description: 'Platform status: active | limited | inactive.'
          examples:
            - active
        enabled:
          type: boolean
          title: Enabled
          description: >-
            Whether this retailer is enabled for this client (a ClientMerchants
            row exists).
        link_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Link Url
          description: >-
            URL to launch Subtotal Link for the retailer. Present only when the
            retailer is enabled.
          examples:
            - https://link.subtotal.com/a1b2c3d4
        link_visibility:
          anyOf:
            - $ref: '#/components/schemas/LinkVisibility'
            - type: 'null'
          description: >-
            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.
          examples:
            - everyone
        link_audience:
          anyOf:
            - $ref: '#/components/schemas/RetailerLinkAudience'
            - type: 'null'
          description: >-
            Allow-lists applied when `link_visibility` is restricted. Present
            only when the retailer is enabled.
      type: object
      required:
        - retailer_id
        - name
        - images
        - status
        - enabled
      title: RetailerListItem
      description: One annotated retailer row of the discovery contract.
    LinkVisibility:
      type: string
      enum:
        - everyone
        - restricted
        - hidden
      title: LinkVisibility
    LinkAudience:
      properties:
        allowed_emails:
          items:
            type: string
          type: array
          maxItems: 100
          title: Allowed Emails
        allowed_domains:
          items:
            type: string
          type: array
          maxItems: 100
          title: Allowed Domains
      additionalProperties: false
      type: object
      title: LinkAudience
    RetailerImages:
      properties:
        logo:
          $ref: '#/components/schemas/ImageThemes'
        icon:
          $ref: '#/components/schemas/ImageThemes'
      type: object
      required:
        - logo
        - icon
      title: RetailerImages
    RetailerLinkAudience:
      properties:
        allowed_emails:
          items:
            type: string
          type: array
          title: Allowed Emails
          description: Consumer emails allowed to see the retailer.
        allowed_domains:
          items:
            type: string
          type: array
          title: Allowed Domains
          description: Consumer email domains allowed to see it.
          examples:
            - - example.com
      type: object
      title: RetailerLinkAudience
      description: Consumer allow-lists applied when `link_visibility` is restricted.
    ImageThemes:
      properties:
        light:
          type: string
          title: Light
        dark:
          type: string
          title: Dark
      type: object
      required:
        - light
        - dark
      title: ImageThemes

````