SellApp
API ReferencePromotions

Update a promotion

Update promotion settings and optionally replace its phases.

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.

PATCH
/v2/promotions/{promotion}

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.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

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": {
    "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"
}
PUT
/v2/promotions/{promotion}

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.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

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

Retrieve a promotion

Retrieve one promotion and its ordered phases.

Replace promotion phases

Replace a promotion's complete ordered phase set.