comecerodocs
Settings

Update storefront settings

POST
/settings/storefront

Changes the storefront document, its switch, or both. Groups you send are merged into the saved document. Custom CSS and JavaScript, and the switch, need a trusted token of the account owner. One change is saved at a time: if another is being saved, you get 409 and can try again. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Secret and trusted tokens may call it when their permissions include settings_storefront. Limited tokens may not.

Authorization

headerAuthorizationBearer <token>

A secret, trusted or limited token. See Authentication.

Query Parameters

show?string

Comma-separated fields to return; all others are left out. Use dot notation for child fields (customer.email). You cannot send show and hide together (400). See Customizing output.

hide?string

Comma-separated fields to leave out of the response. Use dot notation for child fields (customer.email). You cannot send show and hide together (400). See Customizing output.

formatted?boolean

When true, the object also has a formatted child with amounts and dates as display text in the shopper's language and currency (for example $19.99 or November 7, 2026). The default is false. See Localized formatting.

Defaultfalse

Request Body

application/json
  1. body

Change the storefront document, the switch, or both. Send only what you want to change.

Properties1 <= properties
settings?|

The groups to change. A group you send is merged field by field (a list replaces the list). A group sent as null goes back to the defaults. A group you leave out is kept. Send settings: null to discard the whole document; you must switch the shop off first. Changing custom needs the account owner (403 otherwise), and flags cannot be changed.

enabled?boolean

Turn the switch on or off. Only the account owner may do this (403 otherwise). Turning it on needs a saved document (422), and none of your own apps on an address the storefront uses (409).

Response Body

The storefront settings, after the change.

application/json
  1. response

The hosted storefront's settings in the current mode: one document used by the shop, cart, checkout, payment page and customer account, and the switch that says whether the shop's own addresses show the storefront.

object?"settings_storefront"

The object type. Always settings_storefront.

Value in"settings_storefront"
url?string

The URL of this object.

Formaturi
account_id?string

The ID of the account the settings belong to.

test?boolean

True for the test mode settings, false for live.

date_created?string

When the settings were first saved.

Formatdate-time
date_modified?string

When the document or the switch last changed.

Formatdate-time
modified_by?|

The ID of the user who last changed the document or the switch.

enabled?boolean

The shop's switch. True when its own addresses show the storefront.

live?boolean

True when the shop's addresses show the storefront: its own switch is on, or Comecero shows the storefront for every shop.

managed?boolean

True when Comecero shows the storefront for every shop. The shop's own switch then decides nothing.

date_enabled?|

When the switch was turned on. null while it is off.

Formatdate-time
can_switch?boolean

Whether the caller may turn the switch on or off.

can_edit_code?boolean

Whether the caller may change the custom CSS and JavaScript.

has_settings?boolean

Whether a settings document has been saved.

settings?|

The settings document. null until it is first saved.

storefront_url?|

Where the shop's storefront answers now. null when the shop has no host.

Formaturi
preview_url?|

The storefront's own address for the shop, where the document can be seen before the switch is on.

Formaturi
hosts?array<string>

The shop's host names, from the technical settings (app_hosts).

platform_apps?array<>

The Comecero apps the account has installed that the storefront replaces.

own_apps?array<>

Apps of your own that are installed. They are served as before.

alias_conflicts?array<string>

Aliases of your own apps that would hide a storefront page. Give each a different alias before you turn the switch on.

formatted?

Display text for the dates. Returned only when formatted=true.

Example Request
curl -X POST 'https://api.comecero.com/api/v1/settings/storefront' \  -H 'Content-Type: application/json' \  -d '{  "settings": {    "brand": {      "name": "Example Store"    },    "theme": {      "primary": "#1F6FEB"    }  }}'
Example Response
{  "object": "settings_storefront",  "url": "https://api.comecero.com/api/v1/settings/storefront",  "account_id": "AB1234",  "test": true,  "date_created": "2026-09-28T10:02:44Z",  "date_modified": "2026-10-02T14:21:07Z",  "modified_by": "1000",  "enabled": true,  "live": true,  "managed": false,  "date_enabled": "2026-10-02T14:21:07Z",  "can_switch": true,  "can_edit_code": true,  "has_settings": true,  "settings": {    "version": 1,    "brand": {      "name": "Example Store",      "logo": "https://cdn.example.com/logo.png"    },    "theme": {      "mode": "standard",      "primary": "#1F6FEB"    },    "source": {      "kind": "storefront"    }  },  "storefront_url": "https://example.apps.comecero.com",  "preview_url": "https://example.shop.comecero.com",  "hosts": [    "example.apps.comecero.com"  ],  "platform_apps": [    {      "app_id": "comecero-shopping-cart",      "alias": "cart",      "name": "Shopping Cart",      "version": "3.1.60",      "key": "cart"    }  ],  "own_apps": [],  "alias_conflicts": []}

Get storefront settings GET

Returns the hosted storefront's settings document, its switch, the shop's addresses and what the caller may change. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Secret and trusted tokens may call it when their permissions include `settings_storefront`. Limited tokens may not.

Get subscription settings GET

Returns how subscriptions renew: reminders, payment retries, what customers may change themselves, and renewal emails. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Secret and trusted tokens may call it when their permissions include `settings_subscription`. Limited tokens may not.