See the Promotions API Guides for prerequisites and the full upload lifecycle.
The Request a Presigned Upload URL endpoint returns a presigned upload_url that you use to upload your promotions file directly to S3. The upload_url is valid for a single file upload only and expires 1 hour after issue (see expires_at in the response).
Do not route this request through the Deliveroo API gateway — PUT directly to the upload_url returned by the previous step.
No authentication header on the S3 PUT
The presigned URL already contains AWS authentication parameters in its query string. Do not send the Authorization: Bearer ... header to S3 — S3 may reject the request.
File format
The body is a JSON object with a promotions array. Each entry is one promotion — a single mechanic and reward for a partner-controlled promotion_id. Each promotion_id must be unique within a file.
File size limit
Maximum file size: 50 MB. Files exceeding this limit will fail schema validation and the job will transition to status: failed with a FILE_TOO_LARGE entry in the status response.
Sync semantics and duplicate detection
Each upload is treated as the canonical state for the brand. Promotions absent from the new file are removed; only promotions whose content actually changed are updated. If the new file's content_hash matches your most recent successful upload for this brand_id, the job terminates with status: failed and error_code: DUPLICATE_FILE (no promotions are re-processed). Inspect the outcome via GET /brands/{brand_id}/promotions/jobs/{job_id}/status.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
File accepted by S3. Poll the job_id returned by the Request Upload URL endpoint to track processing.
Malformed request to S3 — check Content-Type and HTTP method.
Presigned URL expired or signature mismatch — request a new URL.