> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tagada.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create promotion

> Create a new promotion with rules and actions for a specific store



## OpenAPI

````yaml /openapi.json post /api/public/v1/promotions/create
openapi: 3.0.3
info:
  title: TagadaPay API
  description: >-

    # TagadaPay API Documentation


    Welcome to the TagadaPay API. This REST API lets you process payments,
    manage subscriptions, handle customers, deploy plugins, and orchestrate
    checkout funnels — all programmatically.


    ## Authentication


    Authenticate every request with a Bearer token. Get your API key from the
    [TagadaPay Dashboard](https://app.tagada.io).


    ```

    Authorization: Bearer your-api-key

    ```


    All requests must be made over HTTPS with `Content-Type: application/json`.


    ## Rate Limits


    | Plan | Requests/min | Burst |

    |------|-------------|-------|

    | Standard | 100 | 150 |

    | Premium | 500 | 750 |


    Exceeding the limit returns `429 Too Many Requests`.


    ## Errors


    | Code | Meaning |

    |------|---------|

    | 400 | Bad request — invalid parameters |

    | 401 | Unauthorized — missing or invalid API key |

    | 403 | Forbidden — insufficient permissions |

    | 404 | Not found |

    | 409 | Conflict |

    | 429 | Rate limited |

    | 500 | Server error |


    ## Support


    - Email: api-support@tagada.io

    - Docs: [docs.tagadapay.com](https://docs.tagadapay.com)
        
  version: 1.0.0
servers:
  - url: https://api.tagada.io/
    description: Production
  - url: https://api.tagada.dev/
    description: Sandbox / Development
security:
  - bearerAuth: []
tags:
  - name: auth
    description: Test your API key and verify authentication.
  - name: stores
    description: Create and manage stores within your account.
  - name: products
    description: Create products with variants, prices, and currency options.
  - name: customers
    description: Manage customer records, addresses, and payment instruments.
  - name: orders
    description: List and retrieve orders with line items, payments, and metadata.
  - name: payments
    description: Process, list, refund, void, and dispute payments.
  - name: subscriptions
    description: >-
      Create and manage recurring subscriptions — billing, cancellation,
      rebilling, and processor changes.
  - name: payment-flows
    description: Configure payment routing strategies with cascading processor fallbacks.
  - name: payment-instruments
    description: >-
      Manage stored payment methods — cards, bank accounts, and tokenized
      instruments.
  - name: processors
    description: List connected payment processors (Stripe, NMI, Checkout.com, etc.).
  - name: promotions
    description: Create and manage discount promotions with rules and conditions.
  - name: promotion-codes
    description: Generate and manage reusable promotion/coupon codes.
  - name: block-rules
    description: >-
      Configure fraud prevention rules to block transactions by IP, email, card
      BIN, country, etc.
  - name: webhooks
    description: Register webhook endpoints to receive real-time event notifications.
  - name: events
    description: Query application events, statistics, and audit logs.
  - name: domains
    description: Add, verify, and manage custom domains for your checkout and funnels.
  - name: funnels
    description: >-
      Create and manage checkout funnels with routing, A/B testing, and CDN
      deployment.
  - name: funnel-sessions
    description: Retrieve funnel session data for analytics and debugging.
  - name: funnel-tracking
    description: Track funnel step events for conversion analytics.
  - name: plugins
    description: Deploy, manage, and configure checkout plugins.
  - name: plugins-v2
    description: >-
      V2 plugin system — deploy, mount, split-test, fork, promote, and manage
      plugin instances.
  - name: checkout
    description: >-
      Initialize checkout sessions and process payments through the hosted
      checkout.
  - name: 3ds
    description: >-
      3D Secure authentication — create sessions, authenticate, and handle
      challenges.
  - name: builder
    description: Generate and validate builder session tokens for the visual page editor.
  - name: health
    description: API health check endpoint.
  - name: test
    description: Test and debugging utilities for the event system (sandbox only).
paths:
  /api/public/v1/promotions/create:
    post:
      tags:
        - promotions
      summary: Create promotion
      description: Create a new promotion with rules and actions for a specific store
      operationId: post-api-public-v1-promotions-create
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                storeId:
                  type: string
                  minLength: 1
                name:
                  type: string
                  minLength: 1
                automatic:
                  type: boolean
                  default: false
                usageLimit:
                  type: integer
                  exclusiveMinimum: true
                  minimum: 0
                  nullable: true
                  default: null
                startDate:
                  type: string
                  format: date-time
                  nullable: true
                  default: null
                endDate:
                  type: string
                  format: date-time
                  nullable: true
                  default: null
                enabled:
                  type: boolean
                  default: true
                ruleOperator:
                  type: string
                  enum:
                    - AND
                    - OR
                  default: OR
                combinesWithOrderLevelDiscounts:
                  type: boolean
                  default: false
                combinesWithLineItemDiscounts:
                  type: boolean
                  default: false
                combinesWithShippingDiscounts:
                  type: boolean
                  default: false
                forceCombine:
                  type: boolean
                  default: false
                oncePerCustomer:
                  type: boolean
                  default: false
                rules:
                  type: array
                  items:
                    anyOf:
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - ContainsProduct
                          productId:
                            type: string
                            minLength: 1
                          minimumQuantity:
                            type: integer
                            exclusiveMinimum: true
                            minimum: 0
                            nullable: true
                            default: null
                          variantIds:
                            type: array
                            items:
                              type: string
                            nullable: true
                            default: null
                        required:
                          - type
                          - productId
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - OrderAmountMinimum
                          minimumAmount:
                            type: object
                            additionalProperties:
                              type: object
                              properties:
                                rate:
                                  type: number
                                amount:
                                  type: number
                                lock:
                                  type: boolean
                                date:
                                  type: string
                              required:
                                - amount
                              additionalProperties: false
                        required:
                          - type
                          - minimumAmount
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - OrderMinQuantity
                          orderMinQuantity:
                            type: integer
                            exclusiveMinimum: true
                            minimum: 0
                          excludedProductIds:
                            type: array
                            items:
                              type: string
                            nullable: true
                            default: null
                        required:
                          - type
                          - orderMinQuantity
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - OrderMaxQuantity
                          orderMaxQuantity:
                            type: integer
                            exclusiveMinimum: true
                            minimum: 0
                          excludedProductIds:
                            type: array
                            items:
                              type: string
                            nullable: true
                            default: null
                        required:
                          - type
                          - orderMaxQuantity
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - MaxProductQuantity
                          productId:
                            type: string
                            minLength: 1
                          maximumQuantity:
                            type: integer
                            exclusiveMinimum: true
                            minimum: 0
                          variantIds:
                            type: array
                            items:
                              type: string
                            nullable: true
                            default: null
                        required:
                          - type
                          - productId
                          - maximumQuantity
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - PaymentIntegrationSelected
                          paymentMethodName:
                            type: string
                            minLength: 1
                        required:
                          - type
                          - paymentMethodName
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - DoNotContainRecurringProduct
                        required:
                          - type
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - MaxAmount
                          maximumAmount:
                            type: object
                            additionalProperties:
                              type: object
                              properties:
                                rate:
                                  type: number
                                amount:
                                  type: number
                                lock:
                                  type: boolean
                                date:
                                  type: string
                              required:
                                - amount
                              additionalProperties: false
                        required:
                          - type
                          - maximumAmount
                        additionalProperties: false
                  default: []
                actions:
                  type: array
                  items:
                    anyOf:
                      - type: object
                        properties:
                          targetProductId:
                            type: string
                            nullable: true
                            default: null
                          targetVariantIds:
                            type: array
                            items:
                              type: string
                            nullable: true
                            default: null
                          maxQuantityDiscounted:
                            type: number
                            nullable: true
                            default: null
                          appliesOnEachItem:
                            type: boolean
                            default: false
                          type:
                            type: string
                            enum:
                              - LineItemAdjustment
                          adjustmentType:
                            type: string
                            enum:
                              - percentage
                          adjustmentPercentage:
                            type: number
                        required:
                          - type
                          - adjustmentType
                          - adjustmentPercentage
                        additionalProperties: false
                      - type: object
                        properties:
                          targetProductId:
                            type: string
                            nullable: true
                            default: null
                          targetVariantIds:
                            type: array
                            items:
                              type: string
                            nullable: true
                            default: null
                          maxQuantityDiscounted:
                            type: number
                            nullable: true
                            default: null
                          appliesOnEachItem:
                            type: boolean
                            default: false
                          type:
                            type: string
                            enum:
                              - LineItemAdjustment
                          adjustmentType:
                            type: string
                            enum:
                              - amount
                          adjustmentAmount:
                            type: object
                            additionalProperties:
                              type: object
                              properties:
                                rate:
                                  type: number
                                amount:
                                  type: number
                                lock:
                                  type: boolean
                                date:
                                  type: string
                              required:
                                - amount
                              additionalProperties: false
                        required:
                          - type
                          - adjustmentType
                          - adjustmentAmount
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - OrderAdjustment
                          adjustmentType:
                            type: string
                            enum:
                              - percentage
                          adjustmentPercentage:
                            type: number
                        required:
                          - type
                          - adjustmentType
                          - adjustmentPercentage
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - OrderAdjustment
                          adjustmentType:
                            type: string
                            enum:
                              - amount
                          adjustmentAmount:
                            type: object
                            additionalProperties:
                              type: object
                              properties:
                                rate:
                                  type: number
                                amount:
                                  type: number
                                lock:
                                  type: boolean
                                date:
                                  type: string
                              required:
                                - amount
                              additionalProperties: false
                        required:
                          - type
                          - adjustmentType
                          - adjustmentAmount
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - ShippingAdjustment
                          freeShipping:
                            type: boolean
                            default: true
                        required:
                          - type
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - CreateLineItem
                          priceIdToAdd:
                            type: string
                            minLength: 1
                          quantityToAdd:
                            type: integer
                            exclusiveMinimum: true
                            minimum: 0
                            nullable: true
                            default: null
                        required:
                          - type
                          - priceIdToAdd
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - SubscriptionLineItemFreeTrial
                          subscriptionFreeTrialDuration:
                            type: integer
                            exclusiveMinimum: true
                            minimum: 0
                          subscriptionFreeTrialDurationType:
                            type: string
                            enum:
                              - day
                              - week
                              - month
                              - year
                        required:
                          - type
                          - subscriptionFreeTrialDuration
                          - subscriptionFreeTrialDurationType
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - BOGO
                          targetProductId:
                            type: string
                            minLength: 1
                          targetVariantIds:
                            type: array
                            items:
                              type: string
                            nullable: true
                            default: null
                          buyQuantityThreshold:
                            type: integer
                            exclusiveMinimum: true
                            minimum: 0
                          productIdToAdd:
                            type: string
                            minLength: 1
                          variantIdToAdd:
                            type: string
                            minLength: 1
                          quantityToAdd:
                            type: integer
                            exclusiveMinimum: true
                            minimum: 0
                        required:
                          - type
                          - targetProductId
                          - buyQuantityThreshold
                          - productIdToAdd
                          - variantIdToAdd
                          - quantityToAdd
                        additionalProperties: false
                  default: []
                promotionCodes:
                  type: array
                  description: >-
                    Optional. Redeemable codes to create atomically alongside
                    the promotion. Each entry mirrors the `POST
                    /promotion-codes/create` body (without `promotionId`, which
                    is inferred). Uniqueness is enforced per store and per
                    batch; a failure on any code rolls back the whole promotion.
                  items:
                    type: object
                    properties:
                      code:
                        type: string
                        minLength: 1
                      customerId:
                        type: string
                      usageLimit:
                        type: integer
                        exclusiveMinimum: true
                        minimum: 0
                      expiresAt:
                        type: string
                        format: date-time
                      firstTimeCustomersOnly:
                        type: boolean
                        default: false
                      emailPattern:
                        type: string
                      description:
                        type: string
                      metadata:
                        type: string
                    required:
                      - code
                    additionalProperties: false
              required:
                - storeId
                - name
              additionalProperties: false
            examples:
              basic:
                summary: Create a coupon-code promotion with a single code
                value:
                  storeId: store_123
                  name: Summer Sale 20% Off
                  automatic: false
                  enabled: true
                  usageLimit: 100
                  startDate: '2025-06-01T00:00:00.000Z'
                  endDate: '2025-08-31T23:59:59.000Z'
                  ruleOperator: AND
                  combinesWithOrderLevelDiscounts: false
                  combinesWithLineItemDiscounts: false
                  combinesWithShippingDiscounts: false
                  forceCombine: false
                  rules: []
                  actions:
                    - type: OrderAdjustment
                      adjustmentType: percentage
                      adjustmentPercentage: 20
                  promotionCodes:
                    - code: SUMMER20
                      usageLimit: 100
                      firstTimeCustomersOnly: false
              multipleCodes:
                summary: Create a promotion with multiple codes at once
                value:
                  storeId: store_123
                  name: Summer Sale 20% Off
                  automatic: false
                  enabled: true
                  ruleOperator: AND
                  rules: []
                  actions:
                    - type: OrderAdjustment
                      adjustmentType: percentage
                      adjustmentPercentage: 20
                  promotionCodes:
                    - code: SUMMER20
                      usageLimit: 100
                      firstTimeCustomersOnly: false
                    - code: SUMMER20-VIP
                      firstTimeCustomersOnly: true
                      description: VIP customers only
              automatic:
                summary: Automatic promotion (no codes)
                value:
                  storeId: store_123
                  name: Auto 10% off orders over $50
                  automatic: true
                  enabled: true
                  ruleOperator: AND
                  rules:
                    - type: OrderAmountMinimum
                      minimumAmount:
                        USD:
                          amount: 5000
                  actions:
                    - type: OrderAdjustment
                      adjustmentType: percentage
                      adjustmentPercentage: 10
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: {}
              examples:
                success:
                  summary: Successful creation
                  value:
                    id: promo_123
                    name: Summer Sale 20% Off
                    enabled: true
        default:
          $ref: '#/components/responses/error'
      security:
        - bearerAuth: []
components:
  responses:
    error:
      description: Error response
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
              code:
                type: string
              issues:
                type: array
                items:
                  type: object
                  properties:
                    message:
                      type: string
                  required:
                    - message
                  additionalProperties: false
            required:
              - message
              - code
            additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Enter your API key as: `Bearer your-api-key`'

````