> ## Documentation Index > Fetch the complete documentation index at: https://docs.omnicommerce.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /openapi.json post /api/v1/promotions/batch openapi: 3.1.0 info: title: OmniCommerce API version: 1.0.0 license: name: Proprietary url: https://omnicommerce.sg/terms description: >- OmniCommerce API surface for agents and developer integrations. Includes public endpoints (merchant discovery, product search, compare, catalog, ACO retrieval) and authenticated endpoints (product management via API key Bearer tokens). servers: - url: https://omnicommerce.ai description: Production - url: http://localhost:3000 description: Local development security: [] tags: - name: agentic-checkout description: Merchant-fulfilled agentic checkout x-group: Agentic Checkout - name: agents description: agents x-group: Agents - name: analytics description: Sales performance across marketplaces x-group: Analytics - name: aops description: Agent operating procedures x-group: AOPs - name: branding description: branding x-group: Branding - name: campaigns description: Campaign briefs, offer windows, and marketplace runs x-group: Campaigns - name: commerce description: commerce x-group: Commerce - name: developer-platform description: Authenticated developer platform APIs x-group: Developer Platform - name: documents description: Knowledge base document uploads x-group: Knowledge Base - name: inventory description: Inventory quantities, planning signals, and marketplace listing absence x-group: Inventory - name: looks description: AI-styled product looks x-group: Looks - name: oauth description: OAuth token endpoints x-group: OAuth - name: orders description: Workspace and agentic orders x-group: Orders - name: organizations description: Organization management x-group: Organizations - name: price-books description: Marketplace list-price markup rules x-group: Price Books - name: products description: Product CRUD, bulk import, enrichment, publish, and delist x-group: Products - name: promotions description: Central promotions and marketplace sync x-group: Promotions - name: public-agent description: Public agent discovery and catalog APIs x-group: Public Agent - name: returns description: returns x-group: Returns - name: reviews description: Marketplace product reviews and seller replies x-group: Reviews - name: scripts description: scripts x-group: Scripts - name: settlements description: settlements x-group: Settlements - name: ucp description: Universal Commerce Protocol x-group: UCP paths: /api/v1/promotions/batch: post: tags: - promotions summary: Create Promotions with Products description: >- 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. operationId: post_v1_promotions_batch requestBody: required: true content: application/json: schema: type: object properties: organizationId: description: >- Required for session auth. Optional for an API key, which already identifies the organization. type: string minLength: 1 maxLength: 120 promotions: minItems: 1 maxItems: 50 type: array items: type: object properties: promotion: type: object properties: name: type: string minLength: 1 maxLength: 200 description: anyOf: - type: string maxLength: 2000 - type: 'null' kind: description: >- Canonical OmniCommerce promotion mechanic: product discount, flash sale, voucher, gift with purchase, Buy-X-Get-Y, bundle deal, or Lazada-only free shipping and early bird price. type: string enum: - product_discount - flash_sale - voucher - gift_with_purchase - buy_x_get_y - bundle_deal - free_shipping - early_bird_price salesChannels: minItems: 1 type: array items: type: string enum: - pdp - live discountType: type: string enum: - percentage - fixed_amount discountValue: type: number minimum: 0 storeDiscounts: description: >- Patch discount terms for exact target store keys; unnamed stores remain unchanged. Null discountValue restores shared campaign terms for that store. maxItems: 100 type: array items: type: object properties: storeKey: type: string minLength: 1 maxLength: 255 discountType: type: string enum: - percentage - fixed_amount discountValue: anyOf: - type: number minimum: 0 - type: 'null' required: - storeKey - discountType - discountValue additionalProperties: false targetStores: description: >- Up to 100 connected stores for create (required) or update. Copy marketplace, country, and storeId from get_promotions targetStores or find_products marketplaceDetails. Do not concatenate a storeKeys string. minItems: 1 maxItems: 100 type: array items: type: object properties: marketplace: type: string enum: - lazada - shopee - tiktok - shopify - amazon - zalora - ebay country: type: string minLength: 1 maxLength: 80 storeId: type: string minLength: 1 maxLength: 120 required: - marketplace - country - storeId additionalProperties: false startsAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ - type: 'null' description: Promotion start date/time as an ISO 8601 string. endsAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ - type: 'null' description: Promotion end date/time as an ISO 8601 string. status: description: >- Create is active unless this is draft. Future startsAt still displays as scheduled. Do not call activate after create. type: string enum: - draft - scheduled - active - paused - ended - archived minSalePrice: anyOf: - type: number minimum: 0 - type: 'null' maxDiscountAmount: anyOf: - type: number minimum: 0 - type: 'null' minSpend: anyOf: - type: number minimum: 0 - type: 'null' voucherCode: anyOf: - type: string minLength: 1 maxLength: 100 - type: 'null' claimStartsAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ - type: 'null' totalUsageLimit: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' perBuyerLimit: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' mechanicConfig: type: object properties: voucherType: description: >- Voucher subtype from get_promotions capabilities.voucherTypes. Browser AOP types (delivery=browser_aop) are writable Seller Center vouchers. Omit browserAutomation.aopId to use the built-in marketplace AOP. anyOf: - type: string enum: - shopee_shop - shopee_product - shopee_private - shopee_live - shopee_video - shopee_new_buyer - shopee_repeat_buyer - shopee_campaign - shopee_follow_prize - shopee_exclusive_streamer - shopee_welcome - shopee_member_repeat_buyer - shopee_exclusive - shopee_redemption - shopee_exclusive_creator - lazada_store_follower - lazada_regular - lazada_store_new_buyer - lazada_live - lazada_offline - lazada_co_funded - lazada_welcome - lazada_linked_member - lazada_new_member - lazada_member_exclusive - lazada_points_redeemable - tiktok_seller_coupon - shopify_discount_code - amazon_promotion_code - zalora_seller_voucher - ebay_coded_coupon - type: 'null' voucherCampaign: description: >- Campaign voucher targeting: exact campaignId/sessionId from Seller Center and termsAccepted only after the seller reviewed participation obligations. Required for shopee_campaign; nomination creates a draft awaiting marketplace review. type: object properties: campaignId: type: string pattern: ^[1-9]\d{0,39}$ sessionId: type: string pattern: ^[1-9]\d{0,39}$ termsAccepted: type: boolean required: - campaignId - sessionId - termsAccepted additionalProperties: false browserAutomation: anyOf: - type: object properties: aopId: type: string minLength: 1 maxLength: 160 variableValues: type: object propertyNames: type: string minLength: 1 maxLength: 160 additionalProperties: type: string maxLength: 8000 instructions: type: string maxLength: 8000 additionalProperties: false - type: 'null' voucherScope: description: >- shop = all products, products = selected assigned products. Repeat Buyer defaults to shop. type: string enum: - products - shop voucherReward: description: >- Seller Center reward type. coins_cashback is a percentage greater than 3 and does not reduce salePrice. type: string enum: - discount - coins_cashback voucherAudience: type: string enum: - general - shop_follow repeatPurchaseMinCount: description: >- Shopee Repeat Buyer: minimum completed shop orders, 1 or 2. Required for shopee_repeat_buyer. type: integer minimum: 1 maximum: 999 repeatPurchaseLookbackDays: description: >- Shopee Repeat Buyer: lookback window in days, one of 30, 90, 180 or 365. Required for shopee_repeat_buyer. type: integer minimum: 1 maximum: 365 smartVoucher: description: >- Shopee Smart Voucher toggle. Used by New Buyer and similar portal types. type: boolean followPrizeExpiryDays: description: >- Shopee Follow Prize: days after claim until expiry. Seller Center is 7. type: integer minimum: 1 maximum: 30 videoDisplayMode: description: >- Shopee Video display: shopee_video = all Shopee Video; creator_video = targeted creator videos only. type: string enum: - shopee_video - creator_video exclusiveCreatorUsernames: description: >- Exclusive Creator Voucher: up to 15 Shopee usernames. maxItems: 15 type: array items: type: string minLength: 1 maxLength: 64 exclusiveStreamerUsernames: description: >- Exclusive Streamer Voucher: up to 15 Shopee usernames. maxItems: 15 type: array items: type: string minLength: 1 maxLength: 64 voucherDisplayChannels: description: >- Shopee display setting. ["all"] = display on all pages; [] = hidden/share by code. maxItems: 4 type: array items: type: string enum: - all - feed - live - order_page - followers - offline bundlePriceType: type: string enum: - discount - fixed_price bundleTiers: maxItems: 2 type: array items: type: object properties: minimumQuantity: type: integer minimum: 2 maximum: 3000 discountValue: type: number exclusiveMinimum: 0 required: - minimumQuantity - discountValue thresholdType: type: string enum: - item_quantity - order_amount thresholdValue: type: number exclusiveMinimum: 0 giftType: type: string enum: - gift - sample giftQuantity: type: integer exclusiveMinimum: 0 maximum: 999 gifts: minItems: 1 maxItems: 20 type: array items: type: object properties: productId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ variantId: anyOf: - type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ - type: 'null' totalClaimLimit: type: integer minimum: 1 maximum: 99999 required: - productId - totalClaimLimit additionalProperties: false buyQuantity: type: integer exclusiveMinimum: 0 maximum: 999 getQuantity: type: integer exclusiveMinimum: 0 maximum: 999 benefitProductIds: minItems: 1 maxItems: 200 type: array items: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ benefitType: type: string enum: - free - percentage - fixed_amount benefitValue: type: number minimum: 0 maxApplicationsPerOrder: type: integer exclusiveMinimum: 0 maximum: 999 bundleMinimumQuantity: type: integer minimum: 2 maximum: 3000 shippingDeliveryOption: description: >- Free shipping delivery option. Lazada: STANDARD (default), ECONOMY, EXPRESS, SELLER_OWN_FLEET or P2P, as offered by the store. type: string pattern: ^[A-Z0-9_]{1,40}$ shippingBudget: description: >- Free shipping: total shipping subsidy budget in the store currency. Omit for an unlimited budget. type: number exclusiveMinimum: 0 additionalProperties: false additionalProperties: false productIds: minItems: 1 maxItems: 200 type: array items: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ productDiscounts: maxItems: 200 type: array items: type: object properties: productId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ discountValue: anyOf: - type: number exclusiveMinimum: 0 - type: 'null' required: - productId - discountValue required: - promotion additionalProperties: false required: - promotions additionalProperties: false responses: '200': description: >- Canonical operation result. Inspect aggregate and per-target success and marketplace delivery evidence. content: application/json: schema: type: object properties: success: type: boolean succeededCount: type: integer minimum: 0 maximum: 9007199254740991 failedCount: type: integer minimum: 0 maximum: 9007199254740991 promotionIds: type: array items: type: string results: type: array items: type: object propertyNames: type: string additionalProperties: {} error: type: string required: - success - succeededCount - failedCount - promotionIds - results '400': description: Invalid input or domain validation failed. '401': description: Missing or expired credentials. '403': description: >- Insufficient current organization, store, operation or OAuth permissions. security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- Bearer API key for server-to-server access. Session auth is also supported in first-party UI flows. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.