Refunds

Overview

Refunds return money to customers for previously collected charges. They can be full or partial and are tracked separately from the original charge.

How It Works

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.

API Endpoints

Method	Endpoint	Description
`GET`	List refunds	Retrieve a paginated list of refunds
`POST`	Cancel refunds	Cancel pending refunds

Important Behaviors

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.

Refund Statuses

Status	Description
`succeeded`	Refund completed successfully
`pending`	Refund is being processed
`canceled`	Refund was cancelled before completion
`failed`	Refund could not be processed

Refund Object

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