Subscriptions

Subscriptions represent recurring product purchases made through your store. The V2 subscriptions endpoint currently lets you cancel an active subscription either immediately or at the end of the current billing period.

The subscription model

The subscription model contains the key billing and customer details associated with a recurring subscription.

Properties

Name
id
Type
integer
Description
(read-only) The unique identifier for the subscription record.
Name
invoice_id
Type
integer | null
Description
(read-only) The original invoice ID linked to this subscription, if available.
Name
provider
Type
string
Description
(read-only) The billing provider handling the subscription, such as stripe or paypal.
Name
subscription_id
Type
string
Description
(read-only) The provider subscription identifier.
Name
customer_id
Type
string
Description
(read-only) The provider customer identifier.
Name
customer_email
Type
string
Description
(read-only) The customer email associated with the subscription.
Name
status
Type
string
Description
(read-only) The current subscription status, such as ACTIVE or CANCELED.
Name
current_period_start
Type
timestamp | null
Description
(read-only) When the current billing period started.
Name
current_period_end
Type
timestamp | null
Description
(read-only) When the current billing period ends or ended.
Name
cancel_at_period_end
Type
boolean
Description
(read-only) Whether the subscription is scheduled to cancel at the end of the current billing period.
Name
cancellation_in_progress
Type
boolean
Description
(read-only) Whether an immediate cancellation request has been accepted and is still waiting on provider webhook sync.
Name
store_id
Type
integer
Description
(read-only) The ID of the store this subscription belongs to.
Name
product_variant_id
Type
integer | null
Description
(read-only) The ID of the subscribed product variant.
Name
created_at
Type
timestamp
Description
(read-only) Time at which the subscription record was created.
Name
updated_at
Type
timestamp
Description
(read-only) Time at which the subscription record was last updated.

PATCH/v2/subscriptions/:id/cancel

Cancel a subscription

This endpoint lets you cancel an active subscription programmatically.

You can either:

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

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

Required attributes

Name
cancel_at_period_end
Type
boolean
Description
Set to true to schedule cancellation for the end of the current billing period, or false to cancel immediately.

Optional attributes

Name
refund_last_payment
Type
boolean
Description
When canceling immediately, set this to true to refund the latest subscription payment.
Name
pro_rated_refund
Type
boolean
Description
When refunding the latest payment, set this to true to issue a pro-rated refund instead of a full refund.

Request (Cancel at period end)

PATCH

/v2/subscriptions/:id/cancel

$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->append('{
  "cancel_at_period_end": true
}');

$request->setRequestUrl('https://sell.app/api/v2/subscriptions/123/cancel');
$request->setRequestMethod('PATCH');
$request->setBody($body);
$request->setHeaders([
  'Content-Type' => 'application/json',
  'accept' => 'application/json',
  'Authorization' => 'Bearer {ApiKeyHere}'
]);

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

Response

{
  "data": {
    "id": 123,
    "invoice_id": 456,
    "provider": "stripe",
    "subscription_id": "sub_1QwertyExample",
    "customer_id": "cus_Example123",
    "customer_email": "customer@example.com",
    "status": "ACTIVE",
    "current_period_start": "2026-03-01T00:00:00.000000Z",
    "current_period_end": "2026-04-01T00:00:00.000000Z",
    "cancel_at_period_end": true,
    "cancellation_in_progress": false,
    "store_id": 1,
    "product_variant_id": 99,
    "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."
}

PATCH/v2/subscriptions/:id/cancel

Cancel a subscription immediately with a refund

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

Set pro_rated_refund: true if you want a pro-rated refund instead of a full refund.

Request (Immediate cancellation)

PATCH

/v2/subscriptions/:id/cancel

curl --request PATCH \
  --url https://sell.app/api/v2/subscriptions/123/cancel \
  --header 'Authorization: Bearer {ApiKeyHere}' \
  --header 'Content-Type: application/json' \
  --header 'accept: application/json' \
  --data '{
    "cancel_at_period_end": false,
    "refund_last_payment": true,
    "pro_rated_refund": true
  }'

Response

{
  "data": {
    "id": 123,
    "invoice_id": 456,
    "provider": "stripe",
    "subscription_id": "sub_1QwertyExample",
    "customer_id": "cus_Example123",
    "customer_email": "customer@example.com",
    "status": "ACTIVE",
    "current_period_start": "2026-03-01T00:00:00.000000Z",
    "current_period_end": "2026-04-01T00:00:00.000000Z",
    "cancel_at_period_end": false,
    "cancellation_in_progress": true,
    "store_id": 1,
    "product_variant_id": 99,
    "created_at": "2026-03-01T00:00:00.000000Z",
    "updated_at": "2026-03-23T00:00:00.000000Z"
  },
  "message": "Subscription cancellation requested."
}