---
title: "Create a promotion"
method: POST
path: "/open-api/v1.0/promotions"
tags: ["Promotions"]
---

# Create a promotion

`POST /open-api/v1.0/promotions`

*Rate limit: 100 requests / 10 seconds per shop. See [Rate limiting](/guides/rate-limiting).*

Creates a promotion

## Request body

- union
  - MEMBERSHIPSMULTI
    - `type` 'MEMBERSHIPS_MULTI', required
    - `codes` string[], required
    - `discount` ComFourthwallAppOpenapiEndpointModelRequestsPromotionsOpenApiPromotionDiscountTypeMembershipsPercentage, required
      - `type` 'PERCENTAGE', required
      - `percentage` number, required
    - `requirements` ComFourthwallAppOpenapiEndpointModelRequestsPromotionsOpenApiPromotionRequirementsMemberships
      - `newMembersOnly` boolean, required
    - `subscriptionType` union
      - ComFourthwallAppOpenapiEndpointModelRequestsPromotionsOpenApiPromotionMembershipSubscriptionTypeAppliesToAllMembers
        - `type` 'ALL', required
      - ComFourthwallAppOpenapiEndpointModelRequestsPromotionsOpenApiPromotionMembershipSubscriptionTypeAppliesToAnnualMembersOnly
        - `type` 'ANNUAL', required
      - ComFourthwallAppOpenapiEndpointModelRequestsPromotionsOpenApiPromotionMembershipSubscriptionTypeAppliesToMonthlyMembersOnly
        - `type` 'MONTHLY', required
    - `tiers` union
      - ComFourthwallAppOpenapiEndpointModelRequestsPromotionsOpenApiPromotionMembershipTiersAppliesToAllTiers
        - `type` 'ALL', required
      - ComFourthwallAppOpenapiEndpointModelRequestsPromotionsOpenApiPromotionMembershipTiersAppliesToSelectedTiers
        - `type` 'SELECTED', required
        - `ids` string[], required
  - MEMBERSHIPSSINGLE
    - `type` 'MEMBERSHIPS_SINGLE', required
    - `code` string, required
    - `discount` ComFourthwallAppOpenapiEndpointModelRequestsPromotionsOpenApiPromotionDiscountTypeMembershipsPercentage, required
      - `type` 'PERCENTAGE', required
      - `percentage` number, required
    - `requirements` ComFourthwallAppOpenapiEndpointModelRequestsPromotionsOpenApiPromotionRequirementsMemberships
      - `newMembersOnly` boolean, required
    - `subscriptionType` union
      - ComFourthwallAppOpenapiEndpointModelRequestsPromotionsOpenApiPromotionMembershipSubscriptionTypeAppliesToAllMembers
        - `type` 'ALL', required
      - ComFourthwallAppOpenapiEndpointModelRequestsPromotionsOpenApiPromotionMembershipSubscriptionTypeAppliesToAnnualMembersOnly
        - `type` 'ANNUAL', required
      - ComFourthwallAppOpenapiEndpointModelRequestsPromotionsOpenApiPromotionMembershipSubscriptionTypeAppliesToMonthlyMembersOnly
        - `type` 'MONTHLY', required
    - `tiers` union
      - ComFourthwallAppOpenapiEndpointModelRequestsPromotionsOpenApiPromotionMembershipTiersAppliesToAllTiers
        - `type` 'ALL', required
      - ComFourthwallAppOpenapiEndpointModelRequestsPromotionsOpenApiPromotionMembershipTiersAppliesToSelectedTiers
        - `type` 'SELECTED', required
        - `ids` string[], required
  - SHOPMULTI
    - `type` 'SHOP_MULTI', required
    - `codes` string[], required
    - `discount` union, required
      - ComFourthwallAppOpenapiEndpointModelRequestsPromotionsOpenApiPromotionDiscountTypeShopFixedAmount
        - `type` 'FLAT_RATE', required
        - `money` Money, required
          - `value` number, required
          - `currency` string, required
        - `freeShipping` boolean, required
      - ComFourthwallAppOpenapiEndpointModelRequestsPromotionsOpenApiPromotionDiscountTypeShopFreeShipping
        - `type` 'FREE_SHIPPING', required
      - ComFourthwallAppOpenapiEndpointModelRequestsPromotionsOpenApiPromotionDiscountTypeShopPercentage
        - `type` 'PERCENTAGE', required
        - `percentage` number, required
        - `shipping` 'Excluded' | 'Included' | 'FreeLowestOnly' | 'Free', required
    - `requirements` ComFourthwallAppOpenapiEndpointModelRequestsPromotionsOpenApiPromotionRequirementsShop
      - `minimumOrderValue` Money
        - `value` number, required
        - `currency` string, required
    - `appliesToProducts` ComFourthwallAppOpenapiEndpointModelRequestsPromotionsOpenApiPromotionSelectedProducts
      - `productIds` string[], required
      - `oncePerOrder` boolean
    - `limits` ComFourthwallAppOpenapiEndpointModelRequestsPromotionsOpenApiPromotionLimits
      - `maximumUse` integer
      - `oneUsePerCustomer` boolean, required
  - SHOPSINGLE
    - `type` 'SHOP_SINGLE', required
    - `code` string, required
    - `discount` union, required
      - ComFourthwallAppOpenapiEndpointModelRequestsPromotionsOpenApiPromotionDiscountTypeShopFixedAmount
        - `type` 'FLAT_RATE', required
        - `money` Money, required
          - `value` number, required
          - `currency` string, required
        - `freeShipping` boolean, required
      - ComFourthwallAppOpenapiEndpointModelRequestsPromotionsOpenApiPromotionDiscountTypeShopFreeShipping
        - `type` 'FREE_SHIPPING', required
      - ComFourthwallAppOpenapiEndpointModelRequestsPromotionsOpenApiPromotionDiscountTypeShopPercentage
        - `type` 'PERCENTAGE', required
        - `percentage` number, required
        - `shipping` 'Excluded' | 'Included' | 'FreeLowestOnly' | 'Free', required
    - `requirements` ComFourthwallAppOpenapiEndpointModelRequestsPromotionsOpenApiPromotionRequirementsShop
      - `minimumOrderValue` Money
        - `value` number, required
        - `currency` string, required
    - `appliesToProducts` ComFourthwallAppOpenapiEndpointModelRequestsPromotionsOpenApiPromotionSelectedProducts
      - `productIds` string[], required
      - `oncePerOrder` boolean
    - `limits` ComFourthwallAppOpenapiEndpointModelRequestsPromotionsOpenApiPromotionLimits
      - `maximumUse` integer
      - `oneUsePerCustomer` boolean, required

## Response `200`

OK

- union
  - ComFourthwallOpenapiModelPromotionsAutoApplyingShopPromotionV1
    - `type` 'SHOP_AUTO_APPLYING', required
    - `id` string, required
    - `title` string, required
    - `code` string, required
    - `discount` union, required
      - ComFourthwallOpenapiModelPromotionsPromotionShopDiscountTypeV1FixedAmount
        - `type` 'FLAT_RATE', required
        - `money` Money, required
          - `value` number, required
          - `currency` string, required
        - `freeShipping` boolean, required
      - ComFourthwallOpenapiModelPromotionsPromotionShopDiscountTypeV1FreeProducts
        - `type` 'FREE_PRODUCTS', required
        - `freeProductsType` union, required
          - ComFourthwallOpenapiModelPromotionsPromotionShopDiscountTypeV1FreeProductsTypeAutoAdded
            - `type` 'AUTO_ADDED', required
            - `products` ComFourthwallOpenapiModelPromotionsPromotionShopDiscountTypeV1FreeProductsAutoAddedFreeProduct[], required
              - …
          - ComFourthwallOpenapiModelPromotionsPromotionShopDiscountTypeV1FreeProductsTypeManuallyAdded
            - `type` 'MANUALLY_ADDED', required
            - `products` ComFourthwallOpenapiModelPromotionsPromotionShopDiscountTypeV1FreeProductsManuallyAddedFreeProduct[], required
              - …
        - `freeShipping` boolean, required
      - ComFourthwallOpenapiModelPromotionsPromotionShopDiscountTypeV1FreeShipping
        - `type` 'FREE_SHIPPING', required
        - `lowestOnly` boolean, required
      - ComFourthwallOpenapiModelPromotionsPromotionShopDiscountTypeV1Percentage
        - `type` 'PERCENTAGE', required
        - `percentage` number, required
        - `shippingOption` 'Included' | 'Excluded' | 'Free' | 'FreeLowestOnly'
    - `status` 'Live' | 'Ended' | 'Archived' | 'AllUsed', required
    - `requirements` ComFourthwallOpenapiModelPromotionsPromotionRequirementsV1Shop, required
      - `minimumOrderValue` Money
        - `value` number, required
        - `currency` string, required
    - `usageCount` integer, required
    - `limits` ComFourthwallOpenapiModelPromotionsPromotionLimitsV1, required
      - `maximumUsesNumber` integer
      - `oneUsePerCustomer` boolean
    - `appliesTo` union, required
      - ComFourthwallOpenapiModelPromotionsPromotionShopAppliesToV1EntireOrder
        - `type` 'ENTIRE_ORDER', required
      - ComFourthwallOpenapiModelPromotionsPromotionShopAppliesToV1EntireOrderWithExcludedProducts
        - `type` 'ENTIRE_ORDER_WITH_EXCLUDED_PRODUCTS', required
        - `excludedProducts` string[], required
      - ComFourthwallOpenapiModelPromotionsPromotionShopAppliesToV1SelectedProducts
        - `type` 'SELECTED_PRODUCTS', required
        - `products` string[], required
        - `oncePerOrder` boolean, required
  - ComFourthwallOpenapiModelPromotionsMultiMembershipsPromotionV1
    - `type` 'MEMBERSHIPS_MULTI', required
    - `id` string, required
    - `title` string, required
    - `codes` ComFourthwallOpenapiModelPromotionsMultiPromoSubCodeV1[], required
      - `id` string, required
      - `code` string, required
      - `usageCount` integer, required
      - `status` 'Live' | 'Ended' | 'Archived' | 'AllUsed', required
    - `discount` ComFourthwallOpenapiModelPromotionsPromotionMembershipsDiscountTypeV1Percentage, required
      - `type` 'MEMBERSHIPS_PERCENTAGE', required
      - `percentage` number, required
    - `status` 'Live' | 'Ended' | 'Archived' | 'AllUsed', required
    - `requirements` ComFourthwallOpenapiModelPromotionsPromotionRequirementsV1Memberships, required
      - `newMembersOnly` boolean, required
    - `usageCount` integer, required
    - `subscriptionType` union, required
      - ComFourthwallOpenapiModelPromotionsPromotionMembershipsSubscriptionTypeAppliesToV1AllMembers
        - `type` 'ALL', required
      - ComFourthwallOpenapiModelPromotionsPromotionMembershipsSubscriptionTypeAppliesToV1AnnualMembersOnly
        - `type` 'ANNUAL', required
      - ComFourthwallOpenapiModelPromotionsPromotionMembershipsSubscriptionTypeAppliesToV1MonthlyMembersOnly
        - `type` 'MONTHLY', required
    - `tiers` union, required
      - ComFourthwallOpenapiModelPromotionsPromotionMembershipsTiersAppliesToV1AllTiers
        - `type` 'ALL', required
      - ComFourthwallOpenapiModelPromotionsPromotionMembershipsTiersAppliesToV1SelectedTiers
        - `type` 'SELECTED', required
        - `tiersIds` string[], required
  - ComFourthwallOpenapiModelPromotionsMultiShopPromotionV1
    - `type` 'SHOP_MULTI', required
    - `id` string, required
    - `title` string, required
    - `codes` ComFourthwallOpenapiModelPromotionsMultiPromoSubCodeV1[], required
      - `id` string, required
      - `code` string, required
      - `usageCount` integer, required
      - `status` 'Live' | 'Ended' | 'Archived' | 'AllUsed', required
    - `discount` union, required
      - ComFourthwallOpenapiModelPromotionsPromotionShopDiscountTypeV1FixedAmount
        - `type` 'FLAT_RATE', required
        - `money` Money, required
          - `value` number, required
          - `currency` string, required
        - `freeShipping` boolean, required
      - ComFourthwallOpenapiModelPromotionsPromotionShopDiscountTypeV1FreeProducts
        - `type` 'FREE_PRODUCTS', required
        - `freeProductsType` union, required
          - ComFourthwallOpenapiModelPromotionsPromotionShopDiscountTypeV1FreeProductsTypeAutoAdded
            - `type` 'AUTO_ADDED', required
            - `products` ComFourthwallOpenapiModelPromotionsPromotionShopDiscountTypeV1FreeProductsAutoAddedFreeProduct[], required
              - …
          - ComFourthwallOpenapiModelPromotionsPromotionShopDiscountTypeV1FreeProductsTypeManuallyAdded
            - `type` 'MANUALLY_ADDED', required
            - `products` ComFourthwallOpenapiModelPromotionsPromotionShopDiscountTypeV1FreeProductsManuallyAddedFreeProduct[], required
              - …
        - `freeShipping` boolean, required
      - ComFourthwallOpenapiModelPromotionsPromotionShopDiscountTypeV1FreeShipping
        - `type` 'FREE_SHIPPING', required
        - `lowestOnly` boolean, required
      - ComFourthwallOpenapiModelPromotionsPromotionShopDiscountTypeV1Percentage
        - `type` 'PERCENTAGE', required
        - `percentage` number, required
        - `shippingOption` 'Included' | 'Excluded' | 'Free' | 'FreeLowestOnly'
    - `status` 'Live' | 'Ended' | 'Archived' | 'AllUsed', required
    - `requirements` ComFourthwallOpenapiModelPromotionsPromotionRequirementsV1Shop, required
      - `minimumOrderValue` Money
        - `value` number, required
        - `currency` string, required
    - `limits` ComFourthwallOpenapiModelPromotionsPromotionLimitsV1, required
      - `maximumUsesNumber` integer
      - `oneUsePerCustomer` boolean
    - `usageCount` integer, required
    - `appliesTo` union, required
      - ComFourthwallOpenapiModelPromotionsPromotionShopAppliesToV1EntireOrder
        - `type` 'ENTIRE_ORDER', required
      - ComFourthwallOpenapiModelPromotionsPromotionShopAppliesToV1EntireOrderWithExcludedProducts
        - `type` 'ENTIRE_ORDER_WITH_EXCLUDED_PRODUCTS', required
        - `excludedProducts` string[], required
      - ComFourthwallOpenapiModelPromotionsPromotionShopAppliesToV1SelectedProducts
        - `type` 'SELECTED_PRODUCTS', required
        - `products` string[], required
        - `oncePerOrder` boolean, required
  - ComFourthwallOpenapiModelPromotionsSingleMembershipsPromotionV1
    - `type` 'MEMBERSHIPS_SINGLE', required
    - `id` string, required
    - `code` string, required
    - `discount` ComFourthwallOpenapiModelPromotionsPromotionMembershipsDiscountTypeV1Percentage, required
      - `type` 'MEMBERSHIPS_PERCENTAGE', required
      - `percentage` number, required
    - `status` 'Live' | 'Ended' | 'Archived' | 'AllUsed', required
    - `requirements` ComFourthwallOpenapiModelPromotionsPromotionRequirementsV1Memberships, required
      - `newMembersOnly` boolean, required
    - `usageCount` integer, required
    - `subscriptionType` union, required
      - ComFourthwallOpenapiModelPromotionsPromotionMembershipsSubscriptionTypeAppliesToV1AllMembers
        - `type` 'ALL', required
      - ComFourthwallOpenapiModelPromotionsPromotionMembershipsSubscriptionTypeAppliesToV1AnnualMembersOnly
        - `type` 'ANNUAL', required
      - ComFourthwallOpenapiModelPromotionsPromotionMembershipsSubscriptionTypeAppliesToV1MonthlyMembersOnly
        - `type` 'MONTHLY', required
    - `tiers` union, required
      - ComFourthwallOpenapiModelPromotionsPromotionMembershipsTiersAppliesToV1AllTiers
        - `type` 'ALL', required
      - ComFourthwallOpenapiModelPromotionsPromotionMembershipsTiersAppliesToV1SelectedTiers
        - `type` 'SELECTED', required
        - `tiersIds` string[], required
  - ComFourthwallOpenapiModelPromotionsSingleShopPromotionV1
    - `type` 'SHOP_SINGLE', required
    - `id` string, required
    - `code` string, required
    - `discount` union, required
      - ComFourthwallOpenapiModelPromotionsPromotionShopDiscountTypeV1FixedAmount
        - `type` 'FLAT_RATE', required
        - `money` Money, required
          - `value` number, required
          - `currency` string, required
        - `freeShipping` boolean, required
      - ComFourthwallOpenapiModelPromotionsPromotionShopDiscountTypeV1FreeProducts
        - `type` 'FREE_PRODUCTS', required
        - `freeProductsType` union, required
          - ComFourthwallOpenapiModelPromotionsPromotionShopDiscountTypeV1FreeProductsTypeAutoAdded
            - `type` 'AUTO_ADDED', required
            - `products` ComFourthwallOpenapiModelPromotionsPromotionShopDiscountTypeV1FreeProductsAutoAddedFreeProduct[], required
              - …
          - ComFourthwallOpenapiModelPromotionsPromotionShopDiscountTypeV1FreeProductsTypeManuallyAdded
            - `type` 'MANUALLY_ADDED', required
            - `products` ComFourthwallOpenapiModelPromotionsPromotionShopDiscountTypeV1FreeProductsManuallyAddedFreeProduct[], required
              - …
        - `freeShipping` boolean, required
      - ComFourthwallOpenapiModelPromotionsPromotionShopDiscountTypeV1FreeShipping
        - `type` 'FREE_SHIPPING', required
        - `lowestOnly` boolean, required
      - ComFourthwallOpenapiModelPromotionsPromotionShopDiscountTypeV1Percentage
        - `type` 'PERCENTAGE', required
        - `percentage` number, required
        - `shippingOption` 'Included' | 'Excluded' | 'Free' | 'FreeLowestOnly'
    - `status` 'Live' | 'Ended' | 'Archived' | 'AllUsed', required
    - `requirements` ComFourthwallOpenapiModelPromotionsPromotionRequirementsV1Shop, required
      - `minimumOrderValue` Money
        - `value` number, required
        - `currency` string, required
    - `usageCount` integer, required
    - `limits` ComFourthwallOpenapiModelPromotionsPromotionLimitsV1, required
      - `maximumUsesNumber` integer
      - `oneUsePerCustomer` boolean
    - `appliesTo` union, required
      - ComFourthwallOpenapiModelPromotionsPromotionShopAppliesToV1EntireOrder
        - `type` 'ENTIRE_ORDER', required
      - ComFourthwallOpenapiModelPromotionsPromotionShopAppliesToV1EntireOrderWithExcludedProducts
        - `type` 'ENTIRE_ORDER_WITH_EXCLUDED_PRODUCTS', required
        - `excludedProducts` string[], required
      - ComFourthwallOpenapiModelPromotionsPromotionShopAppliesToV1SelectedProducts
        - `type` 'SELECTED_PRODUCTS', required
        - `products` string[], required
        - `oncePerOrder` boolean, required

## Other responses

- `400` — Possible errors: `PROMOTION_ONCE_PER_ORDER_CONFIGURATION_NOT_SUPPORTER_FOR_DISCOUNT_TYPE`, `PROMOTION_ONLY_ONE_TIERS_REQUIREMENT_TYPE_ALLOWED`
- `409` — Possible errors: `PROMOTION_CODE_DUPLICATION`, `PROMOTION_CODES_DUPLICATION`
- `429` — Rate limited: 100 requests / 10 seconds per shop.

---

[API](https://skmtc.net/fourthwall/apis/fourthwall-apis-2.md) · [All operations](https://skmtc.net/fourthwall/apis/fourthwall-apis-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fourthwall/fourthwall-apis-2/revisions/ef273312f051/schema)