Upload a file that is not an image
- 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 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.
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}$multipart/form-data- body
file*stringOne file of a kind listed on the operation (a PDF, a document, a zip, audio, video, a font, a design file, a picture), at most 50 MB and not empty.
Created
application/json- response
data*curl -X POST 'https://api.shopeazy.co/v1/merchant/stores/<storeId>/uploads/files' \ -H 'Authorization: Bearer <access_token>' \ -H 'Idempotency-Key: <unique_key>' \ -F 'file=@file.jpg'{ "data": { "url": "string", "name": "string" }}Upload an image to the workspace's storage POST
Used for product photos and (by the app) for the profile avatar. 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.
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.