A signed link to upload the CSV 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.
Returns a short-lived (10 minutes) signed HTTPS PUT link into the business's upload area, with its uploadId. PUT the file's bytes to uploadUrl with plain HTTP (for example curl -T stock.csv -H "Content-Type: text/csv" -H "x-goog-content-length-range: 1,10485760" "<uploadUrl>"), sending exactly the returned headers: the link accepts that content type and 1 byte to 10 MB. No browser CORS is involved. Then pass { uploadId } to startProductImport. A link not used in time stops working, and an unused upload is cleared after a day.
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
contentType?string"text/csv""text/csv""text/plain""text/tab-separated-values"OK
application/json- response
data*curl -X POST 'https://api.shopeazy.co/v1/merchant/stores/<storeId>/product-imports/upload-link' \ -H 'Authorization: Bearer <access_token>' \ -H 'Idempotency-Key: <unique_key>' \ -H 'Content-Type: application/json' \ -d '{}'{ "data": { "uploadId": "string", "uploadUrl": "string", "method": "PUT", "headers": { "property1": "string", "property2": "string" }, "expiresAt": 0, "expiresInSeconds": 0, "maxBytes": 0, "maxRows": 0 }}Start a bulk product import from an uploaded CSV POST
Upload the file first (createProductImportUploadLink, then PUT it) and pass its `uploadId`. Say how the columns map with a saved profile (`profileId`, listProductImportProfiles) or an inline `mapping`; one of the fields mapped has to be a product ID, SKU or barcode, so next month's file finds this month's products instead of creating them again. The file is read and staged here (a file with no rows, a missing column or over 20,000 rows is `422` and nothing starts), then a worker applies it in chunks: this answers `202` at once with the run, `status: queued`. Poll getProductImport until `status` is `applied` (written), `previewed` (a `dryRun`: the same run, nothing written) or `failed`. Rows with a match are updated (only what the file has a value for: an empty cell never clears a field) and the rest are created as drafts. New products count against the plan's listing cap as in the console: past it, those rows are refused with a reason. Rows that fail are listed in `errors` (the first 200) and counted in `summary.error`. The same `uploadId` is the same run: asking again returns the run that is there. Needs the Products kit (404 `kit_not_found`) and answers `501 not_available` where bulk import is not switched on. Access: OAuth scope `listings:write`; write-gated by the subscription.
One import, with its status, progress and the rows it refused GET
`status` is `queued`, `running`, then `applied`, `previewed` or `failed` (`failure` says why, in the merchant's words). `rowsDone` of `totalRows` is the progress. `errors` holds the first 200 rows refused (`row` is the line in the file, not counting the header); `errorsTruncated` says there were more, and `summary.error` is the count. An import the console recorded reads the same. Access: OAuth scope `listings:read`; not write-gated.