Overview
Use these endpoints to retrieve the current promotions for a feed or upsert
partial promotion changes matched by id.
REST endpoints
GET /product_feeds/{id}/promotionsreturns the promotions for the specified feed.PATCH /product_feeds/{id}/promotionsupserts promotions into the specified feed. Promotions are matched byid, and promotions not included in the request remain unchanged.
GET /product_feeds/{id}/promotions
Returns the promotions for the specified feed.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
id |
string |
Yes | Identifier for the feed. |
Request
This endpoint does not define a request body.
Response
200 OK
| Field | Type | Required | Description |
|---|---|---|---|
[] |
Promotion[] |
Yes | Array of promotions for the specified feed. |
404 Not Found
Returned when the feed is not found.
PATCH /product_feeds/{id}/promotions
Upserts promotions into the specified feed. Promotions are matched by id. Promotions not included in the request remain unchanged.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
id |
string |
Yes | Identifier for the feed. |
Request
| Field | Type | Required | Description |
|---|---|---|---|
[] |
Promotion[] |
Yes | Array of promotions for the feed. |
Response
200 OK
Returns the following acceptance object:
| Field | Type | Required | Description |
|---|---|---|---|
id |
string |
Yes | Identifier for the feed. |
accepted |
boolean |
Yes | Whether the promotion payload was accepted. |
400 Bad Request
Returned when the promotion payload is invalid.
404 Not Found
Returned when the feed is not found.
Schema reference
Promotion
| Field | Type | Required | Description |
|---|---|---|---|
id |
string |
Yes | Promotion identifier. |
title |
string |
Yes | Promotion title. |
description |
Description |
No | Promotion description content. |
status |
PromotionStatus |
No | Promotion status. |
active_period |
DateTimeRange |
Yes | Start and end time for the promotion. |
benefits |
PromotionBenefit[] |
Yes | Benefits applied by the promotion. |
applies_to |
ProductTarget[] |
No | Products or variants targeted by the promotion. |
url |
string (uri) |
No | Canonical promotion URL. |
Description
At least one of the following fields must be present.
| Field | Type | Required | Description |
|---|---|---|---|
plain |
string |
No | Plain-text description. |
html |
string |
No | HTML description. |
markdown |
string |
No | Markdown description. |
Price
| Field | Type | Required | Description |
|---|---|---|---|
amount |
integer |
Yes | Monetary amount expressed in ISO 4217 minor units. |
currency |
string |
Yes | Currency identifier. |
DateTimeRange
| Field | Type | Required | Description |
|---|---|---|---|
start_time |
string |
Yes | Start timestamp. |
end_time |
string |
Yes | End timestamp. |
PromotionStatus
PromotionStatus is a string. Known values include draft, scheduled, active, expired, and disabled.
PromotionBenefit
PromotionBenefit is a union of:
AmountOffBenefitPercentOffBenefitFreeShippingBenefit
AmountOffBenefit
| Field | Type | Required | Description |
|---|---|---|---|
type |
const |
Yes | Must be amount_off. |
amount_off |
Price |
Yes | Amount discounted. |
PercentOffBenefit
| Field | Type | Required | Description |
|---|---|---|---|
type |
const |
Yes | Must be percent_off. |
percent_off |
number |
Yes | Percentage discounted. |
FreeShippingBenefit
| Field | Type | Required | Description |
|---|---|---|---|
type |
const |
Yes | Must be free_shipping. |
ProductTarget
| Field | Type | Required | Description |
|---|---|---|---|
product_id |
string |
Yes | Product targeted by the promotion. |
variant_ids |
string[] |
No | Variants targeted within the product. |