Create a promotion

At least one phase is required. Phase array order becomes the stored one-based position.

Authorization

AuthorizationBearer <token>

Provide your SellApp API key as a bearer token.

In: header

Header Parameters

X-STORE?string

Store slug. Required for OAuth access tokens. API keys may omit it to use their current store, or the first accessible store when no current store is selected.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Lengthlength <= 255

status*string

Value in"active" | "disabled"

starts_at?|

Formatdate-time

ends_at?|

A date and time after starts_at and after the current time, or null for no end date.

Formatdate-time

priority*integer

Range0 <= value <= 2147483647

is_stackable*boolean

max_redemptions?|

Range1 <= value <= 4294967295

applies_to?string

What the promotion discounts: one_time for one-time purchases, or subscriptions for the first payments of a subscription plan. A new promotion defaults to one_time, and an update that leaves this out keeps the current kind. The promotion only discounts order lines of its kind.

Value in"one_time" | "subscriptions"

subscription_payments?|

How many payments a subscriptions promotion discounts, counting the signup payment as the first, so 3 discounts the signup and the next two renewals. A subscriptions promotion needs one, and an update that leaves it out keeps the stored number. Missing on a subscriptions promotion, or outside 1 to 36, it returns 422 on subscription_payments with The number of discounted payments must be between 1 and 36. A one_time promotion always stores null here.

Range1 <= value <= 36

store_wide?boolean

Send false with products to limit a subscriptions promotion to picked products and plans. Required whenever the request sends products or product_variants. A new promotion defaults to true, an update that leaves it out keeps the current scope, and switching a promotion to one_time makes it store-wide again. A one_time promotion with false returns 422 on store_wide with A promotion for one-time purchases applies to the whole store.

products?array<integer>

Product IDs a narrowed subscription promotion reaches. Each one must sell a subscription, or the request returns 422 on products with Pick only products that sell a subscription. A narrowed promotion left with no products returns 422 with Pick at least one subscription product for this promotion. An update replaces the picks with this list, or keeps them when it is left out.

product_variants?array<integer>

Subscription plan IDs to limit the picked products to. Each one must be a subscription plan of a product in products, or the request returns 422 on product_variants with Pick only subscription plans of the picked products. A picked product with none of its plans listed takes every plan, including plans added later. An update that leaves this out keeps the listed plans of products that stay picked.

phases*array<>

The complete ordered phase set. Array order becomes phase position.

Items1 <= items

Response Body

`application/json`

Request and response example

curl -X POST "https://sell.app/api/v2/promotions" \  -H "X-STORE: launch-lab" \  -H "Content-Type: application/json" \  -d '{    "name": "Ship Week",    "status": "active",    "starts_at": "2026-08-01T00:00:00Z",    "ends_at": "2026-08-08T00:00:00Z",    "priority": 1,    "is_stackable": false,    "max_redemptions": 500,    "phases": [      {        "discount_type": "percentage",        "discount_value": "20",        "ends_at": "2026-08-04T00:00:00Z",        "max_redemptions": 200,        "minimum_amount": "10"      },      {        "discount_type": "fixed",        "discount_value": "5",        "ends_at": null,        "max_redemptions": null,        "minimum_amount": "25"      }    ]  }'

default

{
  "data": {
    "applies_to": "one_time",
    "subscription_payments": null,
    "store_wide": true,
    "products": [],
    "product_variants": [],
    "name": "Ship Week",
    "status": "active",
    "starts_at": "2026-08-01T00:00:00Z",
    "ends_at": "2026-08-08T00:00:00Z",
    "priority": 1,
    "is_stackable": false,
    "max_redemptions": 500,
    "phases": [
      {
        "discount_type": "percentage",
        "discount_value": "20",
        "ends_at": "2026-08-04T00:00:00Z",
        "max_redemptions": 200,
        "minimum_amount": "10",
        "id": 101,
        "promotion_id": 1,
        "sort_order": 1
      },
      {
        "discount_type": "fixed",
        "discount_value": "5",
        "ends_at": null,
        "max_redemptions": null,
        "minimum_amount": "25",
        "id": 102,
        "promotion_id": 1,
        "sort_order": 2
      }
    ],
    "id": 1,
    "created_at": "2026-08-30T12:00:01.000000Z",
    "updated_at": "2026-08-30T12:00:01.000000Z",
    "deleted_at": null
  }
}

subscriptionPlans

{
  "data": {
    "applies_to": "subscriptions",
    "subscription_payments": 3,
    "store_wide": false,
    "products": [
      120
    ],
    "product_variants": [],
    "name": "Founding members",
    "status": "active",
    "starts_at": null,
    "ends_at": null,
    "priority": 0,
    "is_stackable": false,
    "max_redemptions": null,
    "phases": [
      {
        "discount_type": "percentage",
        "discount_value": "25",
        "ends_at": null,
        "max_redemptions": null,
        "minimum_amount": null,
        "id": 103,
        "promotion_id": 2,
        "sort_order": 1
      }
    ],
    "id": 2,
    "created_at": "2026-08-30T12:00:01.000000Z",
    "updated_at": "2026-08-30T12:00:01.000000Z",
    "deleted_at": null
  }
}

{
  "type": "invalid_request_error",
  "code": "bad_request",
  "message": "The request could not be understood.",
  "status": 400,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#bad-request"
}

{
  "type": "authentication_error",
  "code": "unauthenticated",
  "message": "Unauthenticated.",
  "status": 401,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#unauthenticated"
}

{
  "type": "authorization_error",
  "code": "forbidden",
  "message": "This action is unauthorized.",
  "status": 403,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#forbidden"
}

{
  "type": "validation_error",
  "code": "validation_failed",
  "message": "The selected product variant id is invalid.",
  "status": 422,
  "param": "product_variant_id",
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#validation-failed",
  "errors": {
    "product_variant_id": [
      "The selected product variant id is invalid."
    ]
  }
}

{
  "type": "rate_limit_error",
  "code": "rate_limit_exceeded",
  "message": "Too Many Attempts.",
  "status": 429,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#rate-limit-exceeded"
}

{
  "type": "api_error",
  "code": "api_error",
  "message": "Server Error",
  "status": 500,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#api-error"
}

Discount a subscription's first payments

Set applies_to to subscriptions and subscription_payments to how many payments the promotion discounts. This promotion takes 25% off the first three payments of every plan of product 120:

{
  "name": "Founding members",
  "status": "active",
  "priority": 0,
  "is_stackable": false,
  "applies_to": "subscriptions",
  "subscription_payments": 3,
  "store_wide": false,
  "products": [120],
  "product_variants": [],
  "phases": [{ "discount_type": "percentage", "discount_value": "25" }]
}

To limit it to some plans, list their IDs in product_variants; each one must be a subscription plan of a product in products. Leave out store_wide, products, and product_variants to discount every plan in the store. Which promotion a cart takes explains how it competes with other promotions and coupons.

Create a promotion

Authorization

Header Parameters

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

422application/json

429application/json

500application/json

Discount a subscription's first payments

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`