Skip to content

Update a store

PUT
/stores/{storeRef}
curl --request PUT \
--url https://apibase.ecomweb.app/api/v1/stores/example \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--data '{ "name": "My Awesome Store", "description": "A great store selling amazing products", "subdomain": "my-awesome-store", "custom_domain": "mystore.com", "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", "featured_image": "https://example.com/featured.jpg", "tagline": "Quality products, great prices" }'

Changes the store’s name and description. The other fields in the body pass validation but are not applied; use the store settings routes for branding and links. An unknown store reference returns 404. Public store data is refreshed right away.

Required scopes: write:settings

storeRef
required
string

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

Media typeapplication/json
object
name

Name of the store

string
>= 2 characters <= 100 characters

Example

My Awesome Store
description

Description of the store

string

Example

A great store selling amazing products
subdomain

Accepted but not applied: the subdomain is not changed through this route. Lowercase letters, numbers and hyphens.

string
>= 3 characters <= 63 characters /^[a-z0-9]([a-z0-9-]{1,61}[a-z0-9])$/

Example

my-awesome-store
custom_domain

Custom domain for the store

string

Example

mystore.com
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
featured_image

Featured image URL for the store

string

Example

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

Store tagline

string

Example

Quality products, great prices
Media typeapplication/json
object
description

Store description, or null.

string
nullable
status
required

pending while the store is being set up, active, or disabled by the merchant.

string
Allowed values: pending active disabled
onboarding_status

Progress flags of the store’s setup, such as product_added and theme_customized.

object
key
additional properties
any
deleted_at

Deletion time as an ISO 8601 timestamp, or null. Deleted stores are not returned, so this is normally null.

string
nullable
first_opened_at
required

When the store was first opened to the public, as an ISO 8601 timestamp. Null until then.

string
nullable
setup_guide_closed_at
required

When the merchant ended setup without opening the store, as an ISO 8601 timestamp, or null.

string
nullable
settings

The store’s settings. Present only when include_settings is set; null when the store has none yet.

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
config

The store’s domain configuration. Present only when include_config is set; null when it has none yet.

object
subdomain

The store’s subdomain on the platform domain, or null.

string
nullable
custom_domain

The store’s custom domain in lower case, or null.

string
nullable
verified

Whether the custom domain is verified. It serves the store only when it is.

boolean
nullable
domain_verification_token

The value the merchant publishes in DNS to prove they own the custom domain. Put it in a TXT record named _ecomweb-verify.<domain> as ecomweb-verify=<token>. Null until a custom domain is claimed.

string
nullable
custom_domain_claimed_at

When the current custom domain was claimed, as an ISO 8601 timestamp, or null.

string
nullable
proof_checked_at

When a verified domain’s DNS record was last re-checked, as an ISO 8601 timestamp, or null.

string
nullable
proof_deadline

Set while a verified domain’s DNS record is missing: the domain is released at this time. Null otherwise.

string
nullable
created_at
required

When the configuration was created, as an ISO 8601 timestamp.

string
updated_at
required

When the configuration was last updated, as an ISO 8601 timestamp.

string
subscription

The store’s plan. Present only on the list and only when include_subscription is set.

object
plan_name
required

Name of the plan, or null.

string
nullable
trial_ends_at
required

When the trial ends, as an ISO 8601 timestamp, or null.

string
nullable
current_period_end
required

When the current billing period ends, as an ISO 8601 timestamp, or null.

string
nullable
status
required

Subscription status, such as active.

string
is_free
required

True for the free plan. A free store still has an active subscription.

boolean
is_trial_plan
required

True on the trial plan every new store starts on.

boolean
role

The caller’s role in the store, such as owner. Present only on the list.

string
nullable
ref
required

The store’s reference, used as storeRef in every other route.

string
user_id
required

ID of the account that owns the store.

string
name
required

Store name.

string
has_used_trial
required

Whether the store has already used its free trial.

boolean
created_at
required

When the store was created, as an ISO 8601 timestamp.

string
updated_at
required

When the store was last updated, as an ISO 8601 timestamp.

string
coming_soon
required

Whether visitors see the coming soon page instead of the storefront.

boolean
setup_guide_hidden
required

Whether the setup guide is hidden in the dashboard.

boolean

Example

{
"status": "pending"
}

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"
}

The resource does not exist in this store.

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"
}