SellApp
API ReferenceSubscriptions

Cancel a subscription

Cancel an active subscription now or at the end of its billing period, or cancel one with a payment still owed now.

Cancel an active subscription now or at the end of its billing period. A subscription with a payment still owed can only be cancelled now: a past-due one the store bills in house, or a past-due or unpaid Stripe, PayPal, or Razorpay subscription. See Failed payments.

You can either:

  1. Schedule the cancellation for the end of the current billing period.
  2. Cancel immediately.
  3. Optionally refund the most recent payment when canceling immediately.

Important

This endpoint is deprecated. New integrations should use Cancel at period end and Cancel immediately instead.

Note

Refund options are only supported for immediate cancellations. If you send cancel_at_period_end: true, you should not include refund flags.

PATCH
/v2/subscriptions/{subscription}/cancel

Authorization

AuthorizationBearer <token>

Provide your SellApp API key as a bearer token.

In: header

Path Parameters

subscription*integer

The subscription path parameter.

Header Parameters

Idempotency-Key?string

A caller-generated key, unique per store and subscription lifecycle request. Sending it here is the same as sending idempotency_key in the body.

Lengthlength <= 128
Idempotency-Key?string

Caller-generated key for safely retrying this operation. The JSON idempotency_key field is also accepted; when both are sent, the header takes precedence.

Lengthlength <= 128
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/subscriptions/55/cancel" \  -H "X-STORE: launch-lab" \  -H "Content-Type: application/json" \  -d '{    "cancel_at_period_end": true,    "idempotency_key": "design-kit-subscription-55-cancel-v1"  }'
{
  "data": {
    "id": 55,
    "invoice_id": 9001,
    "provider": "stripe",
    "subscription_id": "sub_1QwertyExample",
    "customer_id": "cus_Example123",
    "provider_subscription_id": "sub_1QwertyExample",
    "provider_customer_id": "cus_Example123",
    "customer": {
      "id": 314,
      "email": "maya.chen@example.com",
      "external_id": "crm_314",
      "name": "Maya Chen",
      "locale": "en-GB",
      "metadata": {}
    },
    "customer_email": "natya.sadella@example.com",
    "status": "ACTIVE",
    "current_period_start": "2026-08-30T12:05:00.000000Z",
    "current_period_end": "2026-09-30T12:05:00.000000Z",
    "trial_ends_at": null,
    "cancel_at_period_end": true,
    "cancellation_in_progress": false,
    "store_id": 1,
    "product_variant_id": 4321,
    "current_plan_variant_id": 99,
    "auto_renew": false,
    "paused_at": null,
    "pause_resumes_at": null,
    "canceled_immediately_at": null,
    "payment_method_updated_at": "2026-03-15T09:30:00.000000Z",
    "last_customer_action_at": "2026-03-23T00:00:00.000000Z",
    "created_at": "2026-03-01T00:00:00.000000Z",
    "updated_at": "2026-03-23T00:00:00.000000Z"
  },
  "message": "Subscription will be cancelled at the end of the current period."
}
{
  "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"
}

Read subscriptions

List, search, and retrieve canonical subscription records.

Cancel a subscription immediately with a refund PATCH

To cancel immediately and refund the latest subscription payment, send cancel_at_period_end: false with refund_last_payment: true.