Store photos for listings, from links or bytes
- Credentials
- OAuth access token
- Scopes
listings:write- Subscription
- Needs an active plan. Otherwise
403 subscription_locked. - Idempotency
- Send an
Idempotency-Keyheader. A retry with the same key does the work once.
Up to 50 at once. A link must be https to a public page: it is fetched safely (public addresses only, 15 MB), decoded and re-encoded, so what is stored is pixels we wrote. Bytes are base64, 4 MB each (a request body is capped by the host, so send few or use links). For a photo the person attached or you edited, call createPhotoUploadLinks, PUT the file to the link and pass its uploadId: it is read from the business's upload area, decoded and re-encoded like a link, filed in the Library, and the temporary file is deleted. One result per photo, in order: its stored link, or why it was refused. An OAuth connection's 200 a day counts every kind. Pass a link to createProduct or updateProduct.
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 listings:write; write-gated by the subscription.
merchantOAuth listings:writeAuthorizationBearer <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: listings:write
storeId*stringA store the person can reach. Any other id answers 404, never 403.
Idempotency-Key*stringRequired 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.
^[A-Za-z0-9_-]{8,128}$application/json- body
photos*array<||>1 <= items <= 50OK
application/json- response
data*curl -X POST 'https://api.shopeazy.co/v1/merchant/stores/<storeId>/photos' \ -H 'Authorization: Bearer <access_token>' \ -H 'Idempotency-Key: <unique_key>' \ -H 'Content-Type: application/json' \ -d '{ "photos": [ { "url": "https://example.com" } ]}'{ "data": { "saved": [ { "index": 0, "url": "string", "width": 0, "height": 0 } ], "stored": 0 }}Upload a file that is not an image POST
For deliverables of a digital product, or the files handed over with an order (a PDF, a document, a zip, audio, video, a font, a design file, a picture): `uploadImage` is for listing photos, which it checks and re-encodes; this stores the bytes as they are. Only these kinds are let in, decided by the ending of the file name and never by the type the client says: `pdf`, `doc`, `docx`, `xls`, `xlsx`, `ppt`, `pptx`, `odt`, `ods`, `odp`, `rtf`, `txt`, `csv`, `md`, `epub`, `mobi`, `zip`, `7z`, `mp3`, `wav`, `m4a`, `aac`, `ogg`, `flac`, `mp4`, `m4v`, `mov`, `webm`, `ttf`, `otf`, `woff`, `woff2`, `jpg`, `jpeg`, `png`, `gif`, `webp`, `heic`, `tif`, `tiff`, `psd`, `ai`, `sketch`, `fig`. Anything else (a web page, a script, a program, a file with no ending) is 422 `validation_error`. `name` in the answer is the name that was sent, without any folder. More than 50 MB is 413 `too_large`; no file, or an empty one, is 400 `bad_request`. Storage: counts against the plan's storage like a photo: refused with 403 `plan_limit` when it would take the Library over it. What is already stored stays. It stores a file and attaches it to nothing. The `Idempotency-Key` keeps a retry from storing the file twice. Access: OAuth scope `listings:write`; write-gated by the subscription.
Signed links to upload photos straight to storage POST
For photos too big to send as base64 (a photo the person attached, or one edited in a code sandbox). Returns 1 to 10 short-lived (10 minutes) signed HTTPS PUT links into the business's Library upload area, each with an `uploadId`. PUT the file bytes to `uploadUrl` with plain HTTP (for example `curl -T photo.jpg -H "Content-Type: image/jpeg" -H "x-goog-content-length-range: 1,15728640" "<uploadUrl>"`), sending exactly the returned `headers`: the link only accepts that content type and 1 byte to 15 MB. No browser CORS is involved. Then pass `{ uploadId }` to addPhotos. Links not used within 10 minutes stop working. 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 `listings:write`; write-gated by the subscription.