Signed links to upload photos straight to storage
- 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.
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.
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
count?integerHow many photos you will upload.
1 <= value <= 101contentType?stringThe type of the files; the links only accept this type.
"image/jpeg""image/jpeg""image/png""image/webp""image/heic""image/heif"OK
application/json- response
data*curl -X POST 'https://api.shopeazy.co/v1/merchant/stores/<storeId>/photos/upload-links' \ -H 'Authorization: Bearer <access_token>' \ -H 'Idempotency-Key: <unique_key>' \ -H 'Content-Type: application/json' \ -d '{}'{ "data": { "links": [ { "uploadId": "string", "uploadUrl": "string", "headers": { "property1": "string", "property2": "string" } } ], "method": "PUT", "expiresAt": 0, "expiresInSeconds": 0, "maxBytes": 0 }}Store photos for listings, from links or bytes POST
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.
Channel health and how many chats are waiting GET
Access: OAuth scope `orders:read`; not write-gated.