ShopEazydevelopers
API referenceMerchant API BetaStorefront

Compose a design of its own, no AI

Beta
Credentials
  • OAuth access token
Scopes
design:write
Role
Owners and admins only. Staff get 403 forbidden.
Subscription
Needs an active plan. Otherwise 403 subscription_locked.
Idempotency
Send an Idempotency-Key header. A retry with the same key does the work once.
POST
/v1/merchant/stores/{storeId}/storefront/generate

A design made by rules, never a model, so it costs nothing: the store's category template, a Look and font pairing that suit feel, colours built around colour that always pass contrast (text 4.5:1, buttons 3:1), a design for each home block that has one, and hero words from the shop's name, category and town. The same seed gives the same design; without one a new seed is picked and returned, so the design can be made again. The hero photo and the shop's own listing sections stay. Lands in the draft; nothing changes for shoppers until publishStorefront.

Access: OAuth scope design:write; owner/admin only; write-gated by the subscription.

Authorization

merchantOAuth design:write
headerAuthorizationBearer <token>

OAuth 2.1 (authorization code + PKCE S256, public clients, dynamic registration) for connected AI apps. Effective power is scopes granted AND the person's role today AND the plan. orders:refund, billing:write and team:write are opt-in on the consent screen. Write implies read for marketing:read and messages:read, so a grant holding marketing:write passes a marketing:read check, and messages:send passes messages:read.

Scope: design:write

Path Parameters

storeId*string

A store the person can reach. Any other id answers 404, never 403.

Header Parameters

Idempotency-Key*string

Required on every write. Minted on the device when the person taps, reused on every retry. A write without one, or with one that does not match the pattern, is refused with 422 validation_error. Scoped to the token's subject, remembered 24 hours. A replay returns the first 2xx response with Idempotent-Replay: true; a request still running answers 409 in_flight; the same key with a different method, path or body answers 409 idempotency_key_reused; non-2xx results are not remembered. If the key store cannot be read nothing is processed and the answer is 503 idempotency_unavailable: retry with the same key.

Match^[A-Za-z0-9_-]{8,128}$

Request Body

application/json
  1. body
feel?string

How the shop should feel. Absent, one that suits its category.

Value in"warm""moody""fresh""bold""calm"
colour?string

A colour to build the palette around, like #ff5275. Absent, the Look's own.

Match^#[0-9a-fA-F]{6}$
seed?string

The same seed and shop give the same design. Absent, a new one.

Length1 <= length <= 64

Response Body

OK

application/json
  1. response
data*
Example Request
curl -X POST 'https://api.shopeazy.co/v1/merchant/stores/<storeId>/storefront/generate' \  -H 'Authorization: Bearer <access_token>' \  -H 'Idempotency-Key: <unique_key>' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "data": {    "template": "string",    "seed": "string",    "feel": "warm",    "saved": {      "look": "string",      "colours": {},      "corners": "string",      "hero": {        "headline": "string",        "line": "string",        "button": "string",        "photo": "string"      },      "sections": [        {          "id": "string",          "type": "string",          "label": "string",          "shown": true,          "kind": "string",          "block": {}        }      ],      "announcement": {}    },    "draftDiffersFromLive": true,    "previewUrl": "string"  }}

Start the design from a template POST

Its look, hero words and home sections around the shop's own listings. Lands in the draft; nothing changes for shoppers until `publishStorefront`. Access: OAuth scope `design:write`; owner/admin only; write-gated by the subscription.

What publishing would change GET

The design draft against what shoppers see now (Look, colours, fonts, corners, the top of the page, each home section new, removed or changed by id, the announcement bar and the pop-up), then the shop's pages with something to publish: one never live (`kind: new`) or a live one whose draft differs (`changed`). Each in a few merchant words: `title` and an optional `detail` ("Top of the page", "Full photo → Split"). `area: design` goes live with `publishStorefront`, `area: page` with that page's `publishPage`. Empty: nothing to publish. Access: OAuth scope `store:read`; not write-gated. Paged: `{ items, nextCursor }`, `limit` (default 100, at most 200) and an opaque `cursor`.