Skip to content

Get a store

GET
/stores/{storeRef}
curl --request GET \
--url 'https://apibase.ecomweb.app/api/v1/stores/example?limit=20&offset=0&status=pending&subdomain=my-store&custom_domain=mystore.com&sort_by=id&include_config=false&include_settings=false&include_subscription=false' \
--header 'x-api-key: <x-api-key>'

Returns one store. Set include_settings to add its settings and include_config to add its domain configuration, which includes the DNS verification value the merchant publishes to prove they own a custom domain. Both are returned to any caller allowed to read the store, secret keys included.

Required scopes: none. Any secret key for this store works.

storeRef
required
string

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

limit
number
default: 20 >= 1 <= 10000

Example

20

Number of items per page

offset
number
0

Example

0

Number of items to skip

status
string
Allowed values: pending active disabled

Example

active

Filter by store status

subdomain
string

Example

my-store

Filter by subdomain (exact match)

custom_domain
string

Example

mystore.com

Filter by custom domain (exact match)

sort_by
string
default: created_at
Allowed values: id name created_at updated_at subdomain status

Example

created_at

Sort field

include_config
boolean

Example

true

Include store config

include_settings
boolean

Example

true

Include store settings

include_subscription
boolean

Example

true

Include each store’s subscription summary (status and plan name)

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