> ## Documentation Index > Fetch the complete documentation index at: https://juo.dev/llms.txt > Use this file to discover all available pages before exploring further. # Cancel subscription > Used to cancel a subscription. ## OpenAPI ````yaml openapi-admin.json POST /subscriptions/{subscriptionId}/cancel openapi: 3.1.0 info: title: Juo Admin API version: 1.0.0 description: >- Programmatic access to subscription management for merchants. ## Core Resources - **Subscriptions** — the central entity. Belongs to a Customer, contains Items (product variants) and Discounts. Lifecycle: `active` → `paused` or `cancelled`; `paused` → `active` or `cancelled`; `cancelled` → `active` (via reactivate). - **Items** — subscription items (product variants) (quantity, price, billing/delivery policies). - **Discounts** — applied to subscriptions by discount code or manually (percentage or fixed amount, targeting subscription items or shipping). - **Customers** — customers who own subscriptions and payment methods. - **Products / Variants** — catalog products and variants that can be assigned to subscription plans. - **Schedules** — a read-only projection of upcoming billing orders, derived from subscription state, active schedule adjustments, and triggered workflows. **Schedule adjustments never modify the subscription** — they apply changes to upcoming orders matching the specified criteria (by cycle, date, or both), which may cover one or more orders. For permanent changes (billing frequency, items, payment method, delivery address), update the subscription directly. - **Workflows** — interactive customer-facing flows (retention, dunning, onboarding). Contain Steps connected by Transitions and produce Runs on each execution. Supports A/B experiment steps. ## Authentication Every request requires: - `X-Juo-Admin-Api-Key` header — the merchant's Admin API key. - `X-Tenant-ID` header — the store identifier (myshopify domain, e.g. `my-store.myshopify.com`). servers: - url: https://api.juo.io/admin/v1 security: - AdminApiKey: [] - BearerToken: [] tags: - name: subscriptions description: >- Recurring billing agreements with customers. Manage lifecycle (pause, resume, cancel, reactivate), items, and discounts. - name: customers description: Customers who own subscriptions. Create and update customer records. - name: products description: >- Products and variants linked to subscription plans. Manage catalog and plan assignments. - name: schedules description: >- Read-only view of upcoming billing orders generated from subscription state, schedule adjustments, and workflows. Use schedule adjustments for targeted changes to upcoming orders (scoped by cycle number, date, or both) — they never alter the subscription itself. For permanent changes (billing frequency, items, payment method), update the subscription directly. - name: workflows description: >- Interactive customer-facing flows for retention, dunning, and onboarding. Define steps, publish, and track execution runs and experiments. paths: /subscriptions/{subscriptionId}/cancel: post: tags: - subscriptions summary: Cancel a subscription description: >- Permanently cancels an active or paused subscription, stopping all future billing. Accepts an optional cancellation reason and a flag to notify the customer by email. Use `reactivate` to reverse a cancellation. parameters: - schema: format: uuid type: string in: path name: subscriptionId required: true description: The subscription identifier - $ref: '#/components/parameters/TenantHeader' requestBody: content: application/json: schema: type: object properties: cancellationReason: minLength: 1 description: The reason for canceling the subscription. type: string notifyCustomer: description: >- Choose whether to send notifications to customers when their subscription is canceled. type: boolean required: - notifyCustomer required: true responses: '200': description: Default Response content: application/json: schema: $ref: '#/components/schemas/Subscription' '400': description: >- Bad request — invalid input or violated business rule (e.g., wrong subscription status for the requested operation). '401': description: Unauthorized — missing, expired, or invalid API key. '403': description: Forbidden — authenticated but not permitted to access this resource. '404': description: >- Not found — the resource does not exist or belongs to a different tenant. '422': description: >- Unprocessable entity — well-formed request that fails semantic validation. components: parameters: TenantHeader: name: X-Tenant-ID x-speakeasy-name-override: tenant x-speakeasy-globals-hidden: true in: header schema: type: string required: true description: >- Unique identifier of the tenant in the system (usually a store identifier) schemas: Subscription: type: object properties: id: format: uuid description: Unique subscription identifier (UUID). type: string example: 550e8400-e29b-41d4-a716-446655440000 resource: type: string enum: - subscription serial: minLength: 1 description: >- Unique serial number that increments sequentially with each new subscription within a store. type: string example: '1042' status: type: string enum: - active - paused - canceled - failed - expired - merged description: >- Subscription lifecycle status. `active`: billing runs on schedule; `paused`: billing suspended until resumed; `canceled`: permanently stopped (can be reactivated); `failed`: latest billing attempt failed; `expired`: reached configured end date; `merged`: consolidated into another subscription. example: active createdAt: format: date-time description: Purchase date of the subscription. type: string updatedAt: format: date-time description: Last update date of the subscription. type: string canceledAt: format: date-time description: Cancellation date of the subscription. type: - 'null' - string nextBillingDate: format: date-time description: >- The next billing date determines when the renewal process begins its billing phase. When billing succeeds, it creates one order—or multiple orders for prepaid subscriptions. type: - 'null' - string example: '2024-02-15T10:00:00.000Z' currentCycle: minimum: 0 description: >- The subscription's billing cycle count. Starts at 0 before the first billing completes, increments by 1 with each successful billing. type: integer example: 1 currencyCode: minLength: 3 maxLength: 3 description: >- ISO 4217 currency code that applies to both item prices and delivery price. type: string example: USD billingPolicy: description: How often and when the subscription is billed. type: object properties: interval: type: string enum: - DAY - MONTH - WEEK - YEAR description: 'Billing frequency unit. One of: `WEEK`, `MONTH`, `YEAR`, `DAY`.' example: MONTH intervalCount: minimum: 1 description: Number of interval units between billing cycles. type: integer example: 1 required: - interval - intervalCount deliveryPolicy: description: >- How often shipments are dispatched. Usually matches the billing policy. type: object properties: interval: type: string enum: - DAY - MONTH - WEEK - YEAR description: 'Delivery frequency unit. One of: `WEEK`, `MONTH`, `YEAR`, `DAY`.' example: MONTH intervalCount: minimum: 1 description: Number of interval units between deliveries. type: integer example: 1 required: - interval - intervalCount deliveryMethod: oneOf: - type: 'null' - type: object properties: type: type: string enum: - shipping - local-delivery - pickup description: >- Delivery method type. One of: `shipping`, `local-delivery`, `pickup`. examples: - shipping title: type: - 'null' - string description: type: - 'null' - string required: - type - title - description customAttributes: description: >- Arbitrary key-value pairs attached to this subscription. In the Customer API, attributes whose key starts with `_` are hidden and excluded. type: array items: type: object properties: key: minLength: 1 type: string value: type: string required: - key - value customer: description: >- Customer `id` when not expanded, or the full `Customer` object when the field name is included in the `expand` query parameter. Can be null. anyOf: - minLength: 1 description: Customer ID (numeric string). examples: - '7654321' type: string - $ref: '#/components/schemas/Customer' - type: 'null' items: minItems: 1 type: array items: $ref: '#/components/schemas/SubscriptionItem' discounts: type: array items: $ref: '#/components/schemas/SubscriptionDiscount' paymentMethod: description: >- CustomerPaymentMethod `id` when not expanded, or the full `CustomerPaymentMethod` object when the field name is included in the `expand` query parameter. Can be null. anyOf: - format: uuid type: string - $ref: '#/components/schemas/CustomerPaymentMethod' - type: 'null' deliveryAddress: oneOf: - type: 'null' - type: object properties: firstName: minLength: 1 description: Customer's first name. type: - 'null' - string lastName: minLength: 1 description: Customer's last name. type: - 'null' - string address1: minLength: 1 description: Primary street address. type: - 'null' - string address2: minLength: 1 description: Additional address information (apartment, suite, etc.) type: - 'null' - string zip: minLength: 1 description: Postal/ZIP code. type: - 'null' - string city: minLength: 1 description: City name. type: - 'null' - string country: minLength: 1 description: Full country name. type: - 'null' - string countryCode: minLength: 2 maxLength: 2 description: Two-letter country code (ISO 3166-1). type: - 'null' - string provinceCode: minLength: 1 description: Province/state code. type: - 'null' - string province: minLength: 1 description: Full province/state name. type: - 'null' - string phone: minLength: 1 description: Contact phone number. type: - 'null' - string company: minLength: 1 description: Company name. type: - 'null' - string required: - firstName - lastName - address1 - address2 - zip - city - country - countryCode - provinceCode - province - phone - company title: Address deliveryPrice: minimum: 0 description: The delivery price for the upcoming renewal. type: number required: - id - resource - serial - status - createdAt - updatedAt - canceledAt - nextBillingDate - currentCycle - currencyCode - billingPolicy - deliveryPolicy - deliveryMethod - customAttributes - customer - items - discounts - paymentMethod - deliveryAddress - deliveryPrice title: Subscription Customer: type: object properties: id: minLength: 1 description: Customer ID (numeric string). type: string example: '7654321' resource: type: string enum: - customer displayName: minLength: 1 description: Customer's full name. type: string example: Jane Smith email: format: email description: Customer's contact email. type: - 'null' - string example: jane.smith@example.com phone: minLength: 1 description: Customer's contact phone number in E.164 format. type: - 'null' - string example: '+15550100' required: - id - resource - displayName - email - phone title: Customer SubscriptionItem: type: object properties: id: format: uuid description: Unique subscription item identifier (UUID). type: string example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 resource: type: string enum: - subscription-item title: minLength: 1 description: Product title. type: string example: Monthly Coffee Blend subtitle: minLength: 1 description: Variant title. Matches the variant title in most cases. type: - 'null' - string example: 250g / Ground quantity: minimum: 1 description: Number of units ordered per billing cycle. type: integer example: 1 totalPrice: minimum: 0 description: >- Final item price per billing cycle including all applicable discounts. type: number example: 24.99 recurringCycleLimit: minimum: 1 description: >- Maximum number of billing cycles this item remains on the subscription. The item is automatically removed once this limit is reached. Null means no limit. type: - 'null' - integer example: 3 canceledAt: format: date-time description: Cancellation date of the item. type: - 'null' - string billingPolicy: oneOf: - type: 'null' - type: object properties: interval: anyOf: - type: string enum: - DAY - type: string enum: - WEEK - type: string enum: - MONTH - type: string enum: - YEAR intervalCount: minimum: 1 maximum: 365 type: integer anchors: type: array items: type: object properties: type: anyOf: - type: string enum: - WEEKDAY - type: string enum: - MONTHDAY - type: string enum: - YEARDAY day: minimum: 1 maximum: 31 type: integer month: minimum: 1 maximum: 12 type: - 'null' - integer cutoffDay: minimum: 1 maximum: 31 type: - 'null' - integer required: - type - day - month - cutoffDay minCycles: minimum: 1 type: - 'null' - integer maxCycles: minimum: 1 type: - 'null' - integer required: - interval - intervalCount - anchors - minCycles - maxCycles title: BillingPolicy deliveryPolicy: oneOf: - type: 'null' - type: object properties: interval: anyOf: - type: string enum: - DAY - type: string enum: - WEEK - type: string enum: - MONTH - type: string enum: - YEAR intervalCount: minimum: 1 maximum: 365 type: integer anchors: type: array items: type: object properties: type: anyOf: - type: string enum: - WEEKDAY - type: string enum: - MONTHDAY - type: string enum: - YEARDAY day: minimum: 1 maximum: 31 type: integer month: minimum: 1 maximum: 12 type: - 'null' - integer cutoffDay: minimum: 1 maximum: 31 type: - 'null' - integer required: - type - day - month - cutoffDay required: - interval - intervalCount - anchors title: DeliveryPolicy customAttributes: description: >- Arbitrary key-value pairs attached to this subscription item. In the Customer API, attributes whose key starts with `_` are hidden and excluded. type: array items: type: object properties: key: minLength: 1 type: string value: type: string required: - key - value variant: description: >- ProductVariant `id` when not expanded, or the full `ProductVariant` object when the field name is included in the `expand` query parameter. Can be null. anyOf: - minLength: 1 type: string - $ref: '#/components/schemas/ProductVariant' - type: 'null' product: description: >- Product `id` when not expanded, or the full `Product` object when the field name is included in the `expand` query parameter. Can be null. anyOf: - minLength: 1 type: string - $ref: '#/components/schemas/Product' - type: 'null' required: - id - resource - title - subtitle - quantity - totalPrice - recurringCycleLimit - canceledAt - billingPolicy - deliveryPolicy - customAttributes - variant - product title: SubscriptionItem SubscriptionDiscount: type: object properties: id: format: uuid type: string resource: type: string enum: - subscription-discount title: minLength: 1 description: >- The title of the discount shown to customers, typically displayed as a discount code. type: - 'null' - string target: anyOf: - type: object properties: type: type: string enum: - shipping required: - type - type: object properties: type: type: string enum: - line selector: anyOf: - type: object properties: type: type: string enum: - all required: - type - type: object properties: type: type: string enum: - some lines: type: array items: format: uuid type: string required: - type - lines required: - type - selector value: anyOf: - type: object properties: amount: exclusiveMinimum: 0 type: number type: type: string enum: - fixed-amount appliesOnEachItem: description: >- When true, the amount will be proportionally split among all the items. type: boolean required: - amount - type - appliesOnEachItem - type: object properties: percentage: exclusiveMinimum: 0 maximum: 100 type: number type: type: string enum: - percentage required: - percentage - type recurringCycleLimit: minimum: 1 description: >- The number of billing cycles for which this discount will be applied. After the recurring cycle limit is met the discount will be removed from the subscription. type: - 'null' - integer required: - id - resource - title - target - value - recurringCycleLimit title: SubscriptionDiscount CustomerPaymentMethod: type: object properties: id: format: uuid type: string customer: description: >- Customer `id` when not expanded, or the full `Customer` object when the field name is included in the `expand` query parameter. anyOf: - minLength: 1 description: Customer ID (numeric string). examples: - '7654321' type: string - $ref: '#/components/schemas/Customer' instrument: anyOf: - type: object properties: type: type: string enum: - credit-card brand: minLength: 1 description: Credit card network name. type: string maskedNumber: minLength: 1 description: Masked card number. type: string required: - type - brand - maskedNumber - type: object properties: type: type: string enum: - paypal paypalAccountEmail: format: email description: Email of the associated PayPal account. type: - 'null' - string required: - type - paypalAccountEmail - type: object properties: type: type: string enum: - shop-pay maskedNumber: minLength: 1 description: Masked card number. type: string required: - type - maskedNumber - type: object properties: type: type: string enum: - sepa-direct-debit consumerName: minLength: 1 description: Full name of the account holder. type: string consumerBic: minLength: 1 description: BIC code. type: - 'null' - string maskedConsumerAccount: minLength: 1 description: Masked IBAN. type: string required: - type - consumerName - consumerBic - maskedConsumerAccount - type: object properties: type: type: string enum: - blik required: - type - type: object properties: type: type: string enum: - mbway phone: minLength: 1 type: string required: - type - type: object properties: type: type: string enum: - bacs maskedNumber: minLength: 1 description: Masked number. type: string required: - type - maskedNumber required: - id - customer title: CustomerPaymentMethod ProductVariant: type: object properties: id: minLength: 1 type: string title: minLength: 1 type: string image: oneOf: - type: 'null' - type: object properties: id: minLength: 1 type: string url: format: uri type: string altText: minLength: 1 type: - 'null' - string required: - id - url - altText price: type: number purchaseOptions: type: array items: type: object properties: name: minLength: 1 type: string price: type: number interval: type: object properties: intervalCount: type: number interval: type: string enum: - DAY - MONTH - WEEK - YEAR required: - intervalCount - interval required: - name - price - interval product: description: >- Product `id` when not expanded, or the full `Product` object when the field name is included in the `expand` query parameter. anyOf: - minLength: 1 type: string - $ref: '#/components/schemas/Product' planGroups: description: Subscription plan group IDs associated with this variant type: array items: minLength: 1 type: string required: - id - title - image - price - purchaseOptions - product - planGroups title: ProductVariant Product: type: object properties: id: minLength: 1 type: string title: minLength: 1 type: string image: oneOf: - type: 'null' - type: object properties: id: minLength: 1 type: string url: format: uri type: string altText: minLength: 1 type: - 'null' - string required: - id - url - altText collections: type: array items: type: object properties: handle: minLength: 1 type: string required: - handle planGroups: description: Subscription plan group IDs associated with this product type: array items: minLength: 1 type: string required: - id - title - image - collections - planGroups title: Product securitySchemes: AdminApiKey: type: apiKey name: X-Juo-Admin-Api-Key in: header description: >- Long-lived Admin API key issued from the Juo merchant portal. Pass as the `X-Juo-Admin-Api-Key` header. BearerToken: type: http scheme: bearer bearerFormat: JWT description: >- Short-lived JWT minted via the merchant browser-session flow. Carries the authenticated staff identity so that API calls are attributed to the specific staff user in the activity log. ````