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

# Partial update subscription



## OpenAPI

````yaml PATCH /subscriptions/{id}/
openapi: 3.0.3
info:
  title: Piriod API
  version: 1.0.0
  description: >
    Piriod API for billing, payments, procurement and collections.


    All requests require:

    - `Authorization: Token <api_token>` header.

    - `x-simple-workspace: <workspace_id>` header (the account/workspace
    identifier).

    - Optionally `x-piriod-test-mode: true` to operate against test-mode data.


    See the Documentation tab for getting started, integration flows,
    authentication,

    error handling and pagination/filtering guides.
servers:
  - url: https://api.piriod.com
    description: Production
security:
  - TokenAuth: []
paths:
  /subscriptions/{id}/:
    parameters:
      - $ref: '#/components/parameters/IdPath'
      - $ref: '#/components/parameters/WorkspaceHeader'
      - $ref: '#/components/parameters/TestModeHeader'
    patch:
      tags:
        - Billing
      summary: Partial update subscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Subscription'
      responses:
        '200':
          description: Updated subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
components:
  parameters:
    IdPath:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Resource identifier.
    WorkspaceHeader:
      name: x-simple-workspace
      in: header
      required: true
      schema:
        type: string
      description: Workspace (account) identifier. Required for every request.
      example: acc_01H8XYZ123ABC
    TestModeHeader:
      name: x-piriod-test-mode
      in: header
      required: false
      schema:
        type: boolean
        default: false
      description: Whether to operate against test-mode data. Defaults to `false`.
  schemas:
    Subscription:
      type: object
      properties:
        id:
          type: string
          readOnly: true
        customer:
          type: string
          description: Customer ID.
        document:
          type: integer
          description: Document type ID used to issue invoices.
        date_start:
          type: string
          format: date
        next_billing:
          type: string
          format: date
        previous_billing:
          type: string
          format: date
          nullable: true
        billing_cycles:
          type: integer
          nullable: true
          description: Total cycles or null for indefinite.
        next_billing_cycle:
          type: integer
          default: 1
          readOnly: true
        expiration_days:
          type: integer
          default: 10
          description: Days until invoices generated by this subscription expire.
        collection_scheme:
          type: string
          enum:
            - send_invoice
            - charge_payment
          default: send_invoice
        default_source:
          type: string
          nullable: true
          description: >-
            Default payment source ID. Required when
            `collection_scheme=charge_payment`.
        custom_change:
          type: number
          minimum: 1
          nullable: true
          description: Custom currency conversion factor for issued invoices.
        coupon:
          type: string
          nullable: true
          description: Coupon ID applied at the subscription (invoice-level) scope.
        coupon_redemptions:
          type: integer
          readOnly: true
        require_reference:
          type: boolean
          default: false
        note:
          type: string
          maxLength: 100
          nullable: true
        orgunit:
          type: integer
          nullable: true
        status:
          type: string
          enum:
            - active
            - paused
            - cancelled
            - finalized
            - needs_attention
          readOnly: true
        status_description:
          type: string
          maxLength: 512
          nullable: true
        needs_attention:
          type: string
          format: date-time
          nullable: true
          readOnly: true
        needs_attention_reason:
          type: string
          enum:
            - biller_issue
            - gateway_issue
            - reference_expired
            - without_usage_records
            - processing_issue
            - without_reference
          nullable: true
          readOnly: true
        cancel_reason:
          type: string
          enum:
            - custom
            - fraud_review_failed
            - insolvency
            - no_card
            - non_compliant_customer
            - not_paid
            - not_specified
            - shutdown_ops
          nullable: true
          readOnly: true
        cancelled:
          type: string
          format: date-time
          nullable: true
          readOnly: true
        paused:
          type: string
          format: date-time
          nullable: true
          readOnly: true
        paused_reason:
          type: string
          enum:
            - not_specified
            - non_compliant_customer
            - custom
          nullable: true
          readOnly: true
        pause_until:
          type: string
          format: date
          nullable: true
          readOnly: true
        lines:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionLine'
        addons:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionAddon'
        references:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionReference'
        test_mode:
          type: boolean
          readOnly: true
        created:
          type: string
          format: date-time
          readOnly: true
        updated:
          type: string
          format: date-time
          readOnly: true
      required:
        - customer
        - document
        - date_start
        - next_billing
        - lines
    SubscriptionLine:
      type: object
      properties:
        id:
          type: string
          readOnly: true
        plan:
          type: string
          description: Plan ID. Read responses include the full plan inline.
        quantity:
          type: integer
          minimum: 1
        coupon:
          type: string
          nullable: true
          description: Coupon ID applied to this line.
        coupon_redemptions:
          type: integer
          readOnly: true
        created:
          type: string
          format: date-time
          readOnly: true
        updated:
          type: string
          format: date-time
          readOnly: true
      required:
        - plan
        - quantity
    SubscriptionAddon:
      type: object
      properties:
        addon:
          type: string
          description: Addon ID.
        quantity:
          type: integer
          minimum: 1
        addon_redemptions:
          type: integer
          readOnly: true
        rates:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionAddonRate'
    SubscriptionReference:
      type: object
      properties:
        date:
          type: string
          format: date
        date_end:
          type: string
          format: date
          nullable: true
        document:
          type: string
          description: Document reference type.
        description:
          type: string
          nullable: true
        serial:
          type: string
      required:
        - date
        - document
        - serial
    SubscriptionAddonRate:
      type: object
      properties:
        billing_cycle:
          type: integer
          description: Billing cycle this rate applies to.
        percentage:
          type: number
          description: Discount/markup percentage applied to the addon for the cycle.
        description:
          type: string
          nullable: true
  securitySchemes:
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: |
        Use header `Authorization: Token <api_token>`.
        API tokens are obtained from the Piriod dashboard.

````