> ## 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. # Criar assinatura > Crie uma assinatura recorrente a partir de um token de cartão de uso único. ## Pré-requisitos 1. Crie o cliente com [`POST /v2/customers`](/pt/api-reference/customers/create) — a resposta inclui o `customer_id` (UUID) que você passa abaixo. 2. Tokenize o cartão pelo fluxo seguro do Payment Element — isso retorna um token de pagamento `pgct_` de uso único. Assinaturas não criam clientes automaticamente a partir do corpo da requisição; um `customer_id` desconhecido retorna `404`. ## Comportamento `customer_id` é o identificador público (UUID) do cliente retornado por `POST /v2/customers`. `token` precisa ser um token `pgct_` de uso único. Quando `trial_end` é informado, podemos cobrar um valor pequeno e estorná-lo para validar o meio de pagamento, e a assinatura é criada com status `trialing` até o teste expirar. Sem `trial_end`, a assinatura é criada com status `active` após o primeiro charge bem-sucedido. `amount` está em centavos e é usado também para cobrar cada ciclo de renovação. ## OpenAPI ````yaml api-reference/openapi-v2.json POST /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: post: tags: - API - Subscriptions summary: Post Subscriptions description: >- Create a new subscription. Charges the supplied `pgct_` card token; the subscription is created with status `active`, or `trialing` when `trial_end` is set. operationId: postSubscriptions requestBody: required: true content: application/json: schema: oneOf: - type: object properties: customer_id: type: string minLength: 1 description: >- Public customer id (UUID) returned by `POST /v2/customers`. interval: type: string enum: - day - week - month interval_count: default: 1 type: integer minimum: 1 maximum: 365 failure_policy: default: retry_then_cancel type: string enum: - immediate_cancel - retry_then_cancel retry_offsets_days: minItems: 1 maxItems: 10 type: array items: type: integer minimum: 1 maximum: 30 amount: type: integer minimum: 0 exclusiveMinimum: true maximum: 100000000 description: Billing amount in cents (max 100,000,000). currency: default: BRL 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 metadata: nullable: true type: object additionalProperties: {} idempotency_key: nullable: true type: string minLength: 1 maxLength: 255 products: maxItems: 100 type: array items: type: object properties: name: type: string minLength: 1 maxLength: 255 price: type: integer minimum: 0 maximum: 100000000 quantity: default: 1 type: integer minimum: 1 maximum: 999999 tangible: default: false type: boolean sku: type: string maxLength: 255 required: - name - price payment_method: default: credit_card type: string enum: - credit_card token: type: string minLength: 6 trial_end: description: Trial end timestamp (ISO 8601). Must be in the future. nullable: true 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)))$ required: - customer_id - interval - amount - token - type: object properties: customer_id: type: string minLength: 1 description: >- Public customer id (UUID) returned by `POST /v2/customers`. interval: type: string enum: - day - week - month interval_count: default: 1 type: integer minimum: 1 maximum: 365 failure_policy: default: retry_then_cancel type: string enum: - immediate_cancel - retry_then_cancel retry_offsets_days: minItems: 1 maxItems: 10 type: array items: type: integer minimum: 1 maximum: 30 amount: type: integer minimum: 0 exclusiveMinimum: true maximum: 100000000 description: Billing amount in cents (max 100,000,000). currency: default: BRL 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 metadata: nullable: true type: object additionalProperties: {} idempotency_key: nullable: true type: string minLength: 1 maxLength: 255 products: maxItems: 100 type: array items: type: object properties: name: type: string minLength: 1 maxLength: 255 price: type: integer minimum: 0 maximum: 100000000 quantity: default: 1 type: integer minimum: 1 maximum: 999999 tangible: default: false type: boolean sku: type: string maxLength: 255 required: - name - price payment_method: type: string enum: - pix_automatic billing_day_of_month: type: integer minimum: 1 maximum: 31 comment: type: string maxLength: 140 trial_end: description: >- Trial end (ISO 8601). Future date triggers Jornada 2 (authorization only). nullable: true 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)))$ required: - customer_id - interval - amount - payment_method additionalProperties: false responses: '201': description: HTTP 201 response content: application/json: schema: type: object properties: success: type: boolean requestId: type: string data: 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 required: - success - requestId - data additionalProperties: false '403': description: HTTP 403 response content: application/json: schema: type: object properties: error: type: string message: type: string status: type: number enum: - 403 required: - error - message - status additionalProperties: false '404': description: HTTP 404 response content: application/json: schema: type: object properties: error: type: string message: type: string status: type: number enum: - 404 required: - error - message - status additionalProperties: false '409': description: HTTP 409 response content: application/json: schema: type: object properties: error: type: string message: type: string status: type: number enum: - 409 required: - error - message - status additionalProperties: false '422': description: HTTP 422 response content: application/json: schema: type: object properties: error: type: string message: type: string status: type: number enum: - 422 required: - error - message - status additionalProperties: false 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`. ````