credit-notes
Stable. Describes behaviour that is built and covered by tests in this repository.
GET /v1/credit-notes #
Credit notes, newest first
Parameters
| Name | In | Type | Description |
|---|---|---|---|
invoice_id | query | string · uuid | |
customer | query | string | Customer external id |
page_size | query | integer | |
page_token | query | string |
Responses
| Status | Meaning | Body |
|---|---|---|
200 | OK | ListCreditNotesResponse |
400 | Error envelope | Error |
Example response
{
"credit_notes": [
{
"id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
"number": "string",
"invoice_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
"invoice_number": "string",
"customer_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
"customer_external_id": "string",
"currency": "string",
"total_minor": "string",
"tax_minor": "string",
"reason": "string",
"create_time": "2026-11-03T10:15:00Z",
"disposition": "CREDIT_NOTE_DISPOSITION_CREDIT",
"refund_state": "REFUND_STATE_REQUESTED",
"refund_error": "string"
}
],
"next_page_token": "string"
}curl
curl -X GET https://YOUR-API-ADDRESS/v1/credit-notes \
-H "Authorization: Bearer $PAYRUDDER_API_KEY"POST /v1/credit-notes/{id}/retry-refund #
Ask the payment provider again for a refund to the card that failed
Only a credit note whose refund failed: 409 billing.credit_note.refund_not_failed for any other. Settling a failed refund by hand (it was made at the provider some other way) is the operator's. Needs invoices:write.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id required | path | string · uuid |
Responses
| Status | Meaning | Body |
|---|---|---|
200 | OK | CreditNote |
403 | Error envelope | Error |
404 | Error envelope | Error |
409 | Error envelope | Error |
Example response
{
"id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
"number": "string",
"invoice_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
"invoice_number": "string",
"customer_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
"customer_external_id": "string",
"currency": "string",
"total_minor": "string",
"tax_minor": "string",
"reason": "string",
"create_time": "2026-11-03T10:15:00Z",
"disposition": "CREDIT_NOTE_DISPOSITION_CREDIT",
"refund_state": "REFUND_STATE_REQUESTED",
"refund_error": "string"
}curl
curl -X POST https://YOUR-API-ADDRESS/v1/credit-notes/<id>/retry-refund \
-H "Authorization: Bearer $PAYRUDDER_API_KEY"GET /v1/credit-notes/{id} #
A credit note
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id required | path | string · uuid |
Responses
| Status | Meaning | Body |
|---|---|---|
200 | OK | CreditNote |
404 | Error envelope | Error |
Example response
{
"id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
"number": "string",
"invoice_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
"invoice_number": "string",
"customer_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
"customer_external_id": "string",
"currency": "string",
"total_minor": "string",
"tax_minor": "string",
"reason": "string",
"create_time": "2026-11-03T10:15:00Z",
"disposition": "CREDIT_NOTE_DISPOSITION_CREDIT",
"refund_state": "REFUND_STATE_REQUESTED",
"refund_error": "string"
}curl
curl -X GET https://YOUR-API-ADDRESS/v1/credit-notes/<id> \
-H "Authorization: Bearer $PAYRUDDER_API_KEY"Models
CreditNote
| Field | Type | Description |
|---|---|---|
id required | string · uuid | |
number required | string | CN-2026-000007 (live) or SBX-CN-2026-000007 (sandbox) |
invoice_id required | string · uuid | |
invoice_number required | string | |
customer_id required | string · uuid | |
customer_external_id required | string | |
currency required | string | |
total_minor required | string · int64 | |
tax_minor required | string · int64 | The part of total_minor that is the invoice's tax given back: the note's share of the invoice's total taken from the invoice's tax, so the notes of an invoice give back its tax exactly. 0 for an untaxed invoice and for a note made before this field existed |
reason required | string | |
create_time required | string · date-time | |
disposition required | CREDIT_NOTE_DISPOSITION_CREDIT | CREDIT_NOTE_DISPOSITION_REFUND | Where the amount went: the credit balance, or back to the card |
refund_state required | REFUND_STATE_REQUESTED | REFUND_STATE_REFUNDED | REFUND_STATE_FAILED | Only for a refund to the card |
refund_error required | string |
Error
| Field | Type | Description |
|---|---|---|
error required | object |
ListCreditNotesResponse
| Field | Type | Description |
|---|---|---|
credit_notes required | array of CreditNote | |
next_page_token required | string |