Update storefront settings

PATCH /rest/v1/storefront

Only the listed fields are written; other top-level keys are ignored (payment keys and the URL slug are set up in the dashboard). Every value is checked first: an invalid one, or an unknown key inside announcement, return_policy or shipping, answers 422 with its param (e.g. announcement.text, shipping.zones[0].countries[1]) and nothing is written. announcement and return_policy can be sent partially (merged onto the saved values); shipping replaces the zones. An unknown theme is a 422 (the plan check comes after). Required scope: storefront:write.

Authorization

apiKey

AuthorizationBearer <token>

Authorization: Bearer nbl_live_... (or nbl_test_... for test mode). Test-mode writes are validated and simulated but never persisted and never touch channels; simulated results are marked simulated.

In: header

Header Parameters

Idempotency-Key?string

Unique client-generated key (max 255 chars), stored 24h.

Lengthlength <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

theme?|

Theme slug; empty or null = the storefront default. Plan rules apply (plan_upgrade_required).

Value in

"sardinia"
"okinawa"
"tenerife"
"manhattan"
"iceland"
"madeira"
""
null

announcement?|

The announcement bar. In PATCH, send only the fields that change; any other key is a 422.

custom_domain?|

A domain name (e.g. shop.example.com); empty or null removes it.

logo?|

An http(s) image URL; empty or null removes it.

return_policy?|

Returns (also sent to Google Merchant Center). In PATCH, send only the fields that change.

shipping?|

Either worldwide_free: true, or 1 to 10 zones (a PATCH replaces all the zones).

address?string|null

show_channels?boolean

visible_channels?array<string>|

Channels shown on product cards; empty or null = all.

show_chat?boolean

out_of_stock?boolean

Show sold-out products on the storefront.

ai_discovery?boolean

product_image_display?string

fill crops photos to the frame, fit shows the whole photo.

Value in

"fill"
"fit"

contact_email?|

Empty or null clears it.

Formatemail

Response Body

`application/json`

curl -X PATCH "https://example.com/storefront" \  -H "Content-Type: application/json" \  -d '{}'

{  "object": "storefront",  "name": "string",  "slug": "string",  "theme": "string",  "announcement": {    "enabled": true,    "message": "string",    "link": "string",    "mode": "auto"  },  "custom_domain": "string",  "logo": "string",  "return_policy": {    "days": 30,    "who_pays": "buyer"  },  "shipping": {    "worldwide_free": true,    "zones": [      {        "id": "string",        "name": "Europe",        "enabled": true,        "countries": [          "IT",          "FR",          "DE"        ],        "free": false,        "pricing": {          "light": 0,          "heavy": 0,          "additional": 0        },        "free_over": 0,        "heavier_than": {          "value": 0,          "unit": "oz"        },        "larger_than": {          "value": 0,          "unit": "in3"        },        "pickup": {          "enabled": true,          "note": "string"        }      }    ]  },  "address": "string",  "show_channels": true,  "visible_channels": [    "string"  ],  "show_chat": true,  "out_of_stock": true,  "ai_discovery": true,  "product_image_display": "fill",  "contact_email": "string",  "payments": {    "stripe": true,    "paypal": true  },  "simulated": true}

Last updated on October 18, 2026

Need help?

Email us and a human replies, usually within one business day.

Email us API status

Authorization

Header Parameters

Request Body

Response Body

200application/json

422application/json

`application/json`

`application/json`