Update a promotion

Send only the fields you want to change. Omit phases to keep the current phases. If phases is present, it replaces every active phase and array order becomes phase position.

Leaving out applies_to, subscription_payments, or the scope fields keeps their current values. Sending products replaces the picked products, and store_wide must come with it. Switching a promotion to one_time makes it store-wide again and clears subscription_payments.

Authorization

AuthorizationBearer <token>

Provide your SellApp API key as a bearer token.

In: header

Path Parameters

promotion*integer

The promotion path parameter.

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`

curl -X PATCH "https://sell.app/api/v2/promotions/1" \  -H "X-STORE: launch-lab" \  -H "Content-Type: application/json" \  -d '{    "name": "One More Sprint",    "is_stackable": true  }'

{
  "data": {
    "applies_to": "one_time",
    "subscription_payments": null,
    "store_wide": true,
    "products": [],
    "product_variants": [],
    "name": "One More Sprint",
    "status": "active",
    "starts_at": "2026-08-01T00:00:00Z",
    "ends_at": "2026-08-08T00:00:00Z",
    "priority": 1,
    "is_stackable": true,
    "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
  }
}

{
  "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": "not_found_error",
  "code": "resource_not_found",
  "message": "Not Found.",
  "status": 404,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#resource-not-found"
}

{
  "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"
}

Authorization

AuthorizationBearer <token>

Provide your SellApp API key as a bearer token.

In: header

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

Value in"one_time" | "subscriptions"

subscription_payments?|

Range1 <= value <= 36

store_wide?boolean

products?array<integer>

product_variants?array<integer>

phases?array<>

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

Items1 <= items

Response Body

`application/json`

curl -X PUT "https://sell.app/api/v2/promotions/1" \  -H "X-STORE: launch-lab" \  -H "Content-Type: application/json" \  -d '{    "name": "One More Sprint",    "is_stackable": true  }'

{
  "data": {
    "applies_to": "one_time",
    "subscription_payments": null,
    "store_wide": true,
    "products": [],
    "product_variants": [],
    "name": "One More Sprint",
    "status": "active",
    "starts_at": "2026-08-01T00:00:00Z",
    "ends_at": "2026-08-08T00:00:00Z",
    "priority": 1,
    "is_stackable": true,
    "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
  }
}

{
  "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": "not_found_error",
  "code": "resource_not_found",
  "message": "Not Found.",
  "status": 404,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#resource-not-found"
}

{
  "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"
}

Update a promotion

200application/json

400application/json

401application/json

403application/json

404application/json

422application/json

429application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`