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));

{
  "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

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));

{
  "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 filtro pending 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

x-api-key

string

header

required

API Key da Credential (gerada no Backoffice)

Path Parameters

string

required

ID da assinatura

Query Parameters

status

enum<string>

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

Cobranças

Clientes & Cartões

Checkout

Cobrança recorrente

Split & Recebedores

Webhooks & Eventos

Valores & Taxas

Listar cobranças extras

Exemplo

Authorizations

Path Parameters

Query Parameters

Response

​Exemplo

Authorizations

Path Parameters

Query Parameters

Response

Exemplo