# Upsert checkout styling for a merchant and one or more countries

> `PUT https://api.kustom.co/config/checkout/v1/config/checkoutStyling`

## Parameters

- `X-merchant-id` (string, header) — Merchant identifier
- `countries` (array<string>, query) — ISO 3166-1 alpha-2 country codes (omit for merchant-level default)

## Request body

`application/json`

- `checkoutStyling` (object)
  - `surface` (string) — Background colour of surfaces, as a 6-digit hex colour.
  - `onSurface` (string) — Primary text/content colour shown on surfaces, as a 6-digit hex colour.
  - `onSurfaceMuted` (string) — Muted/secondary content colour shown on surfaces, as a 6-digit hex colour.
  - `primary` (string) — Primary brand/action colour, as a 6-digit hex colour.
  - `onPrimary` (string) — Content colour shown on top of the primary colour, as a 6-digit hex colour.
- `changeReason` (string) — Human-readable reason for the change, stored in the change history.
- `updatedBy` (string) — Identifier of the user or system making the change.

### Example request

```json
{
  "checkoutStyling": {
    "surface": "#FFFFFF",
    "onSurface": "#1A1A1A",
    "onSurfaceMuted": "#6B7280",
    "primary": "#2563EB",
    "onPrimary": "#FFFFFF"
  },
  "changeReason": "Apply spring campaign brand colours",
  "updatedBy": "ops@acme.com"
}
```

## Responses

### 200

OK

`*/*`

- `merchantId` (string) — Merchant identifier.
- `country` (string) — ISO 3166-1 alpha-2 country code, or null for the merchant-level default.
- `checkoutStyling` (object)
  - `surface` (string) — Background colour of surfaces, as a 6-digit hex colour.
  - `onSurface` (string) — Primary text/content colour shown on surfaces, as a 6-digit hex colour.
  - `onSurfaceMuted` (string) — Muted/secondary content colour shown on surfaces, as a 6-digit hex colour.
  - `primary` (string) — Primary brand/action colour, as a 6-digit hex colour.
  - `onPrimary` (string) — Content colour shown on top of the primary colour, as a 6-digit hex colour.
- `revision` (integer) — Monotonically increasing revision of this configuration value.
- `updatedBy` (string) — Identifier of the user or system that last updated the value.
- `updatedAt` (string) — Timestamp of the last update.

```json
[
  {
    "merchantId": "M123456",
    "country": "SE",
    "checkoutStyling": {
      "surface": "#FFFFFF",
      "onSurface": "#1A1A1A",
      "onSurfaceMuted": "#6B7280",
      "primary": "#2563EB",
      "onPrimary": "#FFFFFF"
    },
    "revision": 3,
    "updatedBy": "kustom-external-api",
    "updatedAt": "2026-06-22T14:30:00Z"
  }
]
```

### 400

Schema validation failure

`*/*`

- `merchantId` (string) — Merchant identifier.
- `country` (string) — ISO 3166-1 alpha-2 country code, or null for the merchant-level default.
- `checkoutStyling` (object)
  - `surface` (string) — Background colour of surfaces, as a 6-digit hex colour.
  - `onSurface` (string) — Primary text/content colour shown on surfaces, as a 6-digit hex colour.
  - `onSurfaceMuted` (string) — Muted/secondary content colour shown on surfaces, as a 6-digit hex colour.
  - `primary` (string) — Primary brand/action colour, as a 6-digit hex colour.
  - `onPrimary` (string) — Content colour shown on top of the primary colour, as a 6-digit hex colour.
- `revision` (integer) — Monotonically increasing revision of this configuration value.
- `updatedBy` (string) — Identifier of the user or system that last updated the value.
- `updatedAt` (string) — Timestamp of the last update.

```json
[
  {
    "merchantId": "M123456",
    "country": "SE",
    "checkoutStyling": {
      "surface": "#FFFFFF",
      "onSurface": "#1A1A1A",
      "onSurfaceMuted": "#6B7280",
      "primary": "#2563EB",
      "onPrimary": "#FFFFFF"
    },
    "revision": 3,
    "updatedBy": "kustom-external-api",
    "updatedAt": "2026-06-22T14:30:00Z"
  }
]
```