---
title: "Create refund (full or partial)"
method: POST
path: "/v1/platform/businesses/{business_id}/invoices/refunds/"
tags: ["Refunds"]
---

# Create refund (full or partial)

`POST /v1/platform/businesses/{business_id}/invoices/refunds/`

## Request

- Base URL: `https://docs.thredfi.com` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.thredfi.com/v1/platform/businesses/{business_id}/invoices/refunds/`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - HTTP basic
  - HTTP bearer
  - HTTP bearer

Create a simple refund for an invoice. Provide partial_amount to create a partial refund.

## Path parameters

- `business_id` string, uuid, required

## Request body

- CreateSimpleRefundRequest: Serializer for creating simple refunds
  - `invoice_id` string, uuid, required: Invoice to refund
  - `method` 'CASH' | 'CHECK' | 'CREDIT_CARD' | 'DEBIT_CARD' | 'ACH' | 'BANK_TRANSFER' | 'PAYPAL' | 'STRIPE' | 'OTHER', required: Payment method for the refund * `CASH` - Cash * `CHECK` - Check * `CREDIT_CARD` - Credit Card * `DEBIT_CARD` - Debit Card * `ACH` - ACH * `BANK_TRANSFER` - Bank Transfer * `PAYPAL` - PayPal * `STRIPE` - Stripe * `OTHER` - Other
  - `completed_at` string, date-time, required: When the refund was completed
  - `amount_cents` integer: Optional: Partial refund amount in cents. If not provided, refunds full amount.
  - `external_id` string, required: Required external identifier for idempotency (unique per business)
  - `memo` string: Optional description
  - `reference_number` string: Optional reference number
  - `processor` string: Payment processor (e.g., STRIPE)
  - `refund_processing_fee_cents` integer: Processing fee for the refund in cents
  - `document` RefundDocumentUploadRequest: Refund specific document upload payload.
    - `file` string, binary
    - `document_type` string
    - `upload_source` string
    - `metadata` unknown
    - `tags` unknown

## Response `201`

- Refund: Serializer for refunds (simple response). All amounts in cents.
  - `id` string, uuid, required: Unique refund identifier
  - `external_id` string: Your unique identifier for this refund (used for idempotency)
  - `refunded_amount` integer, required: Total refunded amount in cents
  - `status` 'pending' | 'processing' | 'paid' | 'failed' | 'cancelled': Refund status (pending, processing, paid, failed, cancelled) * `pending` - Pending * `processing` - Processing * `paid` - Paid * `failed` - Failed * `cancelled` - Cancelled
  - `completed_at` string, date-time, nullable: Timestamp when refund was fully paid
  - `is_dedicated` boolean: Whether this is a dedicated refund (true/false)
  - `memo` string: Description or reason for the refund
  - `reference_number` string: Reference number for tracking
  - `metadata` unknown
  - `customer_id` string, uuid, required: UUID of the customer receiving the refund
  - `customer_name` string, required: Customer display name
  - `allocations` RefundAllocation[], required
    - `id` string, uuid, required: Unique allocation identifier
    - `allocation_type` 'invoice' | 'payment' | 'credit' | 'line_item', required: Type of allocation (invoice, line_item, etc.) * `invoice` - Invoice Refund * `payment` - Payment Refund * `credit` - Customer Credit * `line_item` - Line Item Refund
    - `amount` integer, required: Allocation amount in cents
    - `invoice_id` string, uuid, required: Invoice ID if allocated to invoice
    - `invoice_number` string, required: Invoice number if allocated to invoice
    - `invoice_outstanding_balance_cents` integer, required: Invoice outstanding balance in cents if allocated to invoice
    - `target_description` string, required
    - `description` string: Allocation description or notes
    - `allocation_date` string, date-time: Date when allocation was made
  - `refund_payments` RefundPayment[], required
    - `id` string, uuid, required: Unique refund payment identifier
    - `refund_id` string, uuid, required: ID of the refund this payment belongs to
    - `external_id` string: Your unique identifier for idempotency (unique within refund)
    - `refunded_amount` integer, required: Refunded amount in cents
    - `refund_processing_fee` integer, required: Processing fee in cents
    - `completed_at` string, date-time, nullable: Date and time when refund payment was completed
    - `method` 'BANK_TRANSFER' | 'CREDIT_CARD' | 'DEBIT_CARD' | 'ACH' | 'CHECK' | 'CASH' | 'PAYPAL' | 'STRIPE' | 'OTHER': Payment method used for refund (CASH, CHECK, CREDIT_CARD, BANK_TRANSFER, etc.) * `BANK_TRANSFER` - Bank Transfer * `CREDIT_CARD` - Credit Card * `DEBIT_CARD` - Debit Card * `ACH` - ACH/Direct Debit * `CHECK` - Check/Cheque * `CASH` - Cash * `PAYPAL` - PayPal * `STRIPE` - Stripe * `OTHER` - Other
    - `processor` string: Payment processor used (e.g., Stripe, PayPal, manual)
    - `transaction_tags` unknown
    - `memo` string: Optional description or notes for this refund payment
    - `metadata` unknown
    - `reconciled_bank_transactions` EntityReconciliationDetail[], required: Bank transactions this refund payment is reconciled to
      - `payment_type` string
      - `bank_transaction_id` string, uuid, required
      - `bank_transaction_date` string, date-time, required
      - `bank_transaction_amount_cents` integer, required
      - `bank_transaction_direction` string, required
      - `reconciled_amount_cents` integer, required
      - `reconciliation_link_id` string, uuid, required
      - `reconciled_at` string, date-time, required
      - `currency` string, required
      - `bank_account_name` string
      - `notes` string
    - `created_at` string, date-time, required: Timestamp when refund payment record was created
    - `updated_at` string, date-time, required: Timestamp when refund payment record was last updated
  - `document` DocumentFileUrl, required: Serializer for document file URL with metadata.
    - `url` string, uri, required: Presigned URL for document download
    - `expires_in` integer, required: Seconds until URL expires
    - `document_id` string, uuid, required: Document UUID
    - `file_name` string, required: Original document filename
    - `file_size` integer, required: File size in bytes
    - `mime_type` string, required: MIME type of the document
  - `currency` 'EUR' | 'GBP' | 'USD' | 'SEK' | 'NOK' | 'DKK' | 'ISK' | 'MYR' | 'SGD': Three-letter ISO 4217 currency code (EUR, GBP, USD) * `EUR` - Euro * `GBP` - British Pound * `USD` - US Dollar * `SEK` - Swedish Krona * `NOK` - Norwegian Krone * `DKK` - Danish Krone * `ISK` - Icelandic Króna * `MYR` - Malaysian Ringgit * `SGD` - Singapore Dollar
  - `created_at` string, date-time, required: Refund creation timestamp
  - `updated_at` string, date-time, required: Last update timestamp

## Other responses

- `400`: Validation errors in request data
- `401`: Authentication required - missing or invalid API key
- `403`: Permission denied - insufficient privileges
- `404`: Resource not found
- `409`: Conflict - resource already exists or invalid state transition
- `422`: Unprocessable entity - business logic validation failed
- `500`: Internal server error

---

[API](https://skmtc.dev/thredfi/apis/thredfi-accounting-platform-api.md) - [All operations](https://skmtc.dev/thredfi/apis/thredfi-accounting-platform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/thredfi/apis/thredfi-accounting-platform-api/revisions/0c1918254db3?raw)