> ## 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. # Atualizar assinatura > Atualize os campos editáveis de uma assinatura existente. Apenas `metadata`, `failure_policy` e `retry_offsets_days` são editáveis. Outros campos (intervalo, valor, moeda, cartão) são imutáveis — crie uma nova assinatura para alterá-los. Um webhook `subscription.updated` é disparado quando a assinatura é alterada. ## OpenAPI ````yaml api-reference/openapi-v2.json PATCH /v2/subscriptions/{id} 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/{id}: patch: tags: - API - Subscriptions summary: Patch Subscriptions By ID description: >- Update editable subscription fields (`metadata`, `failure_policy`, `retry_offsets_days`). Emits a `subscription.updated` webhook. operationId: patchSubscriptionsById parameters: - schema: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ in: path name: id required: true description: Public subscription id (UUID). requestBody: required: true content: application/json: schema: type: object properties: metadata: nullable: true type: object additionalProperties: {} failure_policy: type: string enum: - immediate_cancel - retry_then_cancel retry_offsets_days: minItems: 1 maxItems: 10 type: array items: type: integer minimum: 1 maximum: 30 responses: '200': description: Success 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 '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 '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`. ````