ShopEazydevelopers
API referenceMerchant API BetaStore

Design the home page with AI, into the draft

Beta
Credentials
  • OAuth access token
Scopes
ai:spend
Role
Owners and admins only. Staff get 403 forbidden.
Subscription
Needs an active plan. Otherwise 403 subscription_locked.
Daily limit
AI generations, 300 a day per store. Over the limit is 429 rate_limited.
Idempotency
Send an Idempotency-Key header. A retry with the same key does the work once.
POST
/v1/merchant/stores/{storeId}/design/ai

One model call reads the shop (logo, listings and their photos, categories, live codes, the merchant's own words) and composes a Look, colours, hero words and 6 to 10 sections. It lands in the design DRAFT only: show previewUrl, then publishStorefront. heroPhoto also makes a wide hero photo, for more credits. Credits are checked for the whole job first and charged only once each part worked (403 insufficient_credits).

Storage: refused with 403 plan_limit when it would take the Library over the plan's storage. What is already stored stays.

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

Authorization

merchantOAuth ai:spend
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: ai:spend

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
brief?string

The merchant's own words about the feel they want.

Lengthlength <= 300
heroPhoto?boolean

Also make a wide hero photo (more credits).

Defaultfalse

Response Body

OK

application/json
  1. response
data*

The draft after a change, and what the save said.

Example Request
curl -X POST 'https://api.shopeazy.co/v1/merchant/stores/<storeId>/design/ai' \  -H 'Authorization: Bearer <access_token>' \  -H 'Idempotency-Key: <unique_key>' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "data": {    "design": {      "look": "string",      "colours": {        "primary": "string",        "accent": "string",        "background": "string",        "foreground": "string"      },      "corners": "string",      "hero": {        "headline": "string",        "line": "string",        "button": "string",        "photo": "string"      },      "announcement": {        "text": "string",        "href": "string",        "endsAt": 0,        "more": [          "string"        ]      }    },    "sections": [      {        "id": "string",        "type": "string",        "label": "string",        "shown": true,        "kind": "string",        "block": {}      }    ],    "popup": {      "kind": "string",      "code": "string",      "heading": "string",      "text": "string",      "imageUrl": "string",      "delay": 0,      "every": "string"    },    "problems": [      "string"    ],    "draftDiffersFromLive": true,    "previewUrl": "string",    "creditsSpent": 0,    "creditsLeft": 0  }}

Is this shop web address free? GET

The same policy and availability provisioning uses. When it is not free, the closest address that is. Access: OAuth scope `store:read`; not write-gated.

The shop's web address and where a connected domain is at GET

The ShopEazy address, the merchant's own domain if one is connected, and what to create at their registrar until it is live. With `name`, also answers whether that ShopEazy address is free (same policy and availability as `checkWebAddress`, and the closest free one when it is not), so a change can be shown before it is made. Access: OAuth scope `settings:write`; owner/admin only; not write-gated.