Refunds return money to customers for previously collected charges. They can be full or partial and are tracked separately from the original charge.
- Refund requested — A refund is initiated through the dashboard or API
- Processing — The refund is sent to the payment processor
- Completed — Funds are returned to the customer's payment method
Example: A customer cancels their annual subscription mid-year. A prorated refund of $50 is created against their original $99 charge. The customer sees the credit on their card statement within 5-10 business days.
- User ID via charge: Each refund includes
user_id resolved through the charge relationship (charge → customer). If the charge has no customer, user_id is null.
- Expandable charge: Pass
include=charge to get the full charge object embedded in the response.
- Cancel accepts IDs or 'all': The cancel endpoint accepts a comma-separated string of refund IDs, or the string
'all' to cancel all eligible pending refunds.
- Only "to_issue" refunds are cancellable: The cancel endpoint only affects refunds with
status: to_issue and a valid created date.
- Async cancellation: Cancel dispatches a background job (
InitiateCancelledRefunds). Refunds are not cancelled immediately.
| Status | Description |
|---|
succeeded | Refund completed successfully |
pending | Refund is being processed |
canceled | Refund was cancelled before completion |
failed | Refund could not be processed |
| Attribute | Type | Description |
|---|
id | integer | Unique identifier |
charge_id | integer | ID of the original charge (expandable via include=charge) |
user_id | integer|null | Customer ID resolved via charge relationship |
amount | integer | Refund amount in cents |
currency | string | Three-letter ISO currency code |
status | string | Refund status |
reason | string|null | Reason for the refund |
description | string|null | Description |
reference | string|null | External reference number |
receipt_number | string|null | Receipt number |
offline | boolean | Whether this is an offline refund |
failed_reason | string|null | Reason for failure (if failed) |
failed_at | integer|null | Unix timestamp of failure |
created_at | integer | Unix timestamp of creation |
