/subscriptions/{subscription_id}/cancel Cancels a subscription using its ID.
By default, active subscriptions are canceled at the end of the billing period. When you send a request to cancel, Paddle creates a scheduled_change against the subscription entity to say that it should cancel at the end of the current billing period. Its status remains active until after the effective date of the scheduled change, at which point it changes to canceled.
You can cancel a subscription right away by including effective_from in your request, setting the value to immediately. If successful, your response includes a copy of the updated subscription entity with the status of canceled. Canceling immediately is the default behavior for paused subscriptions.
You can't reinstate a canceled subscription.
Requires subscription.write
permission.
Path parameters
Request body
next_billing_periodnext_billing_period, which creates a
scheduled_change to apply the subscription change at the end of the billing period.next_billing_periodTakes effect on the next billing period.immediatelyTakes effect immediately.
Response (200)
sub_01h04vsc0qhwtsbsxh3422wjs4sub_.^sub_[a-z\d]{26}$activeSubscription is active. Paddle is billing for this subscription and related transactions aren't past due.canceledSubscription is canceled. Automatically set by Paddle when a subscription is canceled. When a subscription is set to cancel on the next billing period, a scheduled change for the cancellation is created. The subscription status moves to canceled when the scheduled change takes effect.past_dueSubscription has an overdue payment. Automatically set by Paddle when payment fails for an automatically-collected transaction, or when payment terms have elapsed for a manually-collected transaction (an invoice).pausedSubscription is paused. Automatically set by Paddle when a subscription is paused. When a subscription is set to pause on the next billing period, a scheduled change for the pause is created. The subscription status moves topausedwhen the scheduled change takes effect.trialingSubscription is in trial.
ctm_01grnn4zta5a1mf02jjze7y2ysctm_.^ctm_[a-z\d]{26}$add_01gm302t81w94gyjpjpqypkzkfadd_.^add_[a-z\d]{26}$biz_01grrebrzaee2qj2fqqhmcyzajbiz_.^biz_[a-z\d]{26}$USD, EUR, or GBP if collection_mode is manual.USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
2024-10-12T07:20:50.52Z2024-10-13T07:20:50.52Z2024-10-12T07:20:50.52Z2024-10-12T07:20:50.52Z2024-10-12T07:20:50.52Z2024-10-12T07:20:50.52Z2024-10-12T07:20:50.52Zdsc_01gv5kpg05xp104ek2fmgjwttfdsc_.^dsc_[a-z\d]{26}$2024-10-12T07:20:50.52Z2024-10-12T07:20:50.52ZrecurringDiscount applies to multiple billing periods.one-offDiscount applies to a single billing period only. Returned when a subscription is created in trial with a discount. The discount is removed from the subscription on renewal.
automaticautomatic for checkout, manual for invoices.automaticPayment is collected automatically using a checkout initially, then using a payment method on file.manualPayment is collected manually. Customers are sent an invoice with payment terms and can make a payment offline or using a checkout. Requiresbilling_details.
collection_mode is manual.falsefalse.dayweekmonthyear
null for paused and canceled subscriptions.2024-10-12T07:20:50.52Z2024-10-12T07:20:50.52Zdayweekmonthyear
null if no scheduled changes.cancelSubscription is scheduled to cancel. Its status changes tocanceledon theeffective_atdate.pauseSubscription is scheduled to pause. Its status changes topausedon theeffective_atdate.resumeSubscription is scheduled to resume. Its status changes toactiveon theeffective_atdate.
2024-10-12T07:20:50.52Z2024-10-12T07:20:50.52ZCustomer portal deep links for this subscription.
Authenticated links are only returned when your API key has Customer portal session (Write) permission. For security, the token appended to authenticated links is temporary. You shouldn't store them.
https://buyer-portal.paddle.com/subscriptions/sub_01gtewvbsyeqyhtp2vtc2mctq8/update-payment-method?token=null for manually-collected subscriptions.https://buyer-portal.paddle.com/subscriptions/sub_01gtewvbsyeqyhtp2vtc2mctq8/cancel?token=activeThis item is active. It is not in trial and Paddle bills for it.inactiveThis item is not active. Set when the related subscription is paused.trialingThis item is in trial. Paddle has not billed for it.
false if one-time.2024-10-12T07:20:50.52Z2024-10-13T07:20:50.52Z2024-10-12T07:20:50.52Z2024-10-12T07:20:50.52Z2024-10-12T07:20:50.52Z2024-10-12T07:20:50.52Zpri_01gsz8z1q1n00f12qt82y31smhpri_.^pri_[a-z\d]{26}$pro_01gsz97mq9pa4fkyy0wqenepkzpro_.^pro_[a-z\d]{26}$standardcustomNon-catalog item. Typically created for a specific transaction or subscription. Not returned when listing or shown in the Paddle dashboard.standardStandard item. Can be considered part of your catalog and reused across transactions and subscriptions easily.
null if price is non-recurring (one-time).dayweekmonthyear
null for no trial period. Requires billing_cycle.dayweekmonthyear
truetrue) or not (false) when trialing. If false, customers can sign up for subscription without entering their payment details, often referred to as a "cardless trial."account_settingaccount_settingPrices use the setting from your account.externalPrices are exclusive of tax.internalPrices are inclusive of tax.locationPrices are inclusive or exclusive of tax, depending on the country of the transaction.
unit_price_overrides.USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
string
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
{"minimum":1,"maximum":100}11maximum set.100100minimum set. Must be greater than or equal to the minimum value.activeactiveEntity is active and can be used.archivedEntity is archived, so can't be used.
{"customer_reference_id":"abcd1234"}null if this entity is not imported.9b95b0b8-e10f-441a-862e-1936a6d818abpaddle_classic2024-10-12T07:20:50.52Z2024-10-13T07:20:50.52Zpro_01gsz97mq9pa4fkyy0wqenepkzpro_.^pro_[a-z\d]{26}$standardcustomNon-catalog item. Typically created for a specific transaction or subscription. Not returned when listing or shown in the Paddle dashboard.standardStandard item. Can be considered part of your catalog and reused across transactions and subscriptions easily.
digital-goodsNon-customizable digital files or media (not software) acquired with an up front payment that can be accessed without any physical product being delivered.ebooksDigital books and educational material which is sold with permanent rights for use by the customer.implementation-servicesRemote configuration, set-up, and integrating software on behalf of a customer.professional-servicesServices that involve the application of your expertise and specialized knowledge of a software product.saasProducts that allow users to connect to and use online or cloud-based applications over the Internet.
+ Show all values− Hide values
software-programming-servicesstandardSoftware products that are pre-written and can be downloaded and installed onto a local device.training-servicesTraining and education services related to software products.website-hostingCloud storage service for personal or corporate information, assets, or intellectual property.
Image Url
null
Empty String
{"customer_reference_id":"abcd1234"}activeactiveEntity is active and can be used.archivedEntity is archived, so can't be used.
null if this entity is not imported.9b95b0b8-e10f-441a-862e-1936a6d818abpaddle_classic2024-10-12T07:20:50.52Z2024-10-13T07:20:50.52Z{"customer_reference_id":"abcd1234"}null if this entity is not imported.9b95b0b8-e10f-441a-862e-1936a6d818abpaddle_classicsubconreq_01gm302t81w94gyjpjpqypkzkfsubconreq_.^subconreq_[a-z\d]{26}$trial_endingConsent required because the trial period is ending.introductory_discount_endingConsent required because an initial discount is ending.
pendingConsent not yet granted. Subscription is canceled on next renewal.grantedConsent granted. Subscription renews normally.voidedConsent voided. Consent requirement is no longer applicable, either because the consent is no longer required, or another consent requirement has replaced it.
2024-10-12T07:20:50.52Znull if there is no next_billed_at or the consent requirement does not apply to the current billing period.2024-10-12T07:20:50.52Z2024-10-12T07:20:50.52Z2024-10-12T07:20:50.52Z2024-10-12T07:20:50.52Zb15ec92e-8688-40d4-a04d-f44cbec93355{ "effective_from": "immediately"}{ "data": { "id": "sub_01hv8y5ehszzq0yv20ttx3166y", "status": "canceled", "customer_id": "ctm_01hv8wt8nffez4p2t6typn4a5j", "address_id": "add_01hv8y4jk511j9g2n9a2mexjbx", "business_id": null, "currency_code": "USD", "created_at": "2024-04-12T10:38:00.761Z", "updated_at": "2024-04-12T11:24:54.873Z", "started_at": "2024-04-12T10:37:59.556997Z", "first_billed_at": "2024-04-12T10:37:59.556997Z", "next_billed_at": null, "paused_at": null, "canceled_at": "2024-04-12T11:24:54.868Z", "collection_mode": "automatic", "billing_details": null, "current_billing_period": null, "billing_cycle": { "frequency": 1, "interval": "month" }, "scheduled_change": null, "items": [ { "status": "active", "quantity": 20, "recurring": true, "created_at": "2024-04-12T10:38:00.761Z", "updated_at": "2024-04-12T10:49:38.76Z", "previously_billed_at": "2024-04-12T10:37:59.556997Z", "next_billed_at": null, "trial_dates": null, "price": { "id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg", "type": "standard", "description": "Monthly", "name": "Monthly (per seat)", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "month" }, "trial_period": null, "unit_price": { "amount": "3000", "currency_code": "USD" }, "unit_price_overrides": [], "custom_data": null, "status": "active", "quantity": { "minimum": 1, "maximum": 999 }, "import_meta": null, "created_at": "2023-02-23T13:55:22.538367Z", "updated_at": "2024-04-11T13:54:52.254748Z" }, "product": { "id": "pro_01gsz4t5hdjse780zja8vvr7jg", "name": "AeroEdit Pro", "type": "standard", "tax_category": "standard", "description": "Designed for professional pilots, including all features plus in Basic plus compliance monitoring, route optimization, and third-party integrations.", "image_url": "https://paddle.s3.amazonaws.com/user/165798/bT1XUOJAQhOUxGs83cbk_pro.png", "custom_data": { "features": { "aircraft_performance": true, "compliance_monitoring": true, "flight_log_management": true, "payment_by_invoice": false, "route_planning": true, "sso": false }, "suggested_addons": [ "pro_01h1vjes1y163xfj1rh1tkfb65", "pro_01gsz97mq9pa4fkyy0wqenepkz" ], "upgrade_description": "Move from Basic to Pro to take advantage of aircraft performance, advanced route planning, and compliance monitoring." }, "status": "active", "import_meta": null, "created_at": "2023-02-23T12:43:46.605Z", "updated_at": "2024-04-05T15:53:44.687Z" } }, { "status": "active", "quantity": 1, "recurring": true, "created_at": "2024-04-12T10:38:00.761Z", "updated_at": "2024-04-12T10:38:00.761Z", "previously_billed_at": "2024-04-12T10:37:59.556997Z", "next_billed_at": null, "trial_dates": null, "price": { "id": "pri_01h1vjfevh5etwq3rb416a23h2", "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65", "type": "standard", "description": "Monthly", "name": "Monthly (recurring addon)", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "month" }, "trial_period": null, "unit_price": { "amount": "10000", "currency_code": "USD" }, "unit_price_overrides": [], "custom_data": null, "status": "active", "quantity": { "minimum": 1, "maximum": 100 }, "import_meta": null, "created_at": "2023-06-01T13:31:12.625056Z", "updated_at": "2024-04-09T07:23:00.907834Z" }, "product": { "id": "pro_01h1vjes1y163xfj1rh1tkfb65", "name": "Analytics addon", "type": "standard", "tax_category": "standard", "description": "Unlock advanced insights into your flight data with enhanced analytics and reporting features. Includes customizable reporting templates and trend analysis across flights.", "image_url": "https://paddle.s3.amazonaws.com/user/165798/97dRpA6SXzcE6ekK9CAr_analytics.png", "custom_data": null, "status": "active", "import_meta": null, "created_at": "2023-06-01T13:30:50.302Z", "updated_at": "2024-04-05T15:47:17.163Z" } }, { "status": "active", "quantity": 1, "recurring": true, "created_at": "2024-04-12T10:49:38.765Z", "updated_at": "2024-04-12T10:49:38.765Z", "previously_billed_at": "2024-04-12T10:49:38.765Z", "next_billed_at": null, "trial_dates": null, "price": { "id": "pri_01gsz95g2zrkagg294kpstx54r", "product_id": "pro_01gsz92krfzy3hcx5h5rtgnfwz", "type": "standard", "description": "Monthly (recurring addon)", "name": "Monthly (recurring addon)", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "month" }, "trial_period": null, "unit_price": { "amount": "25000", "currency_code": "USD" }, "unit_price_overrides": [], "custom_data": null, "status": "active", "quantity": { "minimum": 1, "maximum": 1 }, "import_meta": null, "created_at": "2023-02-23T13:59:52.159927Z", "updated_at": "2024-04-09T07:27:48.018296Z" }, "product": { "id": "pro_01gsz92krfzy3hcx5h5rtgnfwz", "name": "VIP support", "type": "standard", "tax_category": "standard", "description": "Get exclusive access to our expert team of product specialists, available to help you make the most of your AeroEdit subscription.", "image_url": "https://paddle.s3.amazonaws.com/user/165798/qgyipKJwRtq98YNboipo_vip-support.png", "custom_data": null, "status": "active", "import_meta": null, "created_at": "2023-02-23T13:58:17.615Z", "updated_at": "2024-04-05T15:44:02.893Z" } } ], "custom_data": null, "management_urls": { "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01hv8y5ehszzq0yv20ttx3166y/update-payment-method", "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01hv8y5ehszzq0yv20ttx3166y/cancel" }, "discount": null, "import_meta": null, "consent_requirements": [] }, "meta": { "request_id": "f21058d1-281a-4877-bb3b-261a753d08c4" }}