Skip to content

Update store settings

PUT
/stores/{storeRef}/settings
curl --request PUT \
--url https://apibase.ecomweb.app/api/v1/stores/example/settings \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--data '{ "logo_url": "https://example.com/logo.png", "favicon_url": "https://example.com/favicon.ico", "tiktok_link": "https://tiktok.com/@mystore", "shopee_link": "https://shopee.vn/mystore", "facebook_link": "https://facebook.com/mystore", "instagram_link": "https://instagram.com/mystore", "google_analytics_key": "GA-XXXXXXXXX-X", "shop_introduction": "example", "theme_config": {}, "featured_image": "https://example.com/featured.jpg", "tagline": "Quality products, great prices", "currency_code": "VND", "review_requests_enabled": true, "attach_billing_documents": false, "order_number_prefix": "DH-", "order_number_suffix": "-26", "legal_links": { "terms": "/pages/terms-of-service", "privacy": "/pages/privacy-policy" }, "email_accent_color": "#f4644f", "email_bg_color": "#FFFFFF", "email_body_bg_color": "#FFFFFF", "email_text_color": "#1A1A1A", "email_footer_text_color": "#6B7280", "email_logo_url": "https://example.com/email-logo.png", "email_header_tagline": "Style for everyone", "email_footer_address": "123 Nguyen Hue, District 1, HCMC", "email_footer_phone": "1900-1234" }'

Changes the settings you send and leaves the rest as they are, creating the settings if the store has none yet. Public store data and the store’s email branding are refreshed right away. A new order prefix or suffix applies only to orders placed afterwards; existing orders keep their codes. Colours are #RRGGBB. Sending shop_introduction or theme_config fails with 400: those are theme settings now.

Required scopes: write:settings

storeRef
required
string

The store’s ref, as returned by GET /stores.

Media typeapplication/json
object
logo_url

Logo URL for the store

string

Example

https://example.com/logo.png
favicon_url

Favicon URL for the store

string

Example

https://example.com/favicon.ico
tiktok_link

TikTok profile link

string

Example

https://tiktok.com/@mystore
shopee_link

Shopee store link

string

Example

https://shopee.vn/mystore
facebook_link

Facebook page link

string

Example

https://facebook.com/mystore
instagram_link

Instagram profile link

string

Example

https://instagram.com/mystore
google_analytics_key

Google Analytics tracking key

string

Example

GA-XXXXXXXXX-X
shop_introduction

Retired. A theme setting now: PATCH /stores/:ref/themes/:id settings_values. Sending it returns 400.

string
theme_config

Retired. Theme values live on store themes: PATCH /stores/:ref/themes/:id settings_values. Sending it returns 400.

object
featured_image

Featured image URL for the store

string

Example

https://example.com/featured.jpg
tagline

Store tagline

string

Example

Quality products, great prices
currency_code

Currency code for the store

string

Example

VND
review_requests_enabled

Enable product review requests after order completion

boolean

Example

true
attach_billing_documents

Attach the platform bill PDF to billing emails. Off by default: attachments raise spam scoring, and the email links to the document either way.

boolean

Example

false
order_number_prefix

Prefix wrapped around the order sequence to form the customer-facing order code. Frozen onto each order at placement, so changing it never renames an existing order.

string
<= 10 characters /^[A-Za-z0-9#._/-]*$/

Example

DH-
order_number_suffix

Suffix wrapped around the order sequence to form the customer-facing order code. Frozen onto each order at placement.

string
<= 10 characters /^[A-Za-z0-9#._/-]*$/

Example

-26
legal_links

Checkout and register links: { terms, privacy }

object
terms

Link to the terms of service: a site path or a URL. At most 500 characters.

string
nullable <= 500 characters
privacy

Link to the privacy policy: a site path or a URL. At most 500 characters.

string
nullable <= 500 characters

Example

{
"terms": "/pages/terms-of-service",
"privacy": "/pages/privacy-policy"
}
email_accent_color

Accent colour for email buttons and links

string
/^#[0-9A-Fa-f]{6}$/

Example

#f4644f
email_bg_color

Email canvas background colour

string
/^#[0-9A-Fa-f]{6}$/

Example

#FFFFFF
email_body_bg_color

Email content background colour

string
/^#[0-9A-Fa-f]{6}$/

Example

#FFFFFF
email_text_color

Heading and body text colour

string
/^#[0-9A-Fa-f]{6}$/

Example

#1A1A1A
email_footer_text_color

Secondary and footer text colour

string
/^#[0-9A-Fa-f]{6}$/

Example

#6B7280
email_logo_url

Logo shown in email headers. Falls back to logo_url.

string

Example

https://example.com/email-logo.png
email_header_tagline

Short line shown under the logo in email headers

string
<= 120 characters

Example

Style for everyone
email_footer_address

Postal address shown in the email footer

string
<= 255 characters

Example

123 Nguyen Hue, District 1, HCMC
email_footer_phone

Phone number shown in the email footer

string
<= 32 characters

Example

1900-1234
Media typeapplication/json
object
logo_url

Logo URL, or null.

string
nullable
tiktok_link

TikTok profile link, or null.

string
nullable
shopee_link

Shopee store link, or null.

string
nullable
google_analytics_key

Google Analytics tracking key, or null.

string
nullable
facebook_link

Facebook page link, or null.

string
nullable
instagram_link

Instagram profile link, or null.

string
nullable
favicon_url

Favicon URL, or null.

string
nullable
featured_image

Featured image URL, or null.

string
nullable
tagline

Store tagline, or null.

string
nullable
currency_code

Three-letter currency code of the store, such as VND.

string
nullable
email_preferences

Which roles receive which notification emails. A free-form object, or null.

object
key
additional properties
any
review_requests_enabled

Whether customers are asked for a product review after their order.

boolean
nullable
email_sender_name

Sender name shown on the store’s emails, or null for the default.

string
nullable
email_reply_to

Reply-to address of the store’s emails, or null.

string
nullable
attach_billing_documents

Whether the platform bill PDF is attached to billing emails.

boolean
nullable
order_number_prefix

Text placed before the order number in order codes, such as DH-. Null for none.

string
nullable
order_number_suffix

Text placed after the order number in order codes, such as -26. Null for none.

string
nullable
email_accent_color

Accent colour of email buttons and links as #RRGGBB, or null for the default.

string
nullable
email_bg_color

Email canvas background colour as #RRGGBB, or null for the default.

string
nullable
email_body_bg_color

Email content background colour as #RRGGBB, or null for the default.

string
nullable
email_text_color

Email text colour as #RRGGBB, or null for the default.

string
nullable
email_footer_text_color

Email footer text colour as #RRGGBB, or null for the default.

string
nullable
email_logo_url

Logo shown in email headers, or null to use logo_url.

string
nullable
email_header_tagline

Short line under the logo in email headers, or null.

string
nullable
email_footer_address

Postal address in the email footer, or null.

string
nullable
email_footer_phone

Phone number in the email footer, or null.

string
nullable
published_store_theme_id

ID of the store’s live theme, or null when none is published.

number
nullable
legal_links

Checkout and register links, or null.

object
terms

Link to the terms of service: a site path or a URL.

string
nullable
privacy

Link to the privacy policy: a site path or a URL.

string
nullable
created_at

When the settings were created, as an ISO 8601 timestamp.

string
nullable
updated_at

When the settings were last updated, as an ISO 8601 timestamp.

string
nullable
id
required

Settings record ID.

number

Example generated

{
"logo_url": "example",
"tiktok_link": "example",
"shopee_link": "example",
"google_analytics_key": "example",
"facebook_link": "example",
"instagram_link": "example",
"favicon_url": "example",
"featured_image": "example",
"tagline": "example",
"currency_code": "example",
"email_preferences": {},
"review_requests_enabled": true,
"email_sender_name": "example",
"email_reply_to": "example",
"attach_billing_documents": true,
"order_number_prefix": "example",
"order_number_suffix": "example",
"email_accent_color": "example",
"email_bg_color": "example",
"email_body_bg_color": "example",
"email_text_color": "example",
"email_footer_text_color": "example",
"email_logo_url": "example",
"email_header_tagline": "example",
"email_footer_address": "example",
"email_footer_phone": "example",
"published_store_theme_id": 1,
"legal_links": {
"terms": "example",
"privacy": "example"
},
"created_at": "example",
"updated_at": "example",
"id": 1
}

The request is malformed or failed validation.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key is missing, invalid, revoked or expired.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key may not do this: a missing scope, a readonly key, a publishable key on a Store API route, or a disallowed origin.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}