> ## Documentation Index > Fetch the complete documentation index at: https://developer.pagou.ai/llms.txt > Use this file to discover all available pages before exploring further. # List Subscriptions > List subscriptions with cursor pagination and filters. Cursor metadata (`next_cursor`, `prev_cursor`) is returned under `data.metadata`. Use `status` to filter by lifecycle state, `customer_email` to locate a specific subscriber, and `created_after` / `created_before` for date-range reconciliation. ## OpenAPI ````yaml api-reference/openapi-v2.json GET /v2/subscriptions openapi: 3.1.0 info: title: API PIX - v2 description: API for Pagou.ai Gateway version: 2.0.0 contact: name: Support url: https://pagou.ai email: support@pagou.ai servers: - url: https://api.pagou.ai description: Production server - url: https://api.sandbox.pagou.ai description: Sandbox server for testing security: - BearerAuth: [] - ApiKeyAuth: [] - BasicAuth: [] paths: /v2/subscriptions: get: tags: - API - Subscriptions summary: Get Subscriptions description: >- List subscriptions for the calling company using cursor pagination. Supports filtering by status, customer email, and creation date range. operationId: getSubscriptions parameters: - schema: type: string in: query name: cursor required: false - schema: default: 20 type: number minimum: 1 maximum: 100 in: query name: limit required: false - schema: default: next type: string enum: - next - prev in: query name: direction required: false - schema: type: string enum: - incomplete - trialing - active - past_due - cancel_scheduled - canceled in: query name: status required: false - schema: type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ in: query name: customer_email required: false - schema: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ in: query name: created_after required: false description: Filter to subscriptions created at or after this ISO 8601 timestamp. - schema: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ in: query name: created_before required: false description: >- Filter to subscriptions created at or before this ISO 8601 timestamp. responses: '200': description: Success content: application/json: schema: type: object properties: success: type: boolean requestId: type: string data: type: array items: type: object properties: id: type: string description: Public subscription id (UUID). customerId: type: string description: >- Public customer id (UUID) the subscription belongs to. status: type: string enum: - incomplete - trialing - active - past_due - cancel_scheduled - canceled description: Current subscription status. interval: type: string enum: - day - week - month description: Billing interval unit. intervalCount: type: integer minimum: 1 maximum: 365 description: Number of interval units per billing cycle. amount: type: integer minimum: 0 maximum: 100000000 description: Billing amount in cents. currency: type: string enum: - BRL - MXN - COP - CLP - ARS - PEN - USD - GTQ - CRC - NIO - PYG - UYU - BOB - PHP - RUB - INR - SAR - AED - KWD - QAR - OMR - KHR - SGD - IDR - KRW - THB - MYR - HKD - CNY - EGP - EUR - GBP - BHD - MAD - AUD - CAD - CHF - NZD - PLN - KZT - UZS - JPY - GLC description: Billing currency. trialEnd: nullable: true description: Trial end timestamp, when applicable. type: string format: date-time currentPeriodStart: description: Start of the current billing period. type: string format: date-time currentPeriodEnd: description: End of the current billing period. type: string format: date-time cancelAtPeriodEnd: type: boolean description: Whether cancellation is scheduled at period end. canceledAt: nullable: true description: Cancellation timestamp, when canceled. type: string format: date-time failurePolicy: type: string enum: - immediate_cancel - retry_then_cancel description: Behavior on a failed billing attempt. retryOffsetsDays: type: array items: type: integer minimum: 1 maximum: 30 description: Days after a failed attempt to retry. cancellationReason: nullable: true description: Reason for cancellation, when canceled. type: string enum: - user_requested - payment_failure - chargeback - system customerEmail: type: string description: Email of the subscriber. cardLast4: type: string description: Last four digits of the billing card. metadata: nullable: true description: Custom metadata. type: object additionalProperties: {} products: type: array items: type: object properties: name: type: string maxLength: 255 description: Catalog product name. price: type: integer minimum: 0 maximum: 100000000 description: Unit price in cents. quantity: type: integer minimum: 1 maximum: 999999 description: Quantity included in the subscription. tangible: type: boolean description: Whether the product is a tangible good. sku: description: Optional SKU. type: string maxLength: 255 required: - name - price - quantity - tangible additionalProperties: false description: Snapshot of catalog products billed each cycle. transactions: description: >- Transactions billed under this subscription. Included on GET by id. type: array items: type: object properties: id: type: string description: Public transaction id. status: type: string description: Transaction status. amount: type: integer minimum: 0 maximum: 100000000 description: Transaction amount in cents. paidAmount: type: integer minimum: 0 maximum: 100000000 description: Amount paid in cents. refundedAmount: type: integer minimum: 0 maximum: 100000000 description: Amount refunded in cents. currency: type: string enum: - BRL - MXN - COP - CLP - ARS - PEN - USD - GTQ - CRC - NIO - PYG - UYU - BOB - PHP - RUB - INR - SAR - AED - KWD - QAR - OMR - KHR - SGD - IDR - KRW - THB - MYR - HKD - CNY - EGP - EUR - GBP - BHD - MAD - AUD - CAD - CHF - NZD - PLN - KZT - UZS - JPY - GLC description: Transaction currency. externalRef: nullable: true description: External reference, when provided. type: string createdAt: description: Transaction creation timestamp. type: string format: date-time paidAt: nullable: true description: Payment confirmation timestamp. type: string format: date-time required: - id - status - amount - paidAmount - refundedAmount - currency - externalRef - createdAt - paidAt additionalProperties: false createdAt: description: Subscription creation timestamp. type: string format: date-time updatedAt: nullable: true description: Last update timestamp. type: string format: date-time required: - id - customerId - status - interval - intervalCount - amount - currency - trialEnd - currentPeriodStart - currentPeriodEnd - cancelAtPeriodEnd - canceledAt - failurePolicy - retryOffsetsDays - cancellationReason - customerEmail - cardLast4 - metadata - products - createdAt - updatedAt additionalProperties: false next_cursor: nullable: true type: string prev_cursor: nullable: true type: string total: type: integer minimum: 0 maximum: 9007199254740991 required: - success - requestId - data - next_cursor - prev_cursor - total additionalProperties: false '422': description: Validation error (RFC 7807) content: application/problem+json: schema: $ref: '#/components/schemas/ValidationProblemDetails' default: description: RFC 7807 Problem Details error response content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' security: - BearerAuth: [] - ApiKeyAuth: [] - BasicAuth: [] components: schemas: ValidationProblemDetails: allOf: - $ref: '#/components/schemas/ProblemDetails' - type: object properties: errors: type: array items: type: object properties: field: type: string message: type: string code: type: string additionalProperties: true additionalProperties: true ProblemDetails: type: object description: RFC 7807 Problem Details object. properties: type: type: string format: uri-reference title: type: string status: type: number detail: type: string instance: type: string format: uri-reference required: - type - title - status - detail additionalProperties: true securitySchemes: BearerAuth: type: http scheme: bearer ApiKeyAuth: type: apiKey in: header name: apiKey BasicAuth: type: http scheme: basic description: Use Basic auth with username `token` and password `x`. ````