> ## 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. # List subscriptions ## OpenAPI ````yaml GET /subscriptions/ 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 ` header. - `x-simple-workspace: ` 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/: get: tags: - Billing summary: List subscriptions parameters: - $ref: '#/components/parameters/WorkspaceHeader' - $ref: '#/components/parameters/TestModeHeader' - $ref: '#/components/parameters/PageQuery' - $ref: '#/components/parameters/PageSizeQuery' - $ref: '#/components/parameters/OrderingQuery' - name: customer in: query schema: type: string - name: status in: query schema: type: string enum: - active - paused - cancelled - finalized - needs_attention - name: next_billing in: query schema: type: string format: date - name: date_start in: query schema: type: string format: date - name: document in: query schema: type: integer - name: lines in: query schema: type: string description: Filter by linked line ID. - name: addons in: query schema: type: integer - name: coupon in: query schema: type: string - name: cancelled in: query schema: type: string format: date-time - name: cancel_reason in: query schema: type: string - name: paused in: query schema: type: string format: date-time - name: paused_reason in: query schema: type: string - name: needs_attention in: query schema: type: string format: date-time - name: needs_attention_reason in: query schema: type: string - name: instant in: query schema: type: boolean description: Compute on-the-fly billing for the response. responses: '200': description: Paginated subscription list. content: application/json: schema: allOf: - $ref: '#/components/schemas/Paginated' - type: object properties: results: type: array items: $ref: '#/components/schemas/Subscription' components: parameters: 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`. PageQuery: name: page in: query required: false schema: type: integer minimum: 1 default: 1 description: Page number to retrieve (1-indexed). PageSizeQuery: name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 20 description: Number of items per page. OrderingQuery: name: ordering in: query required: false schema: type: string description: | Field to sort results by. Prefix with `-` for descending order (e.g. `-created`). schemas: Paginated: type: object required: - count - results properties: count: type: integer description: Total number of items matching the filter. example: 142 next: type: string format: uri nullable: true description: URL of the next page, or `null` if last page. previous: type: string format: uri nullable: true description: URL of the previous page, or `null` if first page. results: type: array items: {} description: The items in the current page. 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 tokens are obtained from the Piriod dashboard. ````