> ## Documentation Index > Fetch the complete documentation index at: https://docs.meteroid.com/llms.txt > Use this file to discover all available pages before exploring further. # Cancel subscription > Cancel a subscription either immediately or at the end of the billing period. ## OpenAPI ````yaml https://api.meteroid.com/api-docs/openapi.json post /api/v1/subscriptions/{subscription_id}/cancel openapi: 3.1.0 info: title: meteroid description: '' license: name: LicenseRef-Proprietary identifier: LicenseRef-Proprietary version: 0.1.0 servers: [] security: [] tags: - name: Meteroid description: Meteroid API - name: Add-ons - name: Batch Jobs - name: Checkout Sessions - name: Connect description: Manage connected accounts (Express & Standard) - name: Coupons - name: Credit Notes - name: Customers - name: Entitlements - name: Events - name: Features - name: Invoices - name: Metrics - name: OAuth description: OAuth 2.0 token endpoints (public, client-credentials auth) - name: OAuth Apps description: Manage OAuth applications for Connect integrations - name: Plans - name: Product Families - name: Products - name: Subscriptions - name: Usage paths: /api/v1/subscriptions/{subscription_id}/cancel: post: tags: - Subscriptions summary: Cancel subscription description: >- Cancel a subscription either immediately or at the end of the billing period. operationId: cancel_subscription parameters: - name: subscription_id in: path description: Subscription ID required: true schema: $ref: '#/components/schemas/SubscriptionId' example: sub_123 requestBody: content: application/json: schema: $ref: '#/components/schemas/CancelSubscriptionRequest' required: true responses: '200': description: Subscription canceled content: application/json: schema: $ref: '#/components/schemas/CancelSubscriptionResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '404': description: Subscription not found content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '429': description: Too many requests content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '500': description: Internal error content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' security: - bearer_auth: [] components: schemas: SubscriptionId: type: string format: MeteroidId examples: - sub_7n42DGM5Tflk9n8mt7Fhc7 CancelSubscriptionRequest: type: object properties: effective_date: type: - string - 'null' format: date description: >- If not provided, the cancellation will be effective at the end of the current billing or committed period. reason: type: - string - 'null' CancelSubscriptionResponse: type: object required: - subscription properties: subscription: $ref: '#/components/schemas/Subscription' RestErrorResponse: type: object required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string Subscription: type: object required: - id - customer_id - customer_name - billing_day_anchor - currency - plan_id - plan_name - plan_version_id - plan_version - status - start_date - current_period_start - net_terms - mrr_cents - period - created_at - auto_advance_invoices - charge_automatically properties: activated_at: type: - string - 'null' format: date-time description: >- When the subscription was activated (first payment or activation condition met) auto_advance_invoices: type: boolean description: >- If false, invoices will stay in Draft until manually reviewed and finalized. Default to true. billing_day_anchor: type: integer format: int32 billing_start_date: type: - string - 'null' format: date description: When billing started (after any trial period) charge_automatically: type: boolean description: >- Automatically try to charge the customer's configured payment method on finalize. created_at: type: string format: date-time description: When the subscription was created currency: $ref: '#/components/schemas/Currency' current_period_end: type: - string - 'null' format: date description: Current billing period end date current_period_start: type: string format: date description: Current billing period start date customer_alias: type: - string - 'null' customer_id: $ref: '#/components/schemas/CustomerId' customer_name: type: string end_date: type: - string - 'null' format: date description: When the subscription ends (if set) id: $ref: '#/components/schemas/SubscriptionId' invoice_memo: type: - string - 'null' description: Default memo for invoices mrr_cents: type: integer format: int64 description: Monthly recurring revenue in cents minimum: 0 net_terms: type: integer format: int32 description: Payment terms in days (0 = due on issue) minimum: 0 payment_methods_config: oneOf: - type: 'null' - $ref: '#/components/schemas/PaymentMethodsConfig' description: >- Payment methods configuration (Online, BankTransfer, or External) period: $ref: '#/components/schemas/BillingPeriodEnum' description: Billing period (monthly, annual, etc.) plan_description: type: - string - 'null' plan_id: $ref: '#/components/schemas/PlanId' plan_name: type: string plan_version: type: integer format: int32 minimum: 0 plan_version_id: $ref: '#/components/schemas/PlanVersionId' purchase_order: type: - string - 'null' start_date: type: string format: date description: >- When the subscription contract starts (benefits apply from this date) status: $ref: '#/components/schemas/SubscriptionStatusEnum' trial_duration: type: - integer - 'null' format: int32 description: Trial duration in days minimum: 0 ErrorCode: type: string enum: - BAD_REQUEST - NOT_FOUND - CONFLICT - FORBIDDEN - UNAUTHORIZED - TOO_MANY_REQUESTS - INTERNAL_SERVER_ERROR Currency: type: string enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BRL - BSD - BTN - BWP - BYN - BZD - CAD - CDF - CHF - CLP - CNH - CNY - COP - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRU - MUR - MVR - MWK - MXN - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - UYU - UZS - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL examples: - EUR CustomerId: type: string format: MeteroidId examples: - cus_7n42DGM5Tflk9n8mt7Fhc7 PaymentMethodsConfig: oneOf: - $ref: '#/components/schemas/OnlinePaymentMethodConfig' - $ref: '#/components/schemas/BankTransferPaymentMethodConfig' - $ref: '#/components/schemas/ExternalPaymentMethodConfig' description: Online (card/direct debit), BankTransfer, or External. discriminator: propertyName: type mapping: bank_transfer: $ref: '#/components/schemas/BankTransferPaymentMethodConfig' external: $ref: '#/components/schemas/ExternalPaymentMethodConfig' online: $ref: '#/components/schemas/OnlinePaymentMethodConfig' BillingPeriodEnum: type: string enum: - MONTHLY - QUARTERLY - SEMIANNUAL - ANNUAL PlanId: type: string format: MeteroidId examples: - plan_7n42DGM5Tflk9n8mt7Fhc7 PlanVersionId: type: string format: MeteroidId examples: - plv_7n42DGM5Tflk9n8mt7Fhc7 SubscriptionStatusEnum: type: string title: SubscriptionStatus enum: - PENDING_ACTIVATION - PENDING_CHARGE - TRIAL_ACTIVE - ACTIVE - TRIAL_EXPIRED - PAUSED - SUSPENDED - CANCELLED - COMPLETED - SUPERSEDED - ERRORED OnlinePaymentMethodConfig: type: object properties: config: oneOf: - type: 'null' - $ref: '#/components/schemas/OnlineMethodsConfig' description: If None, inherits all online providers from invoicing entity. BankTransferPaymentMethodConfig: type: object properties: account_id: oneOf: - type: 'null' - $ref: '#/components/schemas/BankAccountId' ExternalPaymentMethodConfig: type: object OnlineMethodsConfig: type: object properties: card: oneOf: - type: 'null' - $ref: '#/components/schemas/OnlineMethodConfig' direct_debit: oneOf: - type: 'null' - $ref: '#/components/schemas/OnlineMethodConfig' BankAccountId: type: string format: MeteroidId examples: - ba_7n42DGM5Tflk9n8mt7Fhc7 OnlineMethodConfig: type: object required: - enabled properties: enabled: type: boolean securitySchemes: bearer_auth: type: http scheme: bearer ````