> ## Documentation Index > Fetch the complete documentation index at: https://docs.omnicommerce.sg/llms.txt > Use this file to discover all available pages before exploring further. # Act on Campaign > Approve, start, end, resume, retry, or decide a proposed live change. Approve, run, resume, and approving a change must be called by the named approver. Requires `promotions:write`. ## OpenAPI ````yaml /openapi.json post /api/v1/campaigns/{campaignId}/actions 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: aops description: Agent operating procedures x-group: AOPs - name: campaigns description: Campaign briefs, offer windows, and marketplace runs x-group: Campaigns - name: commerce description: Root commerce discovery x-group: Commerce - name: developer-platform description: Authenticated developer platform APIs x-group: Developer Platform - 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: settlements description: settlements x-group: Settlements - name: ucp description: Universal Commerce Protocol x-group: UCP paths: /api/v1/campaigns/{campaignId}/actions: post: tags: - campaigns summary: Act on Campaign description: >- Approve, start, end, resume, retry, or decide a proposed live change. Approve, run, resume, and approving a change must be called by the named approver. Requires `promotions:write`. operationId: post_v1_campaigns_by_campaignid_actions parameters: - name: campaignId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: action: type: string enum: - approve - run - approve_and_run - end - resume - retry - approve_change - discard_change expectedRevision: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 expectedPendingVersion: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 organizationId: description: >- Required for session auth. Optional for an API key, which already identifies the organization. type: string minLength: 1 maxLength: 120 required: - action - expectedRevision additionalProperties: false responses: '200': description: Campaign detail after the action, plus the scheduling result. content: application/json: schema: type: object properties: campaign: type: object properties: id: type: string organizationId: type: string revision: type: integer minimum: -9007199254740991 maximum: 9007199254740991 stage: type: string enum: - draft - approved - running - ending - completed - archived approval: anyOf: - type: object properties: revision: type: integer minimum: -9007199254740991 maximum: 9007199254740991 userId: type: string approvedAt: type: string required: - revision - userId - approvedAt - type: 'null' runId: anyOf: - type: string - type: 'null' startedAt: anyOf: - type: string - type: 'null' endedAt: anyOf: - type: string - type: 'null' createdAt: type: string updatedAt: type: string plan: $ref: '#/components/schemas/CampaignPlan' pendingChange: anyOf: - type: object properties: version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 plan: $ref: '#/components/schemas/CampaignPlan' proposedBy: type: string proposedAt: type: string required: - version - plan - proposedBy - proposedAt - type: 'null' description: >- A running campaign's proposed plan, applied only when the approver approves it. required: - id - organizationId - revision - stage - approval - runId - startedAt - endedAt - createdAt - updatedAt - plan - pendingChange executions: type: array items: type: object properties: offerId: type: string windowId: type: string promotionId: anyOf: - type: string - type: 'null' state: type: string enum: - draft - activating - prepared - active - ending - ended - failed error: anyOf: - type: string - type: 'null' evidence: {} termsRevision: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' required: - offerId - windowId - promotionId - state - error - evidence - termsRevision audit: type: array items: type: object properties: id: type: string action: type: string actorId: anyOf: - type: string - type: 'null' actorName: anyOf: - type: string - type: 'null' createdAt: type: string details: type: object propertyNames: type: string additionalProperties: {} summary: type: string items: type: array items: type: object properties: kind: type: string enum: - brief - window - offer action: type: string enum: - add - update - remove id: type: string name: type: string changes: type: array items: type: object properties: field: type: string label: type: string from: anyOf: - type: string - type: 'null' to: anyOf: - type: string - type: 'null' required: - field - label - from - to required: - kind - action - id - name - changes hiddenCount: type: integer minimum: 0 maximum: 9007199254740991 required: - id - action - actorId - actorName - createdAt - details readiness: type: array items: type: string description: Issues that block approving or running the current plan. pendingChangeIssues: type: array items: type: string description: Issues that block approving the proposed live change. pendingScheduleCount: type: integer minimum: 0 maximum: 9007199254740991 failedScheduleCount: type: integer minimum: 0 maximum: 9007199254740991 waitingBrowserJobCount: type: integer minimum: 0 maximum: 9007199254740991 scheduleIssues: type: array items: type: object properties: windowId: type: string phase: type: string enum: - prepare - live kind: type: string enum: - overdue - missed required: - windowId - phase - kind recovery: type: array items: type: object properties: windowId: type: string phase: type: string enum: - prepare - live - start - end - revise state: type: string attempt: type: integer minimum: -9007199254740991 maximum: 9007199254740991 nextRetryAt: type: string error: anyOf: - type: string - type: 'null' required: - windowId - phase - state - attempt - nextRetryAt - error cleanupFailed: type: boolean progress: type: object properties: asOf: type: string title: type: string description: type: string total: type: integer minimum: 0 maximum: 9007199254740991 counts: type: object properties: waiting: type: integer minimum: 0 maximum: 9007199254740991 preparing: type: integer minimum: 0 maximum: 9007199254740991 prepared: type: integer minimum: 0 maximum: 9007199254740991 live: type: integer minimum: 0 maximum: 9007199254740991 ending: type: integer minimum: 0 maximum: 9007199254740991 ended: type: integer minimum: 0 maximum: 9007199254740991 cancelled: type: integer minimum: 0 maximum: 9007199254740991 failed: type: integer minimum: 0 maximum: 9007199254740991 required: - waiting - preparing - prepared - live - ending - ended - cancelled - failed issues: type: array items: type: object properties: offerId: type: string name: type: string error: type: string required: - offerId - name - error scheduleIssues: type: array items: type: object properties: windowId: type: string phase: type: string enum: - prepare - live kind: type: string enum: - overdue - missed name: type: string message: type: string required: - windowId - phase - kind - name - message blockers: type: array items: type: string nextWindow: anyOf: - type: object properties: id: type: string name: type: string preparesAt: anyOf: - type: string - type: 'null' startsAt: anyOf: - type: string - type: 'null' endsAt: anyOf: - type: string - type: 'null' required: - id - name - preparesAt - startsAt - endsAt - type: 'null' required: - asOf - title - description - total - counts - issues - scheduleIssues - blockers - nextWindow scheduling: type: object properties: queued: type: integer minimum: 0 maximum: 9007199254740991 pending: type: boolean required: - queued - pending description: >- `pending` is true when the schedule was saved but not yet acknowledged; retry the action to confirm. required: - campaign - executions - audit - readiness - pendingChangeIssues - pendingScheduleCount - failedScheduleCount - waitingBrowserJobCount - scheduling '400': description: Invalid campaign payload or plan state. '401': description: Unauthorized '403': description: >- Forbidden: missing `promotions:write` scope, or a session member without organization-wide access '404': description: Campaign not found for this organization '429': description: Rate limit exceeded '500': description: Internal Server Error security: - bearerAuth: [] components: schemas: CampaignPlan: type: object properties: brief: type: object properties: name: type: string minLength: 2 maxLength: 160 objective: default: '' type: string maxLength: 8000 brand: default: '' type: string maxLength: 160 ownerId: type: string minLength: 1 maxLength: 160 approverId: type: string minLength: 1 maxLength: 160 timezone: type: string stores: default: [] maxItems: 100 type: array items: type: object properties: marketplace: type: string enum: - shopee - lazada - tiktok - shopify - whatsapp - zalora - amazon - ebay country: type: string minLength: 1 maxLength: 80 storeId: type: string minLength: 1 maxLength: 160 required: - marketplace - country - storeId additionalProperties: false serviceRequest: default: '' type: string maxLength: 300 priority: default: standard type: string enum: - standard - priority - super_priority documentIds: default: [] maxItems: 100 type: array items: type: string minLength: 1 maxLength: 160 reviewDueAt: default: null 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' sourceCurrency: type: string pattern: ^[A-Z]{3}$ sourceMarketplace: type: string enum: - shopee - lazada - tiktok - shopify - whatsapp - zalora - amazon - ebay sourceCountry: type: string maxLength: 80 cleanupNotes: default: '' type: string maxLength: 8000 required: - name - ownerId - approverId - timezone additionalProperties: false windows: default: [] maxItems: 100 type: array items: type: object properties: id: type: string minLength: 1 maxLength: 160 name: type: string minLength: 1 maxLength: 160 preparesAt: default: null description: >- Preparation time: publish promotions with the future live start/end. Must be at or before 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' 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' 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' reviewNotes: default: '' type: string maxLength: 8000 required: - id - name - startsAt - endsAt additionalProperties: false offers: maxItems: 500 type: array items: type: object properties: id: type: string minLength: 1 maxLength: 160 windowId: type: string minLength: 1 maxLength: 160 promotionId: description: >- Existing draft promotion attached to this window; the campaign controls its live dates. 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)$ 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 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_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' 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: default: [] 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)$ reviewNotes: default: '' type: string maxLength: 8000 excludedReason: default: '' type: string maxLength: 2000 source: type: object properties: sheet: type: string maxLength: 160 rows: maxItems: 10000 type: array items: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 headers: maxItems: 100 type: array items: type: string maxLength: 300 values: maxItems: 10000 type: array items: maxItems: 100 type: array items: type: string maxLength: 16000 required: - sheet - rows - headers - values additionalProperties: false required: - id - windowId - promotion additionalProperties: false required: - brief additionalProperties: false 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.