Listar cobranças extras
curl --request GET \
--url https://api.sandbox.z2pay.com/v1/subscriptions/{id}/extra-items \
--header 'x-api-key: <api-key>'const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.sandbox.z2pay.com/v1/subscriptions/{id}/extra-items', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.sandbox.z2pay.com/v1/subscriptions/{id}/extra-items"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"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)"
}
]
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Subscription not found"
}
}Cobranças extras
Listar cobranças extras
Fila de cobranças extras da assinatura, com filtro por status e sem paginação.
GET
/
subscriptions
/
{id}
/
extra-items
Listar cobranças extras
curl --request GET \
--url https://api.sandbox.z2pay.com/v1/subscriptions/{id}/extra-items \
--header 'x-api-key: <api-key>'const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.sandbox.z2pay.com/v1/subscriptions/{id}/extra-items', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.sandbox.z2pay.com/v1/subscriptions/{id}/extra-items"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"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)"
}
]
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Subscription not found"
}
}GET /subscriptions/:id/extra-items
Faz parte do recurso Assinaturas. Para lançar um item nesta fila, veja
Lançar cobrança extra.
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}.Exemplo
O filtropending devolve o que ainda vai ser cobrado, sem o histórico já faturado:
curl -G https://api.sandbox.z2pay.com/v1/subscriptions/sub_x33m4yn6brazh71en4mki6f5c/extra-items \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
-d status=pending
Resposta 200
[
{
"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"
}
]
Authorizations
API Key da Credential (gerada no Backoffice)
Path Parameters
ID da assinatura
Query Parameters
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.
Available options:
pending, consumed, canceled Response
Lista de cobranças extras