See the Promotions API Guides for prerequisites and the full upload lifecycle.

Summary

Requests a presigned S3 upload URL for a new promotions file. The partner then PUTs the JSON file directly to S3 — that upload is not routed through this API.

Usage scenario

Partner wants to create or sync promotions in bulk by uploading a JSON file rather than calling the API per-promotion.

Business constraints

• The file must be uploaded to the returned upload_url before expires_at (1 hour).
• The S3 PUT must not include an Authorization: Bearer header — the presigned URL already contains AWS auth parameters in its query string.
• Maximum file size: 50 MB.
• Maximum 2,000 items per promotion_id. Large promotions (many sites or many items) are split internally during processing — there is no partner-facing block-size cap to manage; submit the file as-is.
• Sync semantics: each upload replaces the brand's current promotion set. Promotions absent from the new file are removed automatically; only promotions whose content actually changed are updated.
• Duplicate-file detection is always on. If the new file's content_hash matches your most recent successful upload for this brand_id — regardless of how long ago — the job terminates with status: failed and error_code: DUPLICATE_FILE (no promotions are re-processed). The original job_id appears in details.original_job_id.
• Only one upload is processed per brand_id at a time. If you submit a second file for the same brand while a previous upload is still processing, it is rejected with 409 JOB_IN_PROGRESS — poll the job status and retry once the in-flight upload reaches a terminal state. (This is separate from DUPLICATE_FILE, which is content-based, not timing-based.) Uploads for different brand_ids run in parallel.

Operational constraints

• Rate limit: 6 requests per brand per hour.
• End-to-end processing target: under 120 minutes per upload.
• Currency for amount_off / fixed_price / max_discount / min_order_value is derived from the brand_id (a brand is bound to a single market at onboarding).