ShopEazydevelopers
API referenceMerchant API BetaStore

Set or clear the pop-up in the design draft

Beta
Credentials
  • OAuth access token
Scopes
marketing: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.
PUT
/v1/merchant/stores/{storeId}/design/popup

An offer code or a newsletter sign-up shoppers see after a few seconds. Send clear: true to remove it.

Lands in the design draft, as the console's designer saves it; shoppers see it after the design is published.

Read the draft fresh on every call, so changes made seconds apart build on each other.

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

Authorization

merchantOAuth marketing: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: marketing: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
kind?string
Value in"offer""newsletter"
code?string
Lengthlength <= 40
heading?string
Lengthlength <= 60
text?string
Lengthlength <= 160
photo?string
delay?integer
Value in51020
every?string
Value in"once""week""month"
clear?boolean

Response Body

OK

application/json
  1. response
data*

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

Example Request
curl -X PUT 'https://api.shopeazy.co/v1/merchant/stores/<storeId>/design/popup' \  -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"  }}

Arrange the home page sections in the design draft PATCH

Order, show, hide, add page blocks and remove blocks that were added. The shop's own sections can be hidden, not removed. Lands in the design draft, as the console's designer saves it; shoppers see it after the design is published. Read the draft fresh on every call, so changes made seconds apart build on each other. Access: OAuth scope `design:write`; owner/admin only; write-gated by the subscription.

Change the brand: logo, colours, tagline and voice PATCH

Only what is sent changes. Live at once on receipts and emails; the shop design's own colours are set with `setStoreLook`. Access: OAuth scope `design:write`; owner/admin only; write-gated by the subscription.