Preview a renewal date change
Preview a new renewal date before confirming it.
Use this endpoint when the subscription's billing-date policy requires a preview before confirmation. No payment method supports renewal-date changes today: Stripe, PayPal, Razorpay, and subscriptions the store bills in house all report shift_billing_date as unsupported in the capabilities response, and this endpoint returns 422 under errors.subscription before any preview is taken. See Handle subscriptions for an example that checks first.
Provide your SellApp API key as a bearer token.
In: header
Path Parameters
The productSubscription path parameter.
Header Parameters
A caller-generated key, unique per store and subscription lifecycle request. Sending it here is the same as sending idempotency_key in the body.
length <= 128Caller-generated key for safely retrying this operation. The JSON idempotency_key field is also accepted; when both are sent, the header takes precedence.
length <= 128Store 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
Request contract for a payment method that supports renewal-date changes. No payment method supports them today, so every request returns 422.
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 POST "https://sell.app/api/v2/subscriptions/0/actions/change-renewal-date/preview" \ -H "X-STORE: launch-lab" \ -H "Content-Type: application/json" \ -d '{ "renewal_date": "2026-10-01T12:00:00Z", "reason": "Align Maya\'s membership with the monthly reading circle." }'No payment method returns a successful response today: Stripe, PayPal, Razorpay, and in-house billing all refuse renewal-date changes with 422. Check subscription capabilities first. The 200 schema describes the interface a payment method would use, not current behavior.
{
"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"
}