API ReferenceSubscriptions

View subscription capabilities

Check which lifecycle actions are currently available for a subscription.

Use this endpoint before showing subscription management actions in your own UI. customer_only describes who owns the action, not who may call the API: a store token can request a plan change or a payment method update on the customer's behalf. Auto-renewal is the exception. set_auto_renew is reported like every other capability but is only available from the customer portal and has no API endpoint.

While a Stripe, PayPal, or Razorpay subscription is past due or unpaid, every action except cancel_immediately, and on Razorpay update_payment_method, reads unsupported. See Failed payments.

GET
/v2/subscriptions/{productSubscription}/capabilities

Authorization

AuthorizationBearer <token>

Provide your SellApp API key as a bearer token.

In: header

Path Parameters

productSubscription*integer

The productSubscription 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.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://sell.app/api/v2/subscriptions/0/capabilities" \  -H "X-STORE: launch-lab"
{
  "data": {
    "id": 55,
    "subscription_id": "sub_1QwertyExample",
    "capabilities": {
      "pause": {
        "status": "available",
        "customer_reason": null,
        "seller_reason": null
      },
      "resume": {
        "status": "unsupported",
        "customer_reason": "This subscription is not paused.",
        "seller_reason": "Stripe cannot resume a subscription without pause_collection."
      },
      "cancel_at_period_end": {
        "status": "available",
        "customer_reason": null,
        "seller_reason": null
      },
      "cancel_immediately": {
        "status": "available",
        "customer_reason": null,
        "seller_reason": null
      },
      "keep_subscription": {
        "status": "unsupported",
        "customer_reason": "This subscription is not scheduled to cancel, so there is nothing to keep.",
        "seller_reason": "Subscription 55 is not scheduled to cancel at period end."
      },
      "update_payment_method": {
        "status": "customer_only",
        "customer_reason": null,
        "seller_reason": "Customers update their own payment method from the customer portal."
      },
      "change_plan": {
        "status": "customer_only",
        "customer_reason": null,
        "seller_reason": "Customers change subscription plans from the customer portal."
      },
      "shift_billing_date": {
        "status": "unsupported",
        "customer_reason": "Changing the next renewal date is not available for this Stripe subscription.",
        "seller_reason": "Stripe does not support arbitrary next-renewal-date changes for existing subscriptions through this provider flow."
      },
      "set_auto_renew": {
        "status": "unsupported",
        "customer_reason": "Renewals for this subscription are collected by the payment provider.",
        "seller_reason": "The stripe provider renews this subscription itself, so auto renewal cannot be switched here."
      }
    }
  }
}
{
  "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"
}