> ## Documentation Index
> Fetch the complete documentation index at: https://www.commercengine.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Update a specific subscription

> Update a specific subscription



## OpenAPI

````yaml put /subscriptions/{id}
openapi: 3.1.0
info:
  version: '1.0'
  title: CE Storefront APIs
  summary: Customer-facing e-commerce API for building exceptional shopping experiences
  description: >-
    Public-facing API for Commerce Engine storefronts, enabling seamless
    shopping experiences with product browsing, cart management, checkout
    processing, user accounts, and order tracking. Perfect for building web,
    mobile, and headless commerce applications.
  contact:
    name: Support
    email: support@commercengine.io
    url: https://www.commercengine.io/contact-us
  license:
    url: https://www.commercengine.io/contact-us
    name: All Rights Reserved
servers:
  - url: https://staging.api.commercengine.io/api/v1/{store_id}/storefront
    description: Staging Server
    variables:
      store_id:
        description: Store ID
        default: store_id
    x-speakeasy-server-id: staging
  - url: https://prod.api.commercengine.io/api/v1/{store_id}/storefront
    description: Prod Server
    variables:
      store_id:
        description: Store ID
        default: store_id
    x-speakeasy-server-id: prod
security: []
tags:
  - name: Analytics
    description: Analytics
  - name: Auth
    description: auth
  - name: Campaigns
    description: Campaigns
  - name: Carts
    description: Carts
  - name: Catalog
    description: Catalog
  - name: Common
    description: Common
  - name: Coupons & promotions
    description: Coupons & promotions
  - name: Customers
    description: Customers
  - name: Juspay
    description: Juspay Payments
  - name: KYC
    description: KYC
  - name: Marketplace
    description: Marketplace
  - name: Orders
    description: Orders
  - name: Others
    description: Others
  - name: Payments
    description: Payments
  - name: PayU
    description: PayU Payments
  - name: POS
    description: POS
  - name: Shipping
    description: Shipping
  - name: Store
    description: Store
  - name: Subscriptions
    description: Subscriptions
externalDocs:
  url: https://llm-docs.commercengine.io
  description: Commerce Engine API Reference Documentation
paths:
  /subscriptions/{id}:
    parameters:
      - name: id
        in: path
        description: subscription id
        required: true
        schema:
          type: string
    put:
      tags:
        - Subscriptions
      summary: Update a specific subscription
      description: Update a specific subscription
      operationId: update-subscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/UpdatePhysicalProductSubscription'
                - $ref: '#/components/schemas/UpdateDigitalProductSubscription'
                - $ref: '#/components/schemas/PauseSubscription'
                - $ref: '#/components/schemas/RevokeSubscription'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - success
                  - content
                properties:
                  message:
                    type: string
                  success:
                    type: boolean
                  content:
                    properties:
                      subscription:
                        $ref: '#/components/schemas/SubscriptionDetail'
                    required:
                      - subscription
                    type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      externalDocs:
        url: >-
          https://llm-docs.commercengine.io/storefront/operations/update-subscription
        description: API reference for the update-subscription operation
components:
  schemas:
    UpdatePhysicalProductSubscription:
      title: UpdatePhysicalProductSubscription
      externalDocs:
        url: >-
          https://llm-docs.commercengine.io/storefront/schemas/UpdatePhysicalProductSubscription
        description: API reference for the UpdatePhysicalProductSubscription schema
      allOf:
        - type: object
          required:
            - command
          properties:
            command:
              type: string
              const: update
            billing_frequency:
              enum:
                - monthly
            billing_interval:
              type: integer
              default: 1
            billing_limit:
              description: >-
                null means there is no limit on number of invoices generated. If
                specified, then subscription will be revoked automatically after
                billing limit is reached.
              type:
                - integer
                - 'null'
            shipping_frequency:
              enum:
                - monthly
            shipping_interval:
              type: integer
              default: 1
            shipping_limit:
              description: >-
                null means there is no limit on number of deliveries completed.
                If specified, then subscription will be revoked automatically
                after shipping limit is reached.
              type:
                - integer
                - 'null'
        - $ref: '#/components/schemas/SubscriptionBehaviour'
        - type: object
          properties:
            invoice_items:
              type: array
              items:
                $ref: '#/components/schemas/SubscriptionInvoiceItem'
      x-tags:
        - Subscriptions
    UpdateDigitalProductSubscription:
      title: UpdateDigitalProductSubscription
      externalDocs:
        url: >-
          https://llm-docs.commercengine.io/storefront/schemas/UpdateDigitalProductSubscription
        description: API reference for the UpdateDigitalProductSubscription schema
      allOf:
        - type: object
          required:
            - command
          properties:
            command:
              type: string
              const: update
            billing_frequency:
              enum:
                - monthly
            billing_interval:
              type: integer
              default: 1
            billing_limit:
              description: >-
                null means there is no limit on number of invoices generated. If
                specified, then subscription will be revoked automatically after
                billing limit is reached.
              type:
                - integer
                - 'null'
        - $ref: '#/components/schemas/SubscriptionBehaviour'
        - type: object
          properties:
            invoice_items:
              type: array
              items:
                $ref: '#/components/schemas/SubscriptionInvoiceItem'
      x-tags:
        - Subscriptions
    PauseSubscription:
      title: PauseSubscription
      type: object
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/PauseSubscription
        description: API reference for the PauseSubscription schema
      required:
        - command
      properties:
        command:
          description: To pause an active subscription.
          type: string
          const: pause
        pause_start_date:
          description: >-
            optional. if specified, subscription will be paused from this date &
            time. If not specified, subscription will be paused immediately.
            datetime value should be greater than current time.
          type: string
          format: date-time
        pause_end_date:
          description: >-
            optional. if specified, subscription will be activated automatically
            from this date & time. If not specified, subscription will remain
            paused. datetime value should be greater than current time.
          type: string
          format: date-time
      x-tags:
        - Subscriptions
    RevokeSubscription:
      title: RevokeSubscription
      type: object
      externalDocs:
        url: >-
          https://llm-docs.commercengine.io/storefront/schemas/RevokeSubscription
        description: API reference for the RevokeSubscription schema
      required:
        - command
        - reason
      properties:
        command:
          description: To revoke a subscription.
          type: string
          const: revoke
        reason:
          description: Provide reason for revoking subscription.
          type: string
      x-tags:
        - Subscriptions
    SubscriptionDetail:
      title: SubscriptionDetail
      externalDocs:
        url: >-
          https://llm-docs.commercengine.io/storefront/schemas/SubscriptionDetail
        description: API reference for the SubscriptionDetail schema
      allOf:
        - $ref: '#/components/schemas/Subscription'
        - type: object
          properties:
            invoice_items:
              type: array
              items:
                $ref: '#/components/schemas/SubscriptionInvoiceItem'
            billing_address:
              $ref: '#/components/schemas/CustomerAddress'
            shipping_address:
              $ref: '#/components/schemas/CustomerAddress'
      x-tags:
        - Subscriptions
    SubscriptionBehaviour:
      title: SubscriptionBehaviour
      type: object
      externalDocs:
        url: >-
          https://llm-docs.commercengine.io/storefront/schemas/SubscriptionBehaviour
        description: API reference for the SubscriptionBehaviour schema
      properties:
        is_prepaid:
          description: >-
            Refers to a pricing model where customers are charged based on their
            actual usage of a service. Usage based billing works for digital
            products.
          type: boolean
          default: false
        usage_based_billing:
          description: >-
            Refers to a pricing model where customers are charged based on their
            actual usage of a service. Usage based billing works for digital
            products.
          type: boolean
          default: false
        usage_based_tiers:
          description: >-
            Refers to a pricing structure where customers are charged based on
            their usage, but the cost per unit of usage decreases or changes as
            they move into higher usage levels.
          type: array
          items:
            type: object
            properties:
              up_to:
                type: integer
              price_per_unit:
                type: number
                format: double
        grace_period_days:
          description: The number of days after a failed payment to retry before canceling.
          type: integer
          default: 0
        is_cancellation_allowed:
          description: Indcates whether the next billing cancellation is allowed or not.
          type: boolean
          default: true
        days_until_cancellation_allowed:
          description: >-
            Specifies the number of days the customer has to cancel before the
            next billing.
          type: integer
          default: 3
      x-tags:
        - Subscriptions
    SubscriptionInvoiceItem:
      title: SubscriptionInvoiceItem
      type: object
      externalDocs:
        url: >-
          https://llm-docs.commercengine.io/storefront/schemas/SubscriptionInvoiceItem
        description: API reference for the SubscriptionInvoiceItem schema
      required:
        - product_id
        - variant_id
        - product_name
        - variant_name
        - product_image_url
        - sku
        - quantity
        - listing_price
        - selling_price
        - tax_type
        - tax_rate
        - price_including_tax
        - selling_price_excluding_tax
      properties:
        product_id:
          type: string
        variant_id:
          type:
            - string
            - 'null'
        product_name:
          type: string
          readOnly: true
        variant_name:
          type: string
          readOnly: true
        product_image_url:
          type: string
          readOnly: true
        sku:
          type: string
          readOnly: true
        quantity:
          type: integer
        listing_price:
          type: number
          format: double
          readOnly: true
        selling_price:
          type: number
          format: double
          readOnly: true
        tax_type:
          type: string
          const: GST
          readOnly: true
        tax_rate:
          type: number
          format: double
          readOnly: true
        price_including_tax:
          type: boolean
          readOnly: true
        selling_price_excluding_tax:
          type: number
          format: double
          readOnly: true
      x-tags:
        - Subscriptions
    Subscription:
      title: Subscription
      type: object
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/Subscription
        description: API reference for the Subscription schema
      required:
        - id
        - plan_id
        - plan_name
        - price
        - status
        - start_date
        - end_date
        - trial_days
        - trial_start_date
        - trial_end_date
        - next_billing_date
        - last_payment_date
        - pause_start_date
        - pause_end_date
        - billing_frequency
        - billing_interval
        - billing_limit
        - shipping_frequency
        - shipping_interval
        - shipping_limit
        - coupon_id
        - coupon_code
        - coupon_discount_percent
        - coupon_discount_amount
        - coupon_redemption_limit
        - is_prepaid
        - usage_based_billing
        - usage_based_tiers
        - grace_period_days
        - is_cancellation_allowed
        - days_until_cancellation_allowed
        - currency
        - metadata
        - created_at
        - modified_at
      properties:
        id:
          type: string
          readOnly: true
        plan_id:
          type: string
          readOnly: true
        plan_name:
          type: string
          readOnly: true
        price:
          description: >-
            The subscription price is the amount a customer is required to pay
            over a specified period (e.g., monthly, annually). This price may
            vary based on the plan selected or based on usage of services.
          type: number
          format: double
        status:
          enum:
            - created
            - active
            - paused
            - revoked
          readOnly: true
        start_date:
          type: string
          format: date
        end_date:
          description: if specified, subscrition will be revoked on this date.
          type:
            - string
            - 'null'
          format: date
        trial_days:
          description: If specified, payment will be charged after trial days completed.
          type: integer
          default: 0
        trial_start_date:
          type:
            - string
            - 'null'
          format: date
          readOnly: true
        trial_end_date:
          type:
            - string
            - 'null'
          format: date
          readOnly: true
        next_billing_date:
          type: string
          format: date
          readOnly: true
        last_payment_date:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
        pause_start_date:
          type:
            - string
            - 'null'
          format: date
        pause_end_date:
          type:
            - string
            - 'null'
          format: date
        billing_frequency:
          enum:
            - monthly
        billing_interval:
          description: >-
            Frequency unit multiplier. For example, `1` with `monthly` means
            every month; `3` with `weekly` means in every 3 weeks.
          type: integer
          default: 1
        billing_limit:
          type:
            - integer
            - 'null'
        shipping_frequency:
          enum:
            - monthly
        shipping_interval:
          description: >-
            Frequency unit multiplier. For example, `1` with `monthly` means
            every month; `3` with `weekly` means in every 3 weeks.
          type: integer
          default: 1
        shipping_limit:
          type:
            - integer
            - 'null'
        coupon_id:
          type:
            - string
            - 'null'
        coupon_code:
          type:
            - string
            - 'null'
        coupon_discount_percent:
          type: number
          default: 0
        coupon_discount_amount:
          type: number
          default: 0
        coupon_redemption_limit:
          description: >-
            Indicates how many times a coupon can be redeemed within the
            subscription.
          type:
            - integer
            - 'null'
          default: 0
        is_prepaid:
          description: >-
            Indicates whether the subscription is paid in advance. When set to
            true, the subscription requires the customer to pay for the entire
            billing period upfront. When set to false, the subscription may
            operate on a pay-as-you-go or post-paid model, where charges are
            billed after the service is provided.
          type: boolean
          default: false
        usage_based_billing:
          description: >-
            Refers to a pricing model where customers are charged based on their
            actual usage of a service. Usage based billing works for digital
            products.
          type: boolean
        usage_based_tiers:
          description: >-
            Refers to a pricing structure where customers are charged based on
            their usage, but the cost per unit of usage decreases or changes as
            they move into higher usage levels.
          type: array
          items:
            type: object
            required:
              - up_to
              - price_per_unit
            properties:
              up_to:
                type: integer
              price_per_unit:
                type: number
                format: double
        grace_period_days:
          description: The number of days after a failed payment to retry before canceling.
          type: integer
          default: 0
        is_cancellation_allowed:
          description: Indcates whether the next billing cancellation is allowed or not.
          type: boolean
          default: true
        days_until_cancellation_allowed:
          description: >-
            Specifies the number of days the customer has to cancel before the
            next billing.
          type: integer
          default: 3
        currency:
          $ref: '#/components/schemas/Currency'
          description: >-
            Details about the currency being used, including `name`, `code`, and
            `symbol`.
        metadata:
          type: object
          additionalProperties:
            type: string
        created_at:
          type: string
          format: date-time
        modified_at:
          type: string
          format: date-time
      x-tags:
        - Subscriptions
    CustomerAddress:
      title: CustomerAddress
      type:
        - object
        - 'null'
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/CustomerAddress
        description: API reference for the CustomerAddress schema
      required:
        - first_name
        - last_name
        - country_code
        - phone
        - email
        - address_line1
        - address_line2
        - landmark
        - pincode
        - city
        - state
        - country
        - tax_identification_number
        - business_name
        - is_phone_verified
        - is_email_verified
      properties:
        id:
          type:
            - string
            - 'null'
          pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$
          readOnly: true
        first_name:
          type: string
        last_name:
          type:
            - string
            - 'null'
        country_code:
          description: "Two-letter code begin with a plus sign prefix that identifies different countries. By default it will be +91 if not provided.\r\n"
          type: string
        phone:
          description: 10 digit phone number without country code.
          type: string
        email:
          type: string
        address_line1:
          type: string
        address_line2:
          type:
            - string
            - 'null'
        landmark:
          type:
            - string
            - 'null'
        pincode:
          type: string
        city:
          type: string
        state:
          type: string
        country:
          type: string
          const: India
        tax_identification_number:
          description: Tax Identification Number specific to the country of operation.
          type:
            - string
            - 'null'
          examples: []
        business_name:
          description: Use in billing & shipping details only.
          type:
            - string
            - 'null'
        is_default_billing:
          description: >-
            Indicates if the address is the default billing address for the
            customer.
          type: boolean
        is_default_shipping:
          description: >-
            Indicates if the address is the default shipping address for the
            customer.
          type: boolean
        is_phone_verified:
          type: boolean
          readOnly: true
        is_email_verified:
          type: boolean
          readOnly: true
        nickname:
          description: Nickname for the address.
          type:
            - string
            - 'null'
          default: null
      examples: []
    Currency:
      type: object
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/Currency
        description: API reference for the Currency schema
      required:
        - name
        - code
        - symbol
      properties:
        name:
          type: string
          examples:
            - Indian Rupee
        code:
          type: string
          examples:
            - INR
          maxLength: 3
          minLength: 3
        symbol:
          type: string
          examples:
            - ₹
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            type: object
            required:
              - message
              - success
              - code
            properties:
              message:
                type: string
                x-speakeasy-error-message: true
              success:
                type: boolean
              code:
                type: string
              error:
                type: object
    Unauthorized:
      description: Not authorized for given operation on the Resource
      content:
        application/json:
          schema:
            type: object
            required:
              - message
              - success
              - code
            properties:
              message:
                type: string
                examples:
                  - Not authorized for given operation on the Resource.
                x-speakeasy-error-message: true
              success:
                type: boolean
                default: false
              code:
                type: string
                examples:
                  - unauthorized
    NotFound:
      description: Requested resource not found
      content:
        application/json:
          schema:
            type: object
            required:
              - message
              - success
              - code
            properties:
              message:
                type: string
                x-speakeasy-error-message: true
              success:
                type: boolean
              code:
                type: string

````