Create Promotions with Products

curl --request POST \
  --url https://omnicommerce.ai/api/v1/promotions/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "promotions": [
    {
      "promotion": {
        "name": "<string>",
        "description": "<string>",
        "salesChannels": [],
        "discountValue": 1,
        "storeDiscounts": [
          {
            "storeKey": "<string>",
            "discountValue": 1
          }
        ],
        "targetStores": [
          {
            "country": "<string>",
            "storeId": "<string>"
          }
        ],
        "startsAt": "2023-11-07T05:31:56Z",
        "endsAt": "2023-11-07T05:31:56Z",
        "minSalePrice": 1,
        "maxDiscountAmount": 1,
        "minSpend": 1,
        "voucherCode": "<string>",
        "claimStartsAt": "2023-11-07T05:31:56Z",
        "totalUsageLimit": 4503599627370495,
        "perBuyerLimit": 4503599627370495,
        "mechanicConfig": {
          "browserAutomation": {
            "aopId": "<string>",
            "variableValues": {},
            "instructions": "<string>"
          },
          "repeatPurchaseMinCount": 500,
          "repeatPurchaseLookbackDays": 183,
          "smartVoucher": true,
          "followPrizeExpiryDays": 15,
          "exclusiveCreatorUsernames": [
            "<string>"
          ],
          "exclusiveStreamerUsernames": [
            "<string>"
          ],
          "voucherDisplayChannels": [],
          "bundleTiers": [
            {
              "minimumQuantity": 1501,
              "discountValue": 123
            }
          ],
          "thresholdValue": 123,
          "giftQuantity": 123,
          "gifts": [
            {
              "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "totalClaimLimit": 50000,
              "variantId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
            }
          ],
          "buyQuantity": 123,
          "getQuantity": 123,
          "benefitProductIds": [
            "3c90c3cc-0d44-4b50-8888-8dd25736052a"
          ],
          "benefitValue": 1,
          "maxApplicationsPerOrder": 123,
          "bundleMinimumQuantity": 1501,
          "shippingDeliveryOption": "<string>",
          "shippingBudget": 123
        }
      },
      "productIds": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "productDiscounts": [
        {
          "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "discountValue": 1
        }
      ]
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    promotions: [
      {
        promotion: {
          name: '<string>',
          description: '<string>',
          salesChannels: [],
          discountValue: 1,
          storeDiscounts: [{storeKey: '<string>', discountValue: 1}],
          targetStores: [{country: '<string>', storeId: '<string>'}],
          startsAt: '2023-11-07T05:31:56Z',
          endsAt: '2023-11-07T05:31:56Z',
          minSalePrice: 1,
          maxDiscountAmount: 1,
          minSpend: 1,
          voucherCode: '<string>',
          claimStartsAt: '2023-11-07T05:31:56Z',
          totalUsageLimit: 4503599627370495,
          perBuyerLimit: 4503599627370495,
          mechanicConfig: {
            browserAutomation: {aopId: '<string>', variableValues: {}, instructions: '<string>'},
            repeatPurchaseMinCount: 500,
            repeatPurchaseLookbackDays: 183,
            smartVoucher: true,
            followPrizeExpiryDays: 15,
            exclusiveCreatorUsernames: ['<string>'],
            exclusiveStreamerUsernames: ['<string>'],
            voucherDisplayChannels: [],
            bundleTiers: [{minimumQuantity: 1501, discountValue: 123}],
            thresholdValue: 123,
            giftQuantity: 123,
            gifts: [
              {
                productId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
                totalClaimLimit: 50000,
                variantId: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
              }
            ],
            buyQuantity: 123,
            getQuantity: 123,
            benefitProductIds: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
            benefitValue: 1,
            maxApplicationsPerOrder: 123,
            bundleMinimumQuantity: 1501,
            shippingDeliveryOption: '<string>',
            shippingBudget: 123
          }
        },
        productIds: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
        productDiscounts: [{productId: '3c90c3cc-0d44-4b50-8888-8dd25736052a', discountValue: 1}]
      }
    ]
  })
};

fetch('https://omnicommerce.ai/api/v1/promotions/batch', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://omnicommerce.ai/api/v1/promotions/batch"

payload = { "promotions": [
        {
            "promotion": {
                "name": "<string>",
                "description": "<string>",
                "salesChannels": [],
                "discountValue": 1,
                "storeDiscounts": [
                    {
                        "storeKey": "<string>",
                        "discountValue": 1
                    }
                ],
                "targetStores": [
                    {
                        "country": "<string>",
                        "storeId": "<string>"
                    }
                ],
                "startsAt": "2023-11-07T05:31:56Z",
                "endsAt": "2023-11-07T05:31:56Z",
                "minSalePrice": 1,
                "maxDiscountAmount": 1,
                "minSpend": 1,
                "voucherCode": "<string>",
                "claimStartsAt": "2023-11-07T05:31:56Z",
                "totalUsageLimit": 4503599627370495,
                "perBuyerLimit": 4503599627370495,
                "mechanicConfig": {
                    "browserAutomation": {
                        "aopId": "<string>",
                        "variableValues": {},
                        "instructions": "<string>"
                    },
                    "repeatPurchaseMinCount": 500,
                    "repeatPurchaseLookbackDays": 183,
                    "smartVoucher": True,
                    "followPrizeExpiryDays": 15,
                    "exclusiveCreatorUsernames": ["<string>"],
                    "exclusiveStreamerUsernames": ["<string>"],
                    "voucherDisplayChannels": [],
                    "bundleTiers": [
                        {
                            "minimumQuantity": 1501,
                            "discountValue": 123
                        }
                    ],
                    "thresholdValue": 123,
                    "giftQuantity": 123,
                    "gifts": [
                        {
                            "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
                            "totalClaimLimit": 50000,
                            "variantId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
                        }
                    ],
                    "buyQuantity": 123,
                    "getQuantity": 123,
                    "benefitProductIds": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
                    "benefitValue": 1,
                    "maxApplicationsPerOrder": 123,
                    "bundleMinimumQuantity": 1501,
                    "shippingDeliveryOption": "<string>",
                    "shippingBudget": 123
                }
            },
            "productIds": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
            "productDiscounts": [
                {
                    "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
                    "discountValue": 1
                }
            ]
        }
    ] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "success": true,
  "succeededCount": 4503599627370495,
  "failedCount": 4503599627370495,
  "promotionIds": [
    "<string>"
  ],
  "results": [
    {}
  ],
  "error": "<string>"
}

Promotions

Create Promotions with Products

Create 1–50 promotions using the shared flat promotion-write contract, with qualifying products and per-product discounts. Set promotion.status=draft explicitly when preparing drafts; otherwise the canonical creation flow activates promotions and requires publish permission. Saved IDs and delivery evidence are retained on partial delivery failure; retry those IDs rather than creating duplicates.

Requires promotions:write. API keys and delegated Computer credentials resolve organization scope without browser cookies; optional organizationId must match that scope.

POST

api

promotions

batch

Create Promotions with Products

curl --request POST \
  --url https://omnicommerce.ai/api/v1/promotions/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "promotions": [
    {
      "promotion": {
        "name": "<string>",
        "description": "<string>",
        "salesChannels": [],
        "discountValue": 1,
        "storeDiscounts": [
          {
            "storeKey": "<string>",
            "discountValue": 1
          }
        ],
        "targetStores": [
          {
            "country": "<string>",
            "storeId": "<string>"
          }
        ],
        "startsAt": "2023-11-07T05:31:56Z",
        "endsAt": "2023-11-07T05:31:56Z",
        "minSalePrice": 1,
        "maxDiscountAmount": 1,
        "minSpend": 1,
        "voucherCode": "<string>",
        "claimStartsAt": "2023-11-07T05:31:56Z",
        "totalUsageLimit": 4503599627370495,
        "perBuyerLimit": 4503599627370495,
        "mechanicConfig": {
          "browserAutomation": {
            "aopId": "<string>",
            "variableValues": {},
            "instructions": "<string>"
          },
          "repeatPurchaseMinCount": 500,
          "repeatPurchaseLookbackDays": 183,
          "smartVoucher": true,
          "followPrizeExpiryDays": 15,
          "exclusiveCreatorUsernames": [
            "<string>"
          ],
          "exclusiveStreamerUsernames": [
            "<string>"
          ],
          "voucherDisplayChannels": [],
          "bundleTiers": [
            {
              "minimumQuantity": 1501,
              "discountValue": 123
            }
          ],
          "thresholdValue": 123,
          "giftQuantity": 123,
          "gifts": [
            {
              "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "totalClaimLimit": 50000,
              "variantId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
            }
          ],
          "buyQuantity": 123,
          "getQuantity": 123,
          "benefitProductIds": [
            "3c90c3cc-0d44-4b50-8888-8dd25736052a"
          ],
          "benefitValue": 1,
          "maxApplicationsPerOrder": 123,
          "bundleMinimumQuantity": 1501,
          "shippingDeliveryOption": "<string>",
          "shippingBudget": 123
        }
      },
      "productIds": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "productDiscounts": [
        {
          "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "discountValue": 1
        }
      ]
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    promotions: [
      {
        promotion: {
          name: '<string>',
          description: '<string>',
          salesChannels: [],
          discountValue: 1,
          storeDiscounts: [{storeKey: '<string>', discountValue: 1}],
          targetStores: [{country: '<string>', storeId: '<string>'}],
          startsAt: '2023-11-07T05:31:56Z',
          endsAt: '2023-11-07T05:31:56Z',
          minSalePrice: 1,
          maxDiscountAmount: 1,
          minSpend: 1,
          voucherCode: '<string>',
          claimStartsAt: '2023-11-07T05:31:56Z',
          totalUsageLimit: 4503599627370495,
          perBuyerLimit: 4503599627370495,
          mechanicConfig: {
            browserAutomation: {aopId: '<string>', variableValues: {}, instructions: '<string>'},
            repeatPurchaseMinCount: 500,
            repeatPurchaseLookbackDays: 183,
            smartVoucher: true,
            followPrizeExpiryDays: 15,
            exclusiveCreatorUsernames: ['<string>'],
            exclusiveStreamerUsernames: ['<string>'],
            voucherDisplayChannels: [],
            bundleTiers: [{minimumQuantity: 1501, discountValue: 123}],
            thresholdValue: 123,
            giftQuantity: 123,
            gifts: [
              {
                productId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
                totalClaimLimit: 50000,
                variantId: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
              }
            ],
            buyQuantity: 123,
            getQuantity: 123,
            benefitProductIds: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
            benefitValue: 1,
            maxApplicationsPerOrder: 123,
            bundleMinimumQuantity: 1501,
            shippingDeliveryOption: '<string>',
            shippingBudget: 123
          }
        },
        productIds: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
        productDiscounts: [{productId: '3c90c3cc-0d44-4b50-8888-8dd25736052a', discountValue: 1}]
      }
    ]
  })
};

fetch('https://omnicommerce.ai/api/v1/promotions/batch', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://omnicommerce.ai/api/v1/promotions/batch"

payload = { "promotions": [
        {
            "promotion": {
                "name": "<string>",
                "description": "<string>",
                "salesChannels": [],
                "discountValue": 1,
                "storeDiscounts": [
                    {
                        "storeKey": "<string>",
                        "discountValue": 1
                    }
                ],
                "targetStores": [
                    {
                        "country": "<string>",
                        "storeId": "<string>"
                    }
                ],
                "startsAt": "2023-11-07T05:31:56Z",
                "endsAt": "2023-11-07T05:31:56Z",
                "minSalePrice": 1,
                "maxDiscountAmount": 1,
                "minSpend": 1,
                "voucherCode": "<string>",
                "claimStartsAt": "2023-11-07T05:31:56Z",
                "totalUsageLimit": 4503599627370495,
                "perBuyerLimit": 4503599627370495,
                "mechanicConfig": {
                    "browserAutomation": {
                        "aopId": "<string>",
                        "variableValues": {},
                        "instructions": "<string>"
                    },
                    "repeatPurchaseMinCount": 500,
                    "repeatPurchaseLookbackDays": 183,
                    "smartVoucher": True,
                    "followPrizeExpiryDays": 15,
                    "exclusiveCreatorUsernames": ["<string>"],
                    "exclusiveStreamerUsernames": ["<string>"],
                    "voucherDisplayChannels": [],
                    "bundleTiers": [
                        {
                            "minimumQuantity": 1501,
                            "discountValue": 123
                        }
                    ],
                    "thresholdValue": 123,
                    "giftQuantity": 123,
                    "gifts": [
                        {
                            "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
                            "totalClaimLimit": 50000,
                            "variantId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
                        }
                    ],
                    "buyQuantity": 123,
                    "getQuantity": 123,
                    "benefitProductIds": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
                    "benefitValue": 1,
                    "maxApplicationsPerOrder": 123,
                    "bundleMinimumQuantity": 1501,
                    "shippingDeliveryOption": "<string>",
                    "shippingBudget": 123
                }
            },
            "productIds": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
            "productDiscounts": [
                {
                    "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
                    "discountValue": 1
                }
            ]
        }
    ] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "success": true,
  "succeededCount": 4503599627370495,
  "failedCount": 4503599627370495,
  "promotionIds": [
    "<string>"
  ],
  "results": [
    {}
  ],
  "error": "<string>"
}

Authorizations

Authorization

string

header

required

Bearer API key for server-to-server access. Session auth is also supported in first-party UI flows.

Body

application/json

promotions

object[]

required

Required array length: 1 - 50 elements

Show child attributes

organizationId

string

Required for session auth. Optional for an API key, which already identifies the organization.

Required string length: 1 - 120

Response

Canonical operation result. Inspect aggregate and per-target success and marketplace delivery evidence.

success

boolean

required

succeededCount

integer

required

Required range: 0 <= x <= 9007199254740991

failedCount

integer

required

Required range: 0 <= x <= 9007199254740991

promotionIds

string[]

required

results

object[]

required

Show child attributes

error

string

Overview

Endpoints

Webhooks

Create Promotions with Products

Authorizations

Body

Response