Refunds

Add an overview of the Refunds API here. This block is preserved across regenerations.

Endpoints

GET /api/v1/invoices/{id}/refunds

List all refunds issued against payments for an invoice

get

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/invoices/{id}/refunds

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Path parameters

idstringRequired

Invoice ID

Query parameters

limitinteger · min: 1 · max: 100Optional

Max items to return (1–100, default 20)

Default: 20

offsetintegerOptional

Number of items to skip (default 0)

Default: 0

Responses

200

Paginated list of refunds

No content

404

No payment session in the caller's tenant references this invoice (anti-enumeration — see Task #1459)

application/json

get/invoices/{id}/refunds

HTTPcURLJavaScriptPython

GET /api/v1/invoices/{id}/refunds HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for GET /invoices/{id}/refunds go here.

POST /api/v1/invoices/{id}/refunds

Issue a refund against the payment for an invoice. Targets the most recent successful payment session linked to this invoice.

post

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/invoices/{id}/refunds

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Path parameters

idstringRequired

Invoice ID (externalInvoiceId on the payment session)

Header parameters

Idempotency-KeystringOptional

Per-refund idempotency key. A retry with the same key + same body returns the original refund; same key + different body returns 409.

Body

application/json

amountCentsinteger · min: 1Optional

reasonstring · max: 500Optional

refundAllbooleanOptionalDefault: false

Responses

200

Replayed prior refund for the same Idempotency-Key

application/json

A refund issued against a successful payment session

idstringOptional

paymentIdstringOptional

invoiceIdstring · nullableOptional

amountCentsintegerOptional

currencystringOptional

statusstring · enumOptionalPossible values:

isFullRefundbooleanOptional

reasonstring · nullableOptional

createdAtstring · date-timeOptional

updatedAtstring · date-timeOptional

201

Refund issued

application/json

400

Validation error or payment not refundable

application/json

404

No successful payment session found for this invoice

application/json

409

Idempotency-Key reused with a different request body

application/json

post/invoices/{id}/refunds

HTTPcURLJavaScriptPython

POST /api/v1/invoices/{id}/refunds HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "amountCents": 1,
  "reason": "text",
  "refundAll": false
}

{
  "id": "text",
  "paymentId": "text",
  "invoiceId": "text",
  "amountCents": 1,
  "currency": "text",
  "status": "pending",
  "isFullRefund": true,
  "reason": "text",
  "createdAt": "2026-07-14T00:12:30.027Z",
  "updatedAt": "2026-07-14T00:12:30.027Z"
}

Notes, examples, or caveats for POST /invoices/{id}/refunds go here.

GET /api/v1/payments/{id}/refunds

List all refunds issued against a payment session

get

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/payments/{id}/refunds

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Path parameters

idstringRequired

Payment session ID

Query parameters

limitinteger · min: 1 · max: 100Optional

Max items to return (1–100, default 20)

Default: 20

offsetintegerOptional

Number of items to skip (default 0)

Default: 0

Responses

200

Paginated list of refunds

No content

404

Payment session not found

application/json

get/payments/{id}/refunds

HTTPcURLJavaScriptPython

GET /api/v1/payments/{id}/refunds HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for GET /payments/{id}/refunds go here.

POST /api/v1/payments/{id}/refunds

Issue a refund against a successful payment session. Supports full refunds (default) and partial refunds via amountCents.

post

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/payments/{id}/refunds

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Path parameters

idstringRequired

Payment session ID

Header parameters

Idempotency-KeystringOptional

Per-refund idempotency key. A retry with the same key + same body returns the original refund; same key + different body returns 409.

Body

application/json

amountCentsinteger · min: 1Optional

Partial refund amount in cents. Omit to refund the full refundable balance.

reasonstring · max: 500Optional

refundAllbooleanOptional

Explicitly refund the full remaining balance.

Default: false

Responses

200

Replayed prior refund for the same Idempotency-Key

application/json

A refund issued against a successful payment session

idstringOptional

paymentIdstringOptional

invoiceIdstring · nullableOptional

amountCentsintegerOptional

currencystringOptional

statusstring · enumOptionalPossible values:

isFullRefundbooleanOptional

reasonstring · nullableOptional

createdAtstring · date-timeOptional

updatedAtstring · date-timeOptional

201

Refund issued

application/json

400

Validation error or payment not refundable

application/json

404

Payment session not found

application/json

409

Idempotency-Key reused with a different request body

application/json

post/payments/{id}/refunds

HTTPcURLJavaScriptPython

POST /api/v1/payments/{id}/refunds HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "amountCents": 1,
  "reason": "text",
  "refundAll": false
}

{
  "id": "text",
  "paymentId": "text",
  "invoiceId": "text",
  "amountCents": 1,
  "currency": "text",
  "status": "pending",
  "isFullRefund": true,
  "reason": "text",
  "createdAt": "2026-07-14T00:12:30.027Z",
  "updatedAt": "2026-07-14T00:12:30.027Z"
}

Notes, examples, or caveats for POST /payments/{id}/refunds go here.