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

# Cancelar cobrança extra

> Remove um item da fila antes que uma fatura de ciclo o inclua.

`DELETE /subscriptions/:id/extra-items/:itemId`

Faz parte do recurso [Assinaturas](/pt-BR/subscriptions). O item é criado em
[Lançar cobrança extra](/pt-BR/subscriptions/extra-items), e a fila inteira está em
[Listar cobranças extras](/pt-BR/subscriptions/extra-items-get).

Cancela um item: `status` vira `canceled` e ele sai da fila que as próximas faturas recolhem.

<Warning>
  **Só funciona com o item `pending`.** Depois que uma fatura o recolhe (`status: "consumed"`), ele
  já é uma linha dela — a partir daí o ajuste é na fatura, não neste item.
</Warning>

<Note>
  **Uma fatura pode recolher o item entre a listagem e o `DELETE`.** Nesse caso a resposta é `409`, e
  o `consumedInvoiceId` do item diz em qual fatura ele entrou.
</Note>

## Exemplo

```bash theme={null}
curl -X DELETE https://api.sandbox.z2pay.com/v1/subscriptions/sub_x33m4yn6brazh71en4mki6f5c/extra-items/xitm_xusdt7vquv0sjrj8k6er6xn6y \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
```

```json Resposta 200 theme={null}
{
  "id": "xitm_xusdt7vquv0sjrj8k6er6xn6y",
  "description": "Segunda via da carteirinha",
  "amount": 4990,
  "quantity": 1,
  "currency": "BRL",
  "reason": "extra_service",
  "reasonDetails": "Cliente perdeu a carteirinha e pediu a segunda via",
  "status": "canceled",
  "consumedInvoiceId": null,
  "createdAt": "2026-08-10T18:20:00.000Z"
}
```


## OpenAPI

````yaml openapi/billing.json DELETE /subscriptions/{id}/extra-items/{itemId}
openapi: 3.0.3
info:
  title: Z2Pay Billing API
  version: 1.0.0
  description: Cobrança recorrente da Z2Pay — planos, assinaturas e faturas
servers:
  - url: https://api.sandbox.z2pay.com/v1
    description: Sandbox
  - url: https://api.z2pay.com/v1
    description: Produção
security: []
tags:
  - name: Invoices
    description: Faturas emitidas pelas assinaturas
  - name: Plans
    description: Planos de cobrança e versões de preço
  - name: Subscriptions
    description: Assinaturas recorrentes
paths:
  /subscriptions/{id}/extra-items/{itemId}:
    delete:
      tags:
        - Subscriptions
      summary: Cancelar cobrança extra
      description: >-
        Só é possível cancelar enquanto o item ainda está `pending`. Depois que
        um fechamento o consome (`status=consumed`), ele já compõe o total de
        uma fatura — o caminho a partir daí é estorno/crédito na fatura, fora do
        escopo desta rota.
      operationId: SubscriptionController_cancelExtraItem
      parameters:
        - name: itemId
          in: path
          required: true
          description: ID da cobrança extra
          schema:
            type: string
        - name: id
          in: path
          required: true
          description: ID da assinatura
          schema:
            type: string
      responses:
        '200':
          description: Cobrança extra cancelada
        '401':
          description: Chave de API ausente, malformada ou inválida
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: >-
                          Identificador estável do erro. É por ele que você deve
                          ramificar, não pela mensagem.
                      message:
                        type: string
                        description: >-
                          Descrição legível. Pode mudar sem aviso e não deve ser
                          usada em condicional.
              example:
                error:
                  code: UNAUTHORIZED
                  message: Invalid API key
        '404':
          description: Assinatura ou cobrança extra não encontrada
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: >-
                          Identificador estável do erro. É por ele que você deve
                          ramificar, não pela mensagem.
                      message:
                        type: string
                        description: >-
                          Descrição legível. Pode mudar sem aviso e não deve ser
                          usada em condicional.
              example:
                error:
                  code: NOT_FOUND
                  message: Subscription not found
        '409':
          description: Item já foi faturado ou cancelado
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: >-
                          Identificador estável do erro. É por ele que você deve
                          ramificar, não pela mensagem.
                      message:
                        type: string
                        description: >-
                          Descrição legível. Pode mudar sem aviso e não deve ser
                          usada em condicional.
              example:
                error:
                  code: CONFLICT
                  message: No refundable payment found
        '422':
          description: >-
            Idempotency-Key já usada com um corpo diferente. Use uma chave nova
            para uma operação diferente
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem do conflito de idempotência. Aqui `error` é
                      texto, não objeto — ramifique pelo status HTTP.
              example:
                error: Idempotency key already used with a different request body
      security:
        - apiKey: []
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API Key da Credential (gerada no Backoffice)

````