Cancelar cobrança extra
curl --request DELETE \
--url https://api.sandbox.z2pay.com/v1/subscriptions/{id}/extra-items/{itemId} \
--header 'x-api-key: <api-key>'const options = {method: 'DELETE', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.sandbox.z2pay.com/v1/subscriptions/{id}/extra-items/{itemId}', 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/{itemId}"
headers = {"x-api-key": "<api-key>"}
response = requests.delete(url, headers=headers)
print(response.text){
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Subscription not found"
}
}{
"error": {
"code": "CONFLICT",
"message": "No refundable payment found"
}
}{
"error": "Idempotency key already used with a different request body"
}Cobranças extras
Cancelar cobrança extra
Remove um item da fila antes que uma fatura de ciclo o inclua.
DELETE
/
subscriptions
/
{id}
/
extra-items
/
{itemId}
Cancelar cobrança extra
curl --request DELETE \
--url https://api.sandbox.z2pay.com/v1/subscriptions/{id}/extra-items/{itemId} \
--header 'x-api-key: <api-key>'const options = {method: 'DELETE', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.sandbox.z2pay.com/v1/subscriptions/{id}/extra-items/{itemId}', 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/{itemId}"
headers = {"x-api-key": "<api-key>"}
response = requests.delete(url, headers=headers)
print(response.text){
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Subscription not found"
}
}{
"error": {
"code": "CONFLICT",
"message": "No refundable payment found"
}
}{
"error": "Idempotency key already used with a different request body"
}DELETE /subscriptions/:id/extra-items/:itemId
Faz parte do recurso Assinaturas. O item é criado em
Lançar cobrança extra, e a fila inteira está em
Listar cobranças extras.
Cancela um item: status vira canceled e ele sai da fila que as próximas faturas recolhem.
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.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.Exemplo
curl -X DELETE https://api.sandbox.z2pay.com/v1/subscriptions/sub_x33m4yn6brazh71en4mki6f5c/extra-items/xitm_xusdt7vquv0sjrj8k6er6xn6y \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX"
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": "canceled",
"consumedInvoiceId": null,
"createdAt": "2026-08-10T18:20:00.000Z"
}