Store

The Store API exposes the stores your API token can act on, plus checkout setup for the selected store: payment methods, popup embed hostnames, abandoned-checkout recovery, tax defaults, and partner defaults.

Branding palettes are a separate resource — see Branding Themes.

Overview

• Get store — the selected store, including checkout setup
• List stores — every store your token has API access to
• Update store — sparse checkout-setup writes and the store legal footer

Get store is the natural first call for any integration: it tells you which store the request landed on, which currencies that store already transacts in, and the store-level checkout defaults products inherit. If your token has access to more than one store, List stores gives you the store IDs to use with the X-Easycart-Store header — see Store selection.

Update store accepts checkout-setup keys and footer_id. Profile fields such as name, email, address, and logo_url are not writable here — sending them returns 422.

Payment Methods

payment_methods is a bare array on the store object — not { items, pagination }. Get store returns the full catalog for the store, sorted by order (lower first).

Each item's id is a catalog key, not a UUID. Do not snake-case applePay, googlePay, or payPo. Catalog ids:

card, applePay, googlePay, blik, tpay, tpay_blik, p24, ideal, eps, bancontact, twint, klarna, revolut_pay, mobilepay, affirm, payPo.

provider is always present: stripe, tpay, or paypo. is_available is read-only. It is false until the method's payment provider is connected and the method is activated for the store, and also while the store's availability with that provider cannot be checked. Enabling a method that is genuinely not activated returns 422 on payment_methods.{i}.is_enabled — connect the provider in the dashboard. Because the same false covers both cases, an enable is not guaranteed to be rejected; if the provider is already connected, read the store again and retry.

is_enabled and order are writable. Methods with no saved row default to enabled for card, applePay, and googlePay, and disabled for the rest.

Update store patches listed items by id. Unlisted methods are unchanged. Duplicate or unknown id returns 422. Sending provider or is_available on write returns 422.

Popup Allowed Domains

popup_allowed_domains is a bare array of hostnames that may embed checkout as a popup. Get store returns them unique, lowercase, and sorted. An empty array means no third-party popup hosts. Each hostname is matched as stored — a parent domain does not allow its subdomains.

On update, the array you send replaces the whole list. Send [] to clear it. Hostnames only — a value with a scheme (for example https://shop.example.com) returns 422.

Checkout Recovery

Store checkout_recovery.enabled is a boolean — never null. false turns store-wide recovery off. Product checkout_recovery.enabled: null inherits this store default at checkout.

coupon: null means no recovery coupon. When a coupon is set, exactly one of amount or percent is present. amount is an integer in minor units (e.g. cents) applied in each product's currency — there is no currency key on the store coupon. percent is an integer 1–100.

On update, omitted checkout_recovery keys are unchanged. Sending coupon replaces the pair. Sending coupon: null clears it. Both amount and percent, neither, or currency on write returns 422.

Tax Defaults

vat_rate, flat_rate, gtu_code, and exempt_tax_kind are store defaults. A product field that is null inherits the matching store value at checkout — see Invoice, tax, portal, waitlist, and QR.

Allowed values match the product fields: vat_rate is a string ("23", "zw", "np"), gtu_code is an integer 1–13, flat_rate is one of 17, 15, 14, 12.5, 12, 10, 8.5, 5.5, 3, 2, and exempt_tax_kind is the exemption basis when VAT is zw (max 255 characters). Send null to clear a store default.

Partners

partners is always present on the store object and is never null. It is the store-wide cookie length and commission a partner inherits when that partner's cookie_valid_days or commission_percent is null.

cookie_valid_days is an integer from 1 to 3650. commission_percent is an integer 1–100, where 20 means 20%. The object is not per currency.

Until the store saves its own values, they are 7 days and 20%.

Update store accepts a sparse partners object. Sending one key leaves the other in place. At least one of cookie_valid_days or commission_percent is required. null on either key returns 422. Send 7 or 20 to put that default back. The field name is commission_percent, not commission.

Legal footer

footer_id is the store legal footer. Update store accepts it and saves it immediately. Omit it to leave the current footer. Setting a UUID turns the store legal footer on. null clears it and turns that footer off. A value that is not a UUID, an unknown project, or a project that is not a legal footer on your account returns 422, and nothing in the patch is saved.

Get store returns store.footer_id only with include=footer_id. Without that token the key is omitted. With it, the value is a UUID, null when nothing is attached, or { "message": "The Easytools attachment could not be resolved." } when the attachment cannot be resolved. That GET stays 200, and the rest of the store is unchanged. Unknown include tokens are ignored.

The key is not on List stores. The Update store response omits it. It is not listed in the Store Object table.

Store Object

Returned inside store on Get store and Update store.

Field	Type	Nullable	Description
id	string	No	Unique store identifier (UUID)
name	string	No	Store name
slug	string	No	URL-friendly store identifier
email	string	Yes	Primary contact email
website_url	string	Yes	Store website URL
logo_url	string	Yes	Store logo URL
tax_id	string	Yes	Tax identification number
company_name	string	Yes	Registered company / billing name
full_name	string	Yes	Contact person's full name
phone	string	Yes	Contact phone number
address	object	Yes	Store billing address. null when the store has no details set. See Address Object.
created_at	string	No	When the store was created (ISO 8601)
payment_methods	array	No	Full payment-method catalog. See Payment Method Object.
popup_allowed_domains	array	No	Hostnames allowed to embed checkout as a popup. Empty means none.
checkout_recovery	object	No	Store-wide abandoned-checkout recovery. See Checkout Recovery Object.
vat_rate	string	Yes	Default VAT rate inherited by products with a null vat_rate
flat_rate	number	Yes	Default flat-rate tax percent inherited by products with a null flat_rate
gtu_code	integer	Yes	Default GTU code 1–13 inherited by products with a null gtu_code
exempt_tax_kind	string	Yes	Default exemption basis inherited by products with a null exempt_tax_kind
partners	object	No	Store-wide partner defaults. Never null. See Partners Object.

footer_id is not in this table. It appears on Get store only when include=footer_id — see Legal footer.

currencies sits beside store on the envelope, not inside it. It is an array of lowercase ISO currency codes the store already has products in, and may be empty.

Address Object

Field	Type	Nullable	Description
street	string	Yes	Street name
street_number	string	Yes	Street / building number
house_number	string	Yes	Apartment / house number
post_code	string	Yes	Postal code
city	string	Yes	City
state	string	Yes	State / region / province
country	string	Yes	Uppercase ISO 3166-1 alpha-2 country code (e.g. "US")

Payment Method Object

Field	Type	Nullable	Description
id	string	No	Catalog key (card, applePay, …). Not a UUID.
provider	string	No	stripe, tpay, or paypo. Read-only.
is_enabled	boolean	No	Whether the method is turned on for this store.
order	integer	No	Display order, lower first. Minimum 0.
is_available	boolean	No	Read-only. See Payment methods.

Checkout Recovery Object

Field	Type	Nullable	Description
enabled	boolean	No	Store-wide recovery switch. Never null.
coupon	object	Yes	Recovery coupon. null means none. See Checkout Recovery Coupon Object.

Checkout Recovery Coupon Object

Exactly one of amount or percent is set. There is no currency property.

Field	Type	Nullable	Description
amount	integer	Yes	Fixed discount in minor units (e.g. cents), applied in each product's currency. Minimum 1 when set. Mutually exclusive with percent.
percent	integer	Yes	Percent discount, 1–100. Mutually exclusive with amount.

Partners Object

Always present. Never null. See Partners.

Field	Type	Nullable	Description
cookie_valid_days	integer	No	How many days the partner cookie lasts when a partner does not set its own. 1–3650. Default 7.
commission_percent	integer	No	Commission when a partner does not set its own. Integer 1–100. 20 means 20%. Default 20.