> ## 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 Promotion > Create a central promotion targeting connected stores. Requires `promotions:write`. Fixed-amount discounts resolve currency from the selected store countries. ## OpenAPI ````yaml /openapi.json post /api/v1/promotions 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.sg 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: campaigns description: Campaign briefs, offer windows, and marketplace runs x-group: Campaigns - name: developer-platform description: Authenticated developer platform APIs x-group: Developer Platform - name: documents description: Knowledge base document uploads x-group: Knowledge Base - 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: settlements description: settlements x-group: Settlements - name: ucp description: Universal Commerce Protocol x-group: UCP paths: /api/v1/promotions: post: tags: - promotions summary: Create Promotion description: >- Create a central promotion targeting connected stores. Requires `promotions:write`. Fixed-amount discounts resolve currency from the selected store countries. operationId: post_v1_promotions requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - name - discountType - discountValue - targetStores properties: organizationId: type: string maxLength: 120 description: >- Required for session auth across multiple organizations. Optional for OAuth/API keys bound to one organization. name: type: string maxLength: 200 description: type: - string - 'null' maxLength: 2000 kind: type: string enum: - product_discount - flash_sale - voucher - gift_with_purchase - buy_x_get_y - bundle_deal - free_shipping - early_bird_price discountType: type: string enum: - percentage - fixed_amount discountValue: type: number minimum: 0 description: >- Discount amount or percentage. Use 0 for gift/sample-only and free Buy-X-Get-Y mechanics. targetStores: type: array minItems: 1 maxItems: 100 items: type: object additionalProperties: false required: - marketplace - country - storeId properties: marketplace: type: string enum: - lazada - shopee - tiktok - shopify - amazon - zalora - ebay country: type: string storeId: type: string description: >- Connected stores as `{ marketplace, country, storeId }`. Copy from existing promotion targetStores or product marketplaceDetails. status: type: string enum: - draft - scheduled - active - paused - ended - archived default: active description: >- Defaults to active. Future start dates display as scheduled. Use draft to save without activation; explicit inactive lifecycle states are preserved. startsAt: type: - string - 'null' format: date-time endsAt: type: - string - 'null' format: date-time minSalePrice: type: - number - 'null' minimum: 0 maxDiscountAmount: type: - number - 'null' minimum: 0 minSpend: type: - number - 'null' minimum: 0 description: Lazada voucher minimum spend. Defaults to 1 when unset. totalUsageLimit: type: - integer - 'null' minimum: 1 description: >- Total redemption/order limit, or per-SKU promotional quantity for flash sales. mechanicConfig: type: object additionalProperties: false properties: voucherCampaign: type: object additionalProperties: false required: - campaignId - sessionId - termsAccepted description: >- Exact Shopee campaign/session for Campaign Voucher Nomination, with reviewed participation obligations. Nomination remains a draft until Shopee approval. properties: campaignId: type: string minLength: 1 maxLength: 40 pattern: ^[1-9][0-9]{0,39}$ sessionId: type: string minLength: 1 maxLength: 40 pattern: ^[1-9][0-9]{0,39}$ termsAccepted: type: boolean voucherType: type: - string - 'null' 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 - null description: >- Exact marketplace voucher subtype. Native types use APIs; Seller Center-only types use a browser AOP with per-store eligibility checks. browserAutomation: type: - object - 'null' additionalProperties: false properties: variableValues: type: object maxProperties: 100 additionalProperties: type: string maxLength: 8000 description: >- Optional overrides for the selected AOP's declared variables. promotionId, action, and storeId are supplied automatically; the AOP loads the campaign with get_promotions. aopId: type: string minLength: 1 maxLength: 160 description: >- Optional organization AOP override. Omit to select the built-in marketplace AOP. instructions: type: string maxLength: 8000 voucherScope: type: string enum: - products - shop voucherReward: type: string enum: - discount - coins_cashback exclusiveStreamerUsernames: type: array maxItems: 15 items: type: string minLength: 1 maxLength: 64 description: >- Approved Shopee usernames targeted by an Exclusive Streamer voucher. The Seller Centre API resolves eligible streamer identities; user IDs must not be supplied here. voucherAudience: type: string enum: - general - shop_follow voucherDisplayChannels: type: array maxItems: 4 description: >- Shopee supports all, feed, live, order_page (update only), or [] for hidden. Lazada requires exactly one of all, live, followers, offline; followers requires voucherScope=shop. 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 minimum: 1 maximum: 999 gifts: type: array minItems: 1 maxItems: 20 items: type: object additionalProperties: false required: - productId - totalClaimLimit properties: productId: type: string format: uuid variantId: type: - string - 'null' format: uuid totalClaimLimit: type: integer minimum: 1 maximum: 99999 buyQuantity: type: integer minimum: 1 maximum: 999 getQuantity: type: integer minimum: 1 maximum: 999 benefitProductIds: type: array minItems: 1 maxItems: 200 items: type: string format: uuid benefitType: type: string enum: - free - percentage - fixed_amount benefitValue: type: number minimum: 0 maxApplicationsPerOrder: type: integer minimum: 1 maximum: 999 bundleMinimumQuantity: type: integer minimum: 2 maximum: 3000 shippingDeliveryOption: type: string pattern: ^[A-Z0-9_]{1,40}$ description: >- Free shipping delivery option offered by the Lazada store; defaults to STANDARD. shippingBudget: type: number exclusiveMinimum: 0 description: >- Free shipping subsidy budget in the store currency. Omit for an unlimited budget. storeDiscounts: type: array maxItems: 100 description: >- Patch discount overrides by exact target store key. Other stores retain their terms. Null discountValue restores shared terms for that store. items: type: object additionalProperties: false required: - storeKey - discountType - discountValue properties: storeKey: type: string minLength: 1 maxLength: 255 discountType: type: string enum: - percentage - fixed_amount discountValue: type: - number - 'null' minimum: 0 description: Percentage must not exceed 100. example: name: Christmas discountType: fixed_amount discountValue: 12 targetStores: - marketplace: shopee country: singapore storeId: '115085776' startsAt: '2026-07-06T17:00:00.000Z' endsAt: '2026-08-02T03:59:00.000Z' responses: '201': description: Promotion created. content: application/json: schema: type: object required: - promotion properties: promotion: type: object '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden or missing `promotions:write` scope '429': description: Rate limit exceeded '500': description: Internal Server Error 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.