> ## 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.
# Listar cobranças extras
> Fila de cobranças extras da assinatura, com filtro por status e sem paginação.
`GET /subscriptions/:id/extra-items`
Faz parte do recurso [Assinaturas](/pt-BR/subscriptions). Para lançar um item nesta fila, veja
[Lançar cobrança extra](/pt-BR/subscriptions/extra-items).
Devolve a fila da assinatura, da mais antiga para a mais nova, sem paginação. Sem `?status`, vem o
histórico completo: pendente, já faturado e cancelado juntos.
**`?status=xpto` responde `400`, não ignora o filtro.** Os três valores aceitos estão descritos no
parâmetro, ao lado.
**`consumedInvoiceId` só existe em `status: "consumed"`.** É a fatura que recolheu o item — a
linha `one_time` correspondente está nos `items` dela, em
[`GET /invoices/{id}`](/pt-BR/subscriptions/invoices/get).
## Exemplo
O filtro `pending` devolve o que ainda vai ser cobrado, sem o histórico já faturado:
```bash theme={null}
curl -G https://api.sandbox.z2pay.com/v1/subscriptions/sub_x33m4yn6brazh71en4mki6f5c/extra-items \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
-d status=pending
```
```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": "pending",
"consumedInvoiceId": null,
"createdAt": "2026-08-10T18:20:00.000Z"
}
]
```
## OpenAPI
````yaml openapi/billing.json GET /subscriptions/{id}/extra-items
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:
get:
tags:
- Subscriptions
summary: Listar cobranças extras
description: >-
Fila de cobranças extras da assinatura, mais antiga primeiro. Não
paginada — o volume por assinatura é baixo por natureza (itens somem da
fila assim que uma fatura fecha).
operationId: SubscriptionController_listExtraItems
parameters:
- name: status
in: query
required: false
description: >-
`pending` = ainda não caiu em nenhuma fatura (extrato "a faturar");
`consumed` = já entrou numa fatura (ver `consumedInvoiceId`);
`canceled` = cancelado antes de faturar. Sem o filtro, devolve os
três.
schema:
type: string
enum:
- pending
- consumed
- canceled
description: >-
`pending` = ainda não caiu em nenhuma fatura (extrato "a
faturar"); `consumed` = já entrou numa fatura (ver
`consumedInvoiceId`); `canceled` = cancelado antes de faturar. Sem
o filtro, devolve os três.
- name: id
in: path
required: true
description: ID da assinatura
schema:
type: string
responses:
'200':
description: Lista de cobranças extras
'400':
description: >-
Requisição inválida — algum parâmetro ou campo do corpo não passou
na validação
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.
issues:
type: array
description: >-
Um item por campo rejeitado. Nunca vem vazio: se há
400 de validação, há pelo menos um.
items:
type: object
properties:
path:
type: string
description: >-
Campo que falhou. Vem vazio quando o erro é do
corpo como um todo.
message:
type: string
description: O que há de errado com esse campo.
example:
error:
code: VALIDATION_ERROR
message: Validation failed
issues:
- path: status
message: >-
Status inválido. Valores aceitos: pending,
waiting_payment, paid, refused, canceled, refunded
- path: startDate
message: >-
Data deve ser ISO 8601 com timezone (ex.:
2026-06-24T00:00:00Z)
'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 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
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````