API Reference
Promotions API
Developer-authenticated promotion, promo-code, scheduled-deal, and bundle-offer API reference.
SoundSync
Verified endpoints
These endpoints are route-backed in the current platform.
GET
/api/developer/promotions
List promotion overview: promo codes, scheduled deals, offers, and stats.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Request fields
- query promoLimit: integer
- query dealLimit: integer
- query offerLimit: integer
- Returns
- promoCodes[], deals[], offers[], stats.
- Side effects
- Retrieves the authorized resource; any preparation or event recording is described in the operation notes.
Request, response and error reference
Query and header parameters
[
{
"name": "promoLimit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "dealLimit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "offerLimit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"promoCodes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"deals": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"offers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"imports": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"stats": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
POST
/api/developer/promotions
Create a promo code, scheduled deal, or promotion offer based on type/offerType.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Request fields
- type: string
- offerType: string
- title: string
- name: string
- code: string
- productId: integer
- productIds: array
- subscriptionProductIds: array
- activation: automatic | code
- quantityTiers: array. Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.
- purchaseType: one_time | subscription
- discountType: percent | amount
- discountValue: number
- startsAt: string,null
- endsAt: string,null
- expiresAt: string,null
- maxRedemptions: integer,null. Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses.
- minimumOrderAmount: number
- salePrice: number
- allowDiscountOnSaleItems: boolean
- isActive: boolean
- status: string
- requiredQuantity: integer
- rewardQuantity: integer
- groupTarget: integer
- rewardMinimumOrderAmount: number
- rewardMaxRedemptions: integer
- rewardExpiresInDays: integer
- rewardCodePrefix: string
- rewardGrantScope: string
- rewardIncludeFreeItems: boolean
- rewardRefundPolicy: string
- rewardAllowAutomaticOfferStacking: boolean
- metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- Returns
- 201 created promo code, deal, or offer.
- Side effects
- Writes promo_codes, product_scheduled_deals, or developer_promotion_offers depending on input.
- Notes
- type selects promo_code, subscription_promo_code or scheduled_deal; other supported offerType values use the offer path. Per-type validation, scope, stacking and paid-price rules still apply.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 2147483647,
"description": "Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses."
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": "integer"
},
"rewardQuantity": {
"type": "integer"
},
"groupTarget": {
"type": "integer"
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"promoCode": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"deal": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"offer": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"checkoutBacked": {
"type": "boolean"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
GET
/api/developer/promotions/promo-codes
List promo codes with stats.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Returns
- promoCodes[], stats.
- Side effects
- Retrieves the authorized resource; any preparation or event recording is described in the operation notes.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"promoCodes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"stats": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
POST
/api/developer/promotions/promo-codes
Create product-scoped or storewide promo code.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Request fields
- type: string
- offerType: string
- title: string
- name: string
- code: string (required)
- productId: integer
- productIds: array
- subscriptionProductIds: array
- activation: automatic | code
- quantityTiers: array. Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.
- purchaseType: one_time | subscription
- discountType: percent | amount (required)
- discountValue: number (required)
- startsAt: string,null
- endsAt: string,null
- expiresAt: string,null
- maxRedemptions: integer,null. Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses.
- minimumOrderAmount: number
- salePrice: number
- allowDiscountOnSaleItems: boolean
- isActive: boolean
- status: string
- requiredQuantity: integer
- rewardQuantity: integer
- groupTarget: integer
- rewardMinimumOrderAmount: number
- rewardMaxRedemptions: integer
- rewardExpiresInDays: integer
- rewardCodePrefix: string
- rewardGrantScope: string
- rewardIncludeFreeItems: boolean
- rewardRefundPolicy: string
- rewardAllowAutomaticOfferStacking: boolean
- metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- Returns
- 201 promoCode.
- Side effects
- Creates promo code and may use first developer product for storewide backing.
- Notes
- Omitting productId selects the storewide path, which requires all-products scope.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 2147483647,
"description": "Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses."
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": "integer"
},
"rewardQuantity": {
"type": "integer"
},
"groupTarget": {
"type": "integer"
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true,
"required": [
"code",
"discountType",
"discountValue"
]
}HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"promoCode": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"deal": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"offer": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"checkoutBacked": {
"type": "boolean"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
PATCH
/api/developer/promotions/promo-codes/:promoCodeId
Update a developer-owned promo code.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Request fields
- type: string
- offerType: string
- title: string
- name: string
- code: string
- productId: integer
- productIds: array
- subscriptionProductIds: array
- activation: automatic | code
- quantityTiers: array. Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.
- purchaseType: one_time | subscription
- discountType: percent | amount
- discountValue: number
- startsAt: string,null
- endsAt: string,null
- expiresAt: string,null
- maxRedemptions: integer,null. Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses.
- minimumOrderAmount: number
- salePrice: number
- allowDiscountOnSaleItems: boolean
- isActive: boolean
- status: string
- requiredQuantity: integer
- rewardQuantity: integer
- groupTarget: integer
- rewardMinimumOrderAmount: number
- rewardMaxRedemptions: integer
- rewardExpiresInDays: integer
- rewardCodePrefix: string
- rewardGrantScope: string
- rewardIncludeFreeItems: boolean
- rewardRefundPolicy: string
- rewardAllowAutomaticOfferStacking: boolean
- metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- Returns
- Updated promoCode.
- Side effects
- Updates promo code through product promo-code service.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 2147483647,
"description": "Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses."
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": "integer"
},
"rewardQuantity": {
"type": "integer"
},
"groupTarget": {
"type": "integer"
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"promoCode": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"deal": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"offer": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"checkoutBacked": {
"type": "boolean"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
GET
/api/developer/promotions/scheduled-deals
List scheduled product deals.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Returns
- deals[], stats.
- Side effects
- Retrieves the authorized resource; any preparation or event recording is described in the operation notes.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"deals": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"stats": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
POST
/api/developer/promotions/scheduled-deals
Create scheduled product deal.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Request fields
- type: string
- offerType: string
- title: string
- name: string
- code: string
- productId: integer (required)
- productIds: array
- subscriptionProductIds: array
- activation: automatic | code
- quantityTiers: array. Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.
- purchaseType: one_time | subscription
- discountType: percent | amount
- discountValue: number
- startsAt: string,null (required)
- endsAt: string,null (required)
- expiresAt: string,null
- maxRedemptions: integer,null. Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses.
- minimumOrderAmount: number
- salePrice: number
- allowDiscountOnSaleItems: boolean
- isActive: boolean
- status: string
- requiredQuantity: integer
- rewardQuantity: integer
- groupTarget: integer
- rewardMinimumOrderAmount: number
- rewardMaxRedemptions: integer
- rewardExpiresInDays: integer
- rewardCodePrefix: string
- rewardGrantScope: string
- rewardIncludeFreeItems: boolean
- rewardRefundPolicy: string
- rewardAllowAutomaticOfferStacking: boolean
- metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- Returns
- 201 deal.
- Side effects
- Writes product_scheduled_deals.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 2147483647,
"description": "Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses."
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": "integer"
},
"rewardQuantity": {
"type": "integer"
},
"groupTarget": {
"type": "integer"
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true,
"required": [
"productId",
"startsAt",
"endsAt"
]
}HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"promoCode": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"deal": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"offer": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"checkoutBacked": {
"type": "boolean"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
POST
/api/developer/promotions/deals/:dealId/cancel
Cancel a scheduled deal.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Returns
- Canceled deal.
- Side effects
- Cancels product scheduled deal.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"deal": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
POST
/api/developer/promotions/offers
Create a supported multi-product, tiered-cart, bundle, BOGO or group-buy offer.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Request fields
- type: string
- offerType: string
- title: string
- name: string
- code: string
- productId: integer
- productIds: array
- subscriptionProductIds: array
- activation: automatic | code
- quantityTiers: array. Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.
- purchaseType: one_time | subscription
- discountType: percent | amount
- discountValue: number
- startsAt: string,null
- endsAt: string,null
- expiresAt: string,null
- maxRedemptions: integer,null. Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses.
- minimumOrderAmount: number
- salePrice: number
- allowDiscountOnSaleItems: boolean
- isActive: boolean
- status: string
- requiredQuantity: integer
- rewardQuantity: integer
- groupTarget: integer
- rewardMinimumOrderAmount: number
- rewardMaxRedemptions: integer
- rewardExpiresInDays: integer
- rewardCodePrefix: string
- rewardGrantScope: string
- rewardIncludeFreeItems: boolean
- rewardRefundPolicy: string
- rewardAllowAutomaticOfferStacking: boolean
- metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- Returns
- 201 offer; inspect checkoutBacked. Cart discounts are unlimited by default; optional usage limits work with automatic or code activation.
- Side effects
- Writes the offer; some supported offer types also create a backing promo code.
- Notes
- multi_product_discount and tiered_cart_discount support activation:automatic or code. Tiered offers require selected one-time productIds and 1-50 unique quantityTiers with positive integer quantity no greater than the selected product count, and discountPercent greater than 0 and at most 100. Quantities count distinct positive-priced eligible products, not cart units. The highest reached quantity threshold applies to all eligible copies. Code activation requires code; automatic offers do not require one. Checkout applies the single best qualifying automatic offer, promo stacking rules and the $9.99 paid minimum. Other offer families retain their own eligibility; a saved record is not proof every legacy type is checkout-backed.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 2147483647,
"description": "Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses."
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": "integer"
},
"rewardQuantity": {
"type": "integer"
},
"groupTarget": {
"type": "integer"
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"promoCode": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"deal": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"offer": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"checkoutBacked": {
"type": "boolean"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
GET
/api/developer/promotions/bundles
List bundle-like promotion offers.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Returns
- offers[] filtered to bundle offer types.
- Side effects
- Retrieves the authorized resource; any preparation or event recording is described in the operation notes.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"offers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"stats": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
POST
/api/developer/promotions/bundles
Create bundle-like promotion offer.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Request fields
- type: string
- offerType: string
- title: string
- name: string
- code: string
- productId: integer
- productIds: array
- subscriptionProductIds: array
- activation: automatic | code
- quantityTiers: array. Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.
- purchaseType: one_time | subscription
- discountType: percent | amount
- discountValue: number
- startsAt: string,null
- endsAt: string,null
- expiresAt: string,null
- maxRedemptions: integer,null. Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses.
- minimumOrderAmount: number
- salePrice: number
- allowDiscountOnSaleItems: boolean
- isActive: boolean
- status: string
- requiredQuantity: integer
- rewardQuantity: integer
- groupTarget: integer
- rewardMinimumOrderAmount: number
- rewardMaxRedemptions: integer
- rewardExpiresInDays: integer
- rewardCodePrefix: string
- rewardGrantScope: string
- rewardIncludeFreeItems: boolean
- rewardRefundPolicy: string
- rewardAllowAutomaticOfferStacking: boolean
- metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- Returns
- 201 offer.
- Side effects
- Changes or processes the authorized resource: Create bundle-like promotion offer.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 2147483647,
"description": "Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses."
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": "integer"
},
"rewardQuantity": {
"type": "integer"
},
"groupTarget": {
"type": "integer"
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"promoCode": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"deal": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"offer": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"checkoutBacked": {
"type": "boolean"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
Import history and promotion activity
GET promo-codes/imports returns recent import jobs within the complete permitted product scope. Read each import detail for row outcomes; a completed job can still contain skipped or invalid rows. The activity endpoint synthesizes up to 50 summaries from the limited current lists, not an immutable audit log.
The overview, deals and group-buys handlers are compatibility views/actions beside the canonical promotion workspace. A saved group-buy offer is not a promise of complete automatic collection or fulfillment. Inspect checkoutBacked and the supported checkout mechanics. Existing immutable-field, archive, product-scope and $9.99 paid-price rules still apply.
A scheduled deal can prepare a campaign
POST deals/{dealId}/campaign-draft creates a campaign draft and associates it with an authorized deal. It does not approve, send or schedule email. Review the product/publication warnings, audience and content in the campaign workflow. Repeating creation can create additional drafts.
SoundSync
Additional promotion operations
GET
/api/developer/promotions/overview
Read the compatible promotion summary
- Auth
- Account Bearer JWT
- Scope
- marketing.view; writes additionally require marketing.manage. Effective workspace and complete product-scope checks apply.
- Request fields
- query promoLimit: integer
- query dealLimit: integer
- query offerLimit: integer
- Returns
- HTTP 200: promoCodes, deals, offers, imports, stats.
- Notes
- Compatibility alias of GET /api/developer/promotions. Uses marketing.view and assigned-product filtering. These limited-list summary statistics are not a complete accounting statement.
Request, response and error reference
Query and header parameters
[
{
"name": "promoLimit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "dealLimit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "offerLimit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"promoCodes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"deals": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"offers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"imports": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"stats": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
GET
/api/developer/promotions/promo-codes/imports
Read scoped import history
- Auth
- Account Bearer JWT
- Scope
- marketing.view; writes additionally require marketing.manage. Effective workspace and complete product-scope checks apply.
- Request fields
- query limit: integer
- query importLimit: integer
- Returns
- HTTP 200: imports.
- Notes
- Requires marketing.view. Only import jobs whose complete row scope is visible to the caller are returned; selected-product access cannot reveal mixed/foreign jobs. Read the import detail separately for row errors.
Request, response and error reference
Query and header parameters
[
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 25
},
"required": false,
"description": ""
},
{
"name": "importLimit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"imports": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"actorUserId": {
"type": [
"integer",
"null"
]
},
"status": {
"type": "string"
},
"sourceFilename": {
"type": [
"string",
"null"
]
},
"totalRows": {
"type": "integer"
},
"validRows": {
"type": "integer"
},
"importedRows": {
"type": "integer"
},
"skippedRows": {
"type": "integer"
},
"errorRows": {
"type": "integer"
},
"duplicateRows": {
"type": "integer"
},
"options": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"summary": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
POST
/api/developer/promotions/deals
Create a scheduled deal through the compatible route
- Auth
- Account Bearer JWT
- Scope
- marketing.view; writes additionally require marketing.manage. Effective workspace and complete product-scope checks apply.
- Request fields
- type: string
- offerType: string
- title: string
- name: string
- code: string
- productId: integer (required)
- productIds: array
- subscriptionProductIds: array
- activation: automatic | code
- quantityTiers: array. Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.
- purchaseType: one_time | subscription
- discountType: percent | amount
- discountValue: number
- startsAt: string,null (required)
- endsAt: string,null (required)
- expiresAt: string,null
- maxRedemptions: integer,null. Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses.
- minimumOrderAmount: number
- salePrice: number (required)
- allowDiscountOnSaleItems: boolean
- isActive: boolean
- status: string
- requiredQuantity: integer
- rewardQuantity: integer
- groupTarget: integer
- rewardMinimumOrderAmount: number
- rewardMaxRedemptions: integer
- rewardExpiresInDays: integer
- rewardCodePrefix: string
- rewardGrantScope: string
- rewardIncludeFreeItems: boolean
- rewardRefundPolicy: string
- rewardAllowAutomaticOfferStacking: boolean
- metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- Returns
- HTTP 201: promoCode, deal, offer, checkoutBacked.
- Notes
- Compatibility alias of scheduled-deals creation. Requires marketing.view and marketing.manage plus permitted product scope. Paid-price, scheduling and conflict validation apply.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 2147483647,
"description": "Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses."
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": "integer"
},
"rewardQuantity": {
"type": "integer"
},
"groupTarget": {
"type": "integer"
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true,
"required": [
"productId",
"salePrice",
"startsAt",
"endsAt"
]
}HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"promoCode": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"deal": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"offer": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"checkoutBacked": {
"type": "boolean"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
PATCH
/api/developer/promotions/offers/{offerId}
Edit an offer under workspace guards
- Auth
- Account Bearer JWT
- Scope
- marketing.view; writes additionally require marketing.manage. Effective workspace and complete product-scope checks apply.
- Request fields
- type: string
- offerType: string
- title: string
- name: string
- code: string
- productId: integer
- productIds: array
- subscriptionProductIds: array
- activation: automatic | code
- quantityTiers: array. Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.
- purchaseType: one_time | subscription
- discountType: percent | amount
- discountValue: number
- startsAt: string,null
- endsAt: string,null
- expiresAt: string,null
- maxRedemptions: integer,null. Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses.
- minimumOrderAmount: number
- salePrice: number
- allowDiscountOnSaleItems: boolean
- isActive: boolean
- status: string
- requiredQuantity: integer
- rewardQuantity: integer
- groupTarget: integer
- rewardMinimumOrderAmount: number
- rewardMaxRedemptions: integer
- rewardExpiresInDays: integer
- rewardCodePrefix: string
- rewardGrantScope: string
- rewardIncludeFreeItems: boolean
- rewardRefundPolicy: string
- rewardAllowAutomaticOfferStacking: boolean
- metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- Returns
- HTTP 200: offer, checkoutBacked.
- Notes
- Requires marketing.view and marketing.manage plus the complete offer product scope. Uses the workspace offer edit path; immutable product/discount fields and archived-state guards still apply. checkoutBacked is not guaranteed true for every offer type.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 2147483647,
"description": "Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses."
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": "integer"
},
"rewardQuantity": {
"type": "integer"
},
"groupTarget": {
"type": "integer"
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"offer": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"checkoutBacked": {
"type": "boolean"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
GET
/api/developer/promotions/group-buys
List group-buy configuration records
- Auth
- Account Bearer JWT
- Scope
- marketing.view; writes additionally require marketing.manage. Effective workspace and complete product-scope checks apply.
- Returns
- HTTP 200: offers, stats.
- Notes
- Compatibility filtered list of community_group_buy offers. Requires marketing.view and assigned-product scope. A saved offer or target counter is not proof of complete group-buy collection/fulfillment. Prefer the promotion workspace and inspect checkoutBacked.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"offers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"stats": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
POST
/api/developer/promotions/group-buys
Create group-buy configuration
- Auth
- Account Bearer JWT
- Scope
- marketing.view; writes additionally require marketing.manage. Effective workspace and complete product-scope checks apply.
- Request fields
- type: string
- offerType: string
- title: string
- name: string
- code: string
- productId: integer
- productIds: array
- subscriptionProductIds: array
- activation: automatic | code
- quantityTiers: array. Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.
- purchaseType: one_time | subscription
- discountType: percent | amount
- discountValue: number
- startsAt: string,null
- endsAt: string,null
- expiresAt: string,null
- maxRedemptions: integer,null. Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses.
- minimumOrderAmount: number
- salePrice: number
- allowDiscountOnSaleItems: boolean
- isActive: boolean
- status: string
- requiredQuantity: integer
- rewardQuantity: integer
- groupTarget: integer
- rewardMinimumOrderAmount: number
- rewardMaxRedemptions: integer
- rewardExpiresInDays: integer
- rewardCodePrefix: string
- rewardGrantScope: string
- rewardIncludeFreeItems: boolean
- rewardRefundPolicy: string
- rewardAllowAutomaticOfferStacking: boolean
- metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- Returns
- HTTP 201: promoCode, deal, offer, checkoutBacked.
- Notes
- Requires marketing.view and marketing.manage plus owned/assigned products. Forces community_group_buy offerType. This is offer configuration, not a promise of automatic group-buy charging or complete group-buy lifecycle support; inspect checkoutBacked and supported checkout behavior.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 2147483647,
"description": "Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses."
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": "integer"
},
"rewardQuantity": {
"type": "integer"
},
"groupTarget": {
"type": "integer"
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"promoCode": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"deal": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"offer": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"offerType": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"productId": {
"type": [
"integer",
"null"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"subscriptionProductIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"activation": {
"type": "string",
"enum": [
"automatic",
"code"
]
},
"quantityTiers": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.",
"items": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"minimum": 1
},
"discountPercent": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"required": [
"quantity",
"discountPercent"
],
"additionalProperties": true
}
},
"purchaseType": {
"type": "string",
"enum": [
"one_time",
"subscription"
]
},
"discountType": {
"type": "string",
"enum": [
"percent",
"amount"
]
},
"discountValue": {
"type": "number"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"endsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"maxRedemptions": {
"type": [
"integer",
"null"
]
},
"minimumOrderAmount": {
"type": "number"
},
"salePrice": {
"type": "number"
},
"allowDiscountOnSaleItems": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"status": {
"type": "string"
},
"requiredQuantity": {
"type": [
"integer",
"null"
]
},
"rewardQuantity": {
"type": [
"integer",
"null"
]
},
"groupTarget": {
"type": [
"integer",
"null"
]
},
"rewardMinimumOrderAmount": {
"type": "number"
},
"rewardMaxRedemptions": {
"type": "integer"
},
"rewardExpiresInDays": {
"type": "integer"
},
"rewardCodePrefix": {
"type": "string"
},
"rewardGrantScope": {
"type": "string"
},
"rewardIncludeFreeItems": {
"type": "boolean"
},
"rewardRefundPolicy": {
"type": "string"
},
"rewardAllowAutomaticOfferStacking": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"kind": {
"type": "string"
},
"productNames": {
"type": "array",
"items": {
"type": "string"
}
},
"checkoutBacked": {
"type": "boolean"
},
"promoCodeId": {
"type": [
"integer",
"null"
]
},
"savedStatus": {
"type": "string"
},
"revenue": {
"type": [
"number",
"null"
]
},
"purchases": {
"type": [
"integer",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"checkoutBacked": {
"type": "boolean"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
GET
/api/developer/promotions/activity
Read recent promotion summaries
- Auth
- Account Bearer JWT
- Scope
- marketing.view; writes additionally require marketing.manage. Effective workspace and complete product-scope checks apply.
- Returns
- HTTP 200: activity.
- Notes
- Requires marketing.view and assigned-product scope. Returns up to 50 creation/status summaries synthesized from the limited current promo/deal/offer lists, not an immutable audit log or complete event history.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"activity": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
POST
/api/developer/promotions/deals/{dealId}/campaign-draft
Create a campaign draft from a deal
- Auth
- Account Bearer JWT
- Scope
- marketing.view; writes additionally require marketing.manage. Effective workspace and complete product-scope checks apply.
- Request fields
- name: string
- subject: string
- preheader: string
- bodyHtml: string
- bodyText: string
- audienceFilter: object
- fromName: string
- fromEmail: string
- replyToEmail: string
- primaryProductId: integer
- heroImageUrl: string
- ctaLabel: string
- ctaUrl: string
- sourceType: string
- sourceId: string
- metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- Returns
- HTTP 201: campaign, audience, deal, product, warnings.
- Notes
- Requires marketing.view and marketing.manage and access to the scheduled deal product. Creates a new campaign draft and links it to the deal; it does not send, schedule or approve email. Repeat calls can create additional drafts. Product publication warnings and campaign audience/suppression checks remain relevant.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"subject": {
"type": "string"
},
"preheader": {
"type": "string"
},
"bodyHtml": {
"type": "string"
},
"bodyText": {
"type": "string"
},
"audienceFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"fromName": {
"type": "string"
},
"fromEmail": {
"type": "string",
"format": "email"
},
"replyToEmail": {
"type": "string",
"format": "email"
},
"primaryProductId": {
"type": "integer",
"minimum": 1
},
"heroImageUrl": {
"type": "string"
},
"ctaLabel": {
"type": "string"
},
"ctaUrl": {
"type": "string"
},
"sourceType": {
"type": "string"
},
"sourceId": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"campaign": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"subject": {
"type": "string"
},
"preheader": {
"type": "string"
},
"bodyHtml": {
"type": "string"
},
"bodyText": {
"type": "string"
},
"audienceFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"fromName": {
"type": "string"
},
"fromEmail": {
"type": "string",
"format": "email"
},
"replyToEmail": {
"type": "string",
"format": "email"
},
"primaryProductId": {
"type": "integer",
"minimum": 1
},
"heroImageUrl": {
"type": "string"
},
"ctaLabel": {
"type": "string"
},
"ctaUrl": {
"type": "string"
},
"sourceType": {
"type": "string"
},
"sourceId": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"status": {
"type": "string"
},
"audienceEstimateCount": {
"type": "integer"
},
"audienceSnapshotCount": {
"type": "integer"
},
"testSentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"approvedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"scheduledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sendStartedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"canceledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"failureReason": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"report": {
"type": "object",
"properties": {
"recipients": {
"type": "integer"
},
"queued": {
"type": "integer"
},
"sending": {
"type": "integer"
},
"sent": {
"type": "integer"
},
"skipped": {
"type": "integer"
},
"failed": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"opened": {
"type": "integer"
},
"clicked": {
"type": "integer"
},
"uniqueOpened": {
"type": "integer"
},
"uniqueClicked": {
"type": "integer"
},
"delivered": {
"type": [
"integer",
"null"
]
},
"recordedDelivered": {
"type": "integer"
},
"deliverySource": {
"type": "string",
"enum": [
"not_sent",
"provider_channel",
"recorded_receipts",
"unavailable"
]
},
"lastDeliveryAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"recordedOpenEvents": {
"type": "integer"
},
"recordedClickEvents": {
"type": "integer"
},
"engagementUnchecked": {
"type": "integer"
},
"engagementDenominator": {
"type": "integer"
},
"providerBounced": {
"type": [
"integer",
"null"
]
},
"providerUnsubscribed": {
"type": [
"integer",
"null"
]
},
"providerComplaints": {
"type": [
"integer",
"null"
]
},
"performanceSource": {
"type": "string",
"enum": [
"elastic_channel",
"recorded_events"
]
},
"providerStatsCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"providerStatsError": {
"type": [
"string",
"null"
]
},
"providerStatsStatus": {
"type": "string",
"enum": [
"not_sent",
"pending",
"retrying",
"ready",
"stale",
"unavailable"
]
},
"attributedOrders": {
"type": "integer"
},
"revenueCents": {
"type": "integer"
},
"openRate": {
"type": "object",
"properties": {
"percent": {
"type": [
"number",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"clickRate": {
"type": "object",
"properties": {
"percent": {
"type": [
"number",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"clickToOpenRate": {
"type": "number"
},
"statusBreakdown": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"percentComplete": {
"type": "number"
}
},
"additionalProperties": true
},
"denominatorSource": {
"type": "string",
"enum": [
"sent",
"delivered"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"audience": {
"type": "object",
"properties": {
"filter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"resolvedFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"totalMatchingContacts": {
"type": "integer"
},
"finalSendableEstimate": {
"type": "integer"
},
"selectedProductOwnerCount": {
"type": [
"integer",
"null"
]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"excluded": {
"type": "object",
"properties": {
"noMarketingConsent": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"suppressed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"invalid": {
"type": "integer"
},
"missingEmail": {
"type": "integer"
},
"duplicateEmail": {
"type": "integer"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"deal": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"imageUrl": {
"type": "string"
},
"url": {
"type": "string"
}
},
"additionalProperties": true
},
"warnings": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
Tiered and automatic multi-product requests
Use offerType:tiered_cart_discount with productIds, activation:automatic or code, and quantityTiers:[{quantity,discountPercent}]. A code-activated offer also requires code. multi_product_discount supports the same activation choice with its own discount fields. POST /offers and POST /workspace/offer use the same per-type validation.
Tier quantities count distinct positive-priced eligible one-time products, not units. The highest reached quantity threshold applies to all eligible copies at their current eligible prices. Read the saved normalized offer and checkoutBacked; do not infer eligibility from a title or from the existence of a promo-code row. Existing immutable-field and archived-state edit guards remain in force.
SoundSync
Illustrative automatic cart tiers
Create a tiered offer for three owned products
curl --fail-with-body -sS -X POST "$SOUNDSYNC_API_BASE/api/developer/promotions/offers" \
-H "Authorization: Bearer $DEVELOPER_TOKEN" -H "Content-Type: application/json" \
--data '{"offerType":"tiered_cart_discount","title":"Build your collection","productIds":[123,124,125],"activation":"automatic","quantityTiers":[{"quantity":2,"discountPercent":10},{"quantity":3,"discountPercent":15}]}'SoundSync