> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getruba.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List Refunds
> ### Intent
Reads the available refunds as a pageable collection without changing them.
### When to call it
Call this when an interface, sync, or support workflow needs to inspect refunds. Use the filters and paging controls shown below to limit the result.
### Access boundary
Authorize the request with a token that carries `refunds:read` or `refunds:write`.
### Successful result
A successful request returns `200`. The response schema below defines the body your integration receives.
export const RubaSocials = () => {
if (typeof document === "undefined") {
return null;
}
const inject = () => {
const footer = document.getElementById("footer");
if (!footer || document.getElementById("ruba-socials")) {
return false;
}
const isDark = document.querySelector("html.dark") || document.querySelector('html[class*="dark"]');
const lineColor = isDark ? "#383838" : "#e8e8ed";
const iconColor = isDark ? "#8e8e93" : "#86868b";
const markColor = isDark ? "#ffffff" : "#08080c";
const hoverColor = "#0071e3";
const div = document.createElement("div");
div.id = "ruba-socials";
div.style.cssText = `display:flex;align-items:center;gap:20px;padding-top:20px;margin-top:20px;border-top:1px solid ${lineColor};width:100%`;
const logo = `Ruba`;
const spacer = ``;
const ig = ``;
const li = ``;
const x = ``;
const github = ``;
div.innerHTML = logo + spacer + ig + li + x + github;
footer.appendChild(div);
return true;
};
if (!document.documentElement.dataset.rubaSocialsObserver) {
document.documentElement.dataset.rubaSocialsObserver = "true";
const observer = new MutationObserver(() => {
if (!document.getElementById("ruba-socials")) {
inject();
}
});
observer.observe(document.body, {
childList: true,
subtree: true
});
}
setTimeout(() => {
if (!inject()) {
const interval = setInterval(() => {
if (inject()) {
clearInterval(interval);
}
}, 500);
setTimeout(() => clearInterval(interval), 10000);
}
}, 300);
return null;
};
## OpenAPI
````yaml get /v1/refunds/
openapi: 3.1.0
info:
title: Ruba API
summary: Ruba HTTP and Webhooks API
description: '**Details:** Read the docs at https://docs.getruba.com/api-reference.'
version: 2026-04
servers:
- url: https://api.getruba.com
description: '**Details:** Production environment.'
x-speakeasy-server-id: production
- url: https://sandbox-api.getruba.com
description: '**Details:** Sandbox environment.'
x-speakeasy-server-id: sandbox
security: []
tags:
- name: public
description: >-
**Details:** Endpoints shown and documented in the Ruba API documentation
and available in our SDKs.
- name: private
description: >-
**Details:** Endpoints that should appear in the schema only in
development to generate our internal JS SDK.
paths:
/v1/refunds/:
get:
tags:
- refunds
- public
summary: List Refunds
description: >-
### Intent
Reads the available refunds as a pageable collection without changing
them.
### When to call it
Call this when an interface, sync, or support workflow needs to inspect
refunds. Use the filters and paging controls shown below to limit the
result.
### Access boundary
Authorize the request with a token that carries `refunds:read` or
`refunds:write`.
### Successful result
A successful request returns `200`. The response schema below defines
the body your integration receives.
operationId: refunds:list
parameters:
- name: id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid4
description: Identifier of the refund.
- type: array
items:
type: string
format: uuid4
description: Identifier of the refund.
- type: 'null'
title: RefundID Filter
description: Return only records matching refund ID.
description: Return only records matching refund ID.
- name: organization_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid4
description: Identifier of the organization.
examples:
- 1dbfc517-0bbf-4301-9ba8-555ca42b9737
x-ruba-selector-widget:
displayProperty: name
resourceName: Organization
resourceRoot: /v1/organizations
- type: array
items:
type: string
format: uuid4
description: Identifier of the organization.
examples:
- 1dbfc517-0bbf-4301-9ba8-555ca42b9737
x-ruba-selector-widget:
displayProperty: name
resourceName: Organization
resourceRoot: /v1/organizations
- type: 'null'
title: OrganizationID Filter
description: Return only records matching organization ID.
description: Return only records matching organization ID.
- name: order_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid4
description: Identifier of the order.
- type: array
items:
type: string
format: uuid4
description: Identifier of the order.
- type: 'null'
title: OrderID Filter
description: Return only records matching order ID.
description: Return only records matching order ID.
- name: subscription_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid4
description: Identifier of the subscription.
- type: array
items:
type: string
format: uuid4
description: Identifier of the subscription.
- type: 'null'
title: SubscriptionID Filter
description: Return only records matching subscription ID.
description: Return only records matching subscription ID.
- name: customer_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid4
description: Identifier of the customer.
- type: array
items:
type: string
format: uuid4
description: Identifier of the customer.
- type: 'null'
title: CustomerID Filter
description: Return only records matching customer ID.
description: Return only records matching customer ID.
- name: external_customer_id
in: query
required: false
schema:
anyOf:
- type: string
description: Identifier of the customer external.
- type: array
items:
type: string
description: Identifier of the customer external.
- type: 'null'
title: ExternalCustomerID Filter
description: Return only records matching customer external ID.
description: Return only records matching customer external ID.
- name: succeeded
in: query
required: false
schema:
anyOf:
- type: boolean
- type: 'null'
title: RefundStatus Filter
description: Return only records matching `succeeded`.
description: Return only records matching `succeeded`.
- name: page
in: query
required: false
schema:
type: integer
exclusiveMinimum: 0
description: Results page to return. The first page is used by default.
default: 1
title: Page
description: Results page to return. The first page is used by default.
- name: limit
in: query
required: false
schema:
type: integer
exclusiveMinimum: 0
description: Records returned per page. Defaults to 10 and accepts up to 100.
default: 10
title: Limit
description: Records returned per page. Defaults to 10 and accepts up to 100.
- name: sorting
in: query
required: false
schema:
anyOf:
- type: array
items:
$ref: '#/components/schemas/RefundSortProperty'
- type: 'null'
description: >-
Sort rules applied from left to right. Prefix any rule with `-` to
reverse it into descending order.
default:
- '-created_at'
title: Sorting
description: >-
Sort rules applied from left to right. Prefix any rule with `-` to
reverse it into descending order.
responses:
'200':
description: Request completed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ListResource_Refund_'
'422':
description: Request validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- oidc:
- refunds:read
- refunds:write
- pat:
- refunds:read
- refunds:write
- oat:
- refunds:read
- refunds:write
components:
schemas:
RefundSortProperty:
type: string
enum:
- created_at
- '-created_at'
- amount
- '-amount'
title: RefundSortProperty
ListResource_Refund_:
properties:
items:
items:
$ref: '#/components/schemas/Refund'
type: array
title: Items
pagination:
$ref: '#/components/schemas/Pagination'
type: object
required:
- items
- pagination
title: ListResource[Refund]
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
Refund:
properties:
created_at:
type: string
format: date-time
title: Created At
description: The time Ruba created this record.
modified_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Modified At
description: The time this record last changed.
id:
type: string
format: uuid4
title: Id
description: The stable identifier for this record.
metadata:
$ref: '#/components/schemas/MetadataOutputType'
status:
$ref: '#/components/schemas/RefundStatus'
reason:
$ref: '#/components/schemas/RefundReason'
amount:
type: integer
title: Amount
tax_amount:
type: integer
title: Tax Amount
currency:
type: string
title: Currency
organization_id:
type: string
format: uuid4
title: Organization Id
order_id:
type: string
format: uuid4
title: Order Id
subscription_id:
anyOf:
- type: string
format: uuid4
- type: 'null'
title: Subscription Id
customer_id:
type: string
format: uuid4
title: Customer Id
revoke_benefits:
type: boolean
title: Revoke Benefits
dispute:
anyOf:
- $ref: '#/components/schemas/RefundDispute'
- type: 'null'
type: object
required:
- created_at
- modified_at
- id
- metadata
- status
- reason
- amount
- tax_amount
- currency
- organization_id
- order_id
- subscription_id
- customer_id
- revoke_benefits
- dispute
title: Refund
Pagination:
properties:
total_count:
type: integer
title: Total Count
max_page:
type: integer
title: Max Page
type: object
required:
- total_count
- max_page
title: Pagination
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
MetadataOutputType:
additionalProperties:
anyOf:
- type: string
- type: integer
- type: number
- type: boolean
type: object
RefundStatus:
type: string
enum:
- pending
- succeeded
- failed
- canceled
title: RefundStatus
RefundReason:
type: string
enum:
- duplicate
- fraudulent
- customer_request
- service_disruption
- satisfaction_guarantee
- dispute_prevention
- other
title: RefundReason
RefundDispute:
properties:
created_at:
type: string
format: date-time
title: Created At
description: The time Ruba created this record.
modified_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Modified At
description: The time this record last changed.
id:
type: string
format: uuid4
title: Id
description: The stable identifier for this record.
status:
$ref: '#/components/schemas/DisputeStatus'
description: >-
**Status:** Status of the dispute. `prevented` means we issued a
refund before the dispute was escalated, avoiding any fees.
examples:
- needs_response
- prevented
resolved:
type: boolean
title: Resolved
description: Indicates whether the dispute has been resolved (won or lost).
examples:
- false
closed:
type: boolean
title: Closed
description: Indicates whether the dispute is closed (prevented, won, or lost).
examples:
- false
amount:
type: integer
title: Amount
description: '**Amount:** Amount in cents disputed.'
examples:
- 1000
tax_amount:
type: integer
title: Tax Amount
description: '**Tax Amount:** Tax amount in cents disputed.'
examples:
- 200
currency:
type: string
title: Currency
description: '**Currency:** Currency code of the dispute.'
examples:
- usd
reason:
anyOf:
- type: string
- type: 'null'
title: Reason
description: >-
**Reason:** Reason for the dispute as reported by the card network
(e.g. `fraudulent`, `product_not_received`). `None` until the
processor reports it.
examples:
- fraudulent
evidence_due_by:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Evidence Due By
description: >-
**Evidence Due By:** Deadline to submit evidence in response to the
dispute. `None` when no response is required.
past_due:
type: boolean
title: Past Due
description: Indicates whether the evidence submission deadline has passed.
examples:
- false
order_id:
type: string
format: uuid4
title: Order Id
description: Unique identifier for the order associated with the dispute.
examples:
- 57107b74-8400-4d80-a2fc-54c2b4239cb3
payment_id:
type: string
format: uuid4
title: Payment Id
description: Unique identifier for the payment associated with the dispute.
examples:
- 42b94870-36b9-4573-96b6-b90b1c99a353
type: object
required:
- created_at
- modified_at
- id
- status
- resolved
- closed
- amount
- tax_amount
- currency
- reason
- evidence_due_by
- past_due
- order_id
- payment_id
title: RefundDispute
description: |-
Dispute associated with a refund,
in case we prevented a dispute by issuing a refund.
DisputeStatus:
type: string
enum:
- prevented
- early_warning
- needs_response
- under_review
- lost
- won
title: DisputeStatus
securitySchemes:
oidc:
type: openIdConnect
openIdConnectUrl: /.well-known/openid-configuration
pat:
type: http
description: >-
**Authentication:** You can generate a **Personal Access Token** from
your [settings](https://getruba.com/settings).
scheme: bearer
oat:
type: http
description: >-
**Authentication:** You can generate an **Organization Access Token**
from your organization's settings.
scheme: bearer
````