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

# Alterar data da próxima cobrança

> Altera a data da próxima cobrança, a partir de amanhã. O calendário inteiro se move: as faturas seguintes passam a contar a partir da nova data. Só é possível em uma assinatura ativa ou agendada e sem fatura em andamento.


<Info>
  Envie `next_billing_at` com uma data **a partir de amanhã**. Só o dia é considerado. Uma data de hoje ou do passado retorna `422` (`validation_error`).
</Info>

<Warning>
  A alteração move **todo o calendário** da assinatura: as faturas seguintes passam a ser contadas a partir da nova data, somando o intervalo da assinatura. O `start_at` da resposta continua mostrando o início original.
</Warning>

<Note>
  A assinatura precisa estar em andamento (`scheduled` ou `active`) e **sem fatura em andamento** (pendente, autorizada ou aguardando ação). Em qualquer outro caso, incluindo `past_due` e `suspended`, a resposta é `422` (`billing_date_not_updatable`).
</Note>


## OpenAPI

````yaml POST /v2/subscriptions/{id}/next-billing-date
openapi: 3.1.0
info:
  title: 4Selet Pay API
  description: >
    API de processamento de pagamentos da plataforma 4Selet Pay. Suporta
    cobranças únicas, assinaturas recorrentes, PIX, Cartão de Crédito. Todas as
    rotas autenticadas requerem um Bearer Token obtido via `/v1/login`.
  version: 1.0.0
  contact:
    name: 4Selet Pay
    email: suporte@4selet.com.br
servers:
  - url: https://sandbox.4seletpay.com.br/api
    description: Servidor de Sandbox
security:
  - bearerAuth: []
tags:
  - name: Autenticação
    description: Rotas de autenticação e criação de usuários
  - name: Cobranças
    description: Criação, consulta, cancelamento e reembolso de cobranças
  - name: Pedidos
    description: Consulta de pedidos e gerenciamento de confirmações desafiadas
  - name: Cartões
    description: Cadastro e gerenciamento dos cartões salvos de um cliente
  - name: Assinaturas
    description: Criação e gerenciamento de assinaturas recorrentes
  - name: Faturas
    description: Gerenciamento de faturas e pagamento de faturas em atraso
  - name: Clientes Bloqueados
    description: Gerenciamento de lista negra de clientes
  - name: Contas
    description: Criação e gerenciamento de contas na plataforma
  - name: Aplicativo
    description: Endpoints para dashboard e uso via aplicativo mobile
  - name: Notificações Push
    description: Envio e gerenciamento de notificações push
  - name: Utilitários
    description: Endpoints utilitários como listagem de fusos horários
  - name: Gestão
    description: Relatórios gerenciais (acesso restrito a Super Admins)
  - name: Webhooks
    description: Endpoints para receber notificações de gateways de pagamento
  - name: Endpoints de Webhook
    description: >-
      Gerenciamento de endpoints de webhook para receber notificações de eventos
      da plataforma
  - name: Links de Pagamento
    description: Criação e gerenciamento de links de pagamento com checkout pré-configurado
  - name: Análise de Fraude
    description: >-
      API de Risco — consulta o risco de fraude de uma transação (autenticada
      por chave de API)
  - name: Pedidos (v2)
    description: >-
      API v2 — pedidos com um ou mais meios de pagamento, captura, cancelamento
      e verificação por código
  - name: Cobranças (v2)
    description: API v2 — consulta e estorno de cobranças
  - name: Cartões (v2)
    description: API v2 — cadastro e consulta de cartões salvos
  - name: Assinaturas (v2)
    description: API v2 — criação e gerenciamento de assinaturas recorrentes
  - name: Faturas (v2)
    description: >-
      API v2 — consulta, pagamento e verificação por código das faturas de
      assinaturas
paths:
  /v2/subscriptions/{id}/next-billing-date:
    post:
      tags:
        - Assinaturas (v2)
      summary: Alterar data da próxima cobrança
      description: >
        Altera a data da próxima cobrança, a partir de amanhã. O calendário
        inteiro se move: as faturas seguintes passam a contar a partir da nova
        data. Só é possível em uma assinatura ativa ou agendada e sem fatura em
        andamento.
      operationId: v2UpdateSubscriptionNextBillingDate
      parameters:
        - $ref: '#/components/parameters/V2Id'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2ChangeNextBillingDateRequest'
      responses:
        '200':
          description: Data alterada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Subscription'
        '400':
          $ref: '#/components/responses/V2IdempotencyInvalid'
        '401':
          $ref: '#/components/responses/V2Unauthorized'
        '403':
          $ref: '#/components/responses/V2AccountBlocked'
        '404':
          $ref: '#/components/responses/V2SubscriptionNotFound'
        '409':
          $ref: '#/components/responses/V2IdempotencyInUse'
        '422':
          description: Data inválida ou assinatura que não permite a alteração agora
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
              examples:
                validation_error:
                  summary: Data não enviada
                  value:
                    error:
                      type: invalid_request_error
                      code: validation_error
                      message: The next billing at field is required.
                      param: next_billing_at
                billing_date_not_updatable:
                  summary: Assinatura não ativa ou com fatura em andamento
                  value:
                    error:
                      type: invalid_request_error
                      code: billing_date_not_updatable
                      message: >-
                        A data da próxima cobrança só pode ser alterada em uma
                        assinatura ativa e sem fatura em andamento.
                idempotency_key_conflict:
                  summary: Idempotency-Key usada com outro corpo
                  value:
                    error:
                      type: idempotency_error
                      code: idempotency_key_conflict
                      message: >-
                        The Idempotency-Key has already been used with a
                        different request body.
        '429':
          $ref: '#/components/responses/V2ThrottleExceeded'
        '500':
          $ref: '#/components/responses/V2ServerError'
      security:
        - secretKeyAuth: []
components:
  parameters:
    V2Id:
      name: id
      in: path
      required: true
      description: Identificador do recurso (o campo `id` devolvido pela API)
      schema:
        type: string
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >
        Chave de idempotência opcional e recomendada. Tem até 128 caracteres e
        vale por 24 horas, por conta. A mesma chave com o mesmo corpo devolve a
        resposta original (mesmo status e mesmo corpo), sem processar de novo.
        Só respostas 2xx ficam guardadas: depois de um erro, a mesma chave pode
        ser reutilizada. A mesma chave com um corpo diferente retorna 422
        (`idempotency_key_conflict`), uma requisição original ainda em andamento
        retorna 409 (`idempotency_key_in_use`) e uma chave com mais de 128
        caracteres retorna 400 (`idempotency_key_invalid`).
      schema:
        type: string
        maxLength: 128
        example: pedido-1024-tentativa-1
  schemas:
    V2ChangeNextBillingDateRequest:
      type: object
      required:
        - next_billing_at
      properties:
        next_billing_at:
          type: string
          format: date
          description: >-
            Nova data da próxima cobrança, a partir de amanhã. O horário é
            descartado
          example: '2026-10-01'
    V2Subscription:
      type: object
      description: >
        Assinatura. `incomplete`: a primeira fatura ainda não foi paga.
        `incomplete_expired`: a primeira fatura foi recusada. `scheduled`: a
        primeira cobrança está agendada (`start_at`). `active`: em dia.
        `past_due`: fatura em atraso. `suspended`: suspensa. `canceled`:
        cancelada. `completed`: todas as faturas previstas foram pagas.
      properties:
        id:
          type: string
          example: sub_4Hn8Qw2Rt6Yp1Zx3
        object:
          type: string
          enum:
            - subscription
        code:
          type: string
          nullable: true
          example: plano-anual-123
        status:
          type: string
          enum:
            - incomplete
            - incomplete_expired
            - scheduled
            - active
            - past_due
            - suspended
            - canceled
            - completed
        currency:
          type: string
          example: brl
        description:
          type: string
          nullable: true
        interval:
          type: string
          enum:
            - day
            - week
        interval_count:
          type: integer
        billing_type:
          type: string
          enum:
            - prepaid
        amount:
          type: integer
          description: Total dos itens, em centavos, sem descontos ou acréscimos
        items:
          type: array
          items:
            $ref: '#/components/schemas/V2SubscriptionItem'
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/V2SubscriptionAdjustment'
        increments:
          type: array
          items:
            $ref: '#/components/schemas/V2SubscriptionAdjustment'
        max_invoices:
          type: integer
          nullable: true
        invoices_paid:
          type: integer
          description: Quantidade de faturas pagas
        minimum_price:
          type: integer
          nullable: true
          description: Aceito e devolvido pela API, mas ainda não é aplicado na cobrança
        payment_method:
          type: object
          properties:
            type:
              type: string
              enum:
                - card
                - pix
            installments:
              type: integer
              description: Presente quando `type` é `card`
            card:
              type: object
              nullable: true
              description: Presente quando `type` é `card`
              properties:
                token:
                  type: string
                  description: O `id` do cartão salvo, para reutilizar em outras compras
                  example: 9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f
                brand:
                  type: string
                  example: visa
                last_four:
                  type: string
                  example: '1111'
                holder_name:
                  type: string
                  example: João Silva
        statement_descriptor:
          type: string
          nullable: true
        start_at:
          type: string
          nullable: true
        next_billing_at:
          type: string
          nullable: true
        created_at:
          type: string
        customer:
          type: object
          properties:
            name:
              type: string
            email:
              type: string
        latest_invoice:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/V2Invoice'
        metadata:
          type: object
          additionalProperties: true
    V2Error:
      type: object
      description: Envelope de erro da API v2
      required:
        - error
      properties:
        error:
          type: object
          required:
            - type
            - code
            - message
          properties:
            type:
              type: string
              enum:
                - invalid_request_error
                - idempotency_error
                - authentication_error
                - api_error
              description: Categoria do erro
            code:
              type: string
              description: Código estável do erro. Use este campo na sua lógica
              example: validation_error
            message:
              type: string
              description: Texto técnico, para log e depuração. Não exiba ao pagador
              example: The payments field is required.
            param:
              type: string
              description: >-
                Campo que causou o erro, em notação de ponto. Presente só quando
                se aplica
              example: payments
            customer_message:
              type: string
              description: Texto para exibir ao pagador. Presente só quando se aplica
    V2SubscriptionItem:
      type: object
      required:
        - code
        - description
        - quantity
        - amount
      properties:
        code:
          type: string
          maxLength: 255
          example: SKU-SUB
        description:
          type: string
          maxLength: 255
          example: Assinatura
        quantity:
          type: integer
          minimum: 1
          example: 1
        amount:
          type: integer
          minimum: 1
          description: Valor unitário, em centavos
          example: 10000
    V2SubscriptionAdjustment:
      type: object
      required:
        - type
        - value
      properties:
        type:
          type: string
          enum:
            - fixed
            - percentage
        value:
          type: number
          exclusiveMinimum: 0
          description: >
            Em `fixed`, valor inteiro em centavos. Em `percentage`, percentual
            (em descontos, no máximo 100).
          example: 1000
        invoice_number:
          type: integer
          minimum: 1
          nullable: true
          description: >-
            Número da fatura a que o ajuste se aplica. Sem valor, vale para
            todas as faturas
          example: 1
    V2Invoice:
      type: object
      description: >
        Fatura de um ciclo da assinatura. `processing`: em processamento.
        `requires_action`: PIX aguardando pagamento ou verificação por código
        (veja `next_action`). `paid`: paga. `failed`: recusada (veja
        `failure_reason`). `canceled`: cancelada. `refunded` e
        `partially_refunded`: estornada. `chargeback`: contestada.
      properties:
        id:
          type: string
          example: '719305'
        object:
          type: string
          enum:
            - invoice
        subscription:
          type: string
          example: sub_4Hn8Qw2Rt6Yp1Zx3
        number:
          type: integer
          description: Número da fatura na assinatura
          example: 1
        status:
          type: string
          enum:
            - processing
            - requires_action
            - paid
            - failed
            - canceled
            - refunded
            - partially_refunded
            - chargeback
        currency:
          type: string
          example: brl
        amount:
          type: integer
          description: Valor da fatura, em centavos, já com descontos e acréscimos
          example: 9000
        attempts:
          type: integer
          description: Tentativas de cobrança
        items:
          type: array
          items:
            $ref: '#/components/schemas/V2SubscriptionItem'
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/V2SubscriptionAdjustment'
        increments:
          type: array
          items:
            $ref: '#/components/schemas/V2SubscriptionAdjustment'
        payments:
          type: array
          items:
            $ref: '#/components/schemas/V2PaymentIntent'
        next_action:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/V2NextAction'
        created_at:
          type: string
        failure_reason:
          $ref: '#/components/schemas/V2FailureReason'
    V2ThrottleError:
      type: object
      description: >
        Corpo padrão, fora do envelope `error`, do limite geral de requisições e
        do limite de reenvio do código de verificação
      properties:
        message:
          type: string
          example: Too Many Attempts.
    V2PaymentIntent:
      type: object
      description: >
        Um meio de pagamento dentro de um pedido ou fatura. O `id` é o mesmo da
        cobrança (`GET /v2/charges/{id}`).
      properties:
        id:
          type: string
          example: cha_8Kq2Lm9XvB3nT7pZ
        object:
          type: string
          enum:
            - payment_intent
        status:
          type: string
          enum:
            - requires_action
            - requires_capture
            - processing
            - paid
            - failed
            - canceled
            - refund_processing
            - partially_refunded
            - refunded
            - chargeback
          description: >
            `requires_action`: PIX aguardando pagamento ou verificação por
            código. `requires_capture`: cartão autorizado, aguardando captura.
            `processing`: em processamento. `paid`: pago. `failed`: recusado.
            `canceled`: cancelado. `refund_processing`: estorno em
            processamento. `partially_refunded` e `refunded`: estornado em parte
            ou totalmente. `chargeback`: contestado pelo portador.
        amount:
          type: integer
          description: Valor em centavos
          example: 10000
        amount_refunded:
          type: integer
          description: Valor estornado, em centavos
          example: 0
        currency:
          type: string
          example: brl
        payment_method_details:
          type: object
          properties:
            type:
              type: string
              enum:
                - card
                - pix
                - boleto
            card:
              type: object
              description: Presente em pagamentos com cartão
              properties:
                brand:
                  type: string
                  example: visa
                last_four:
                  type: string
                  example: '1111'
                holder_name:
                  type: string
                  example: João Silva
            pix:
              $ref: '#/components/schemas/V2Pix'
    V2NextAction:
      type: object
      description: >
        O que precisa acontecer para o pagamento seguir. `pix_display_qr_code`:
        exiba o QR Code para o pagador. `otp_confirmation`: a análise de fraude
        pediu verificação — nada é cobrado até o código ser confirmado na rota
        `/confirm`.
      properties:
        type:
          type: string
          enum:
            - pix_display_qr_code
            - otp_confirmation
        pix:
          $ref: '#/components/schemas/V2Pix'
        otp:
          type: object
          description: Presente quando `type` é `otp_confirmation`
          properties:
            confirmation_id:
              type: string
              example: 5f1c2a9e-7b3d-4e8f-9a6c-1d2e3f4a5b6c
            expires_at:
              type: string
              description: Data e hora de expiração do código
              example: '2026-09-14T12:15:00.000000Z'
    V2FailureReason:
      type: object
      description: Motivo da recusa. Presente só quando o status é `failed`
      required:
        - code
        - message
        - customer_message
        - merchant_message
      properties:
        code:
          type: string
          enum:
            - card_declined
            - insufficient_funds
            - expired_card
            - incorrect_cvc
            - incorrect_number
            - card_not_supported
            - fraud_suspected
            - invalid_request
            - acquirer_error
            - processing_error
        message:
          type: string
          description: Texto técnico. Não exiba ao pagador
          example: O cartão não possui saldo suficiente para concluir o pagamento.
        customer_message:
          type: string
          description: Texto para exibir ao pagador
          example: >-
            Não foi possível concluir o pagamento. Revise os dados informados ou
            tente outro meio de pagamento.
        merchant_message:
          type: string
          description: Texto para você ou a sua equipe de atendimento
          example: >-
            O pagamento não foi concluído. Oriente o comprador a revisar os
            dados informados ou tentar outro meio de pagamento.
    V2Pix:
      type: object
      properties:
        qr_code:
          type: string
          description: Código PIX copia e cola
          example: 00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890
        qr_code_url:
          type: string
          description: Link do QR Code
          example: https://pix.exemplo.com.br/qr/cha_8Kq2Lm9XvB3nT7pZ
        expires_at:
          type: string
          description: Data e hora de expiração do QR Code
          example: '2026-09-14T16:00:00.000000Z'
  responses:
    V2IdempotencyInvalid:
      description: O header `Idempotency-Key` tem mais de 128 caracteres
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/V2Error'
          example:
            error:
              type: invalid_request_error
              code: idempotency_key_invalid
              message: Idempotency-Key must be 128 characters or fewer.
    V2Unauthorized:
      description: Chave de API ausente, inválida, revogada ou de outro ambiente
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/V2Error'
          example:
            error:
              type: authentication_error
              code: invalid_api_secret
              message: Invalid API secret.
    V2AccountBlocked:
      description: >-
        As requisições da conta estão bloqueadas. A resposta traz
        `customer_message`
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/V2Error'
          example:
            error:
              type: invalid_request_error
              code: account_requests_blocked
              message: As requisições desta conta estão bloqueadas.
              customer_message: >-
                Não foi possível concluir sua transação. Tente novamente mais
                tarde.
    V2SubscriptionNotFound:
      description: Assinatura não encontrada nesta conta
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/V2Error'
          example:
            error:
              type: invalid_request_error
              code: resource_missing
              message: Recurso "subscription" não encontrado.
    V2IdempotencyInUse:
      description: >-
        Uma requisição com a mesma `Idempotency-Key` ainda está em andamento.
        Tente novamente em instantes
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/V2Error'
          example:
            error:
              type: idempotency_error
              code: idempotency_key_in_use
              message: >-
                A request with this Idempotency-Key is still being processed.
                Retry shortly.
    V2ThrottleExceeded:
      description: >
        Limite geral de requisições excedido (120 por minuto por chave de API e
        por conta). Esta resposta não usa o envelope `error` da API v2.
      headers:
        X-RateLimit-Limit:
          description: Limite de requisições da janela
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Requisições restantes na janela
          schema:
            type: integer
        Retry-After:
          description: Segundos até a próxima tentativa
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/V2ThrottleError'
          example:
            message: Too Many Attempts.
    V2ServerError:
      description: Erro inesperado ao processar a requisição
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/V2Error'
          example:
            error:
              type: api_error
              code: internal_error
              message: Ocorreu um erro inesperado ao processar a requisição.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Token JWT obtido via `POST /v1/login`. Envie no header `Authorization:
        Bearer <token>`.
    secretKeyAuth:
      type: http
      scheme: bearer
      description: >
        Chave de API (secret key) da conta, no formato `sk_live_...` (produção)
        ou `sk_test_...` (Dev mode). Envie no header `Authorization: Bearer
        <chave>`. Autentica todas as rotas da API v2 e as rotas de Análise de
        Fraude. A chave identifica a conta, então a API v2 não usa o header
        `account`. Uma chave só é aceita no ambiente em que foi criada. Gere a
        sua no dashboard em Configurações → Chaves de API.

````