FlintflintDocs

Refunds

Refunds return funds to a buyer for an order or a specific payment intent. Target either an order_id or a payment_intent_id (or both, if the payment intent belongs to that order), and refund the full remaining refundable amount or a partial amount. Refunds require a previously succeeded payment, and funds are returned to the original payment method.

Refunds fit the orders-first model: when you refund against an order, Flint recalculates the order's refunded and balance amounts and transitions the order status automatically, so order state stays the source of truth. Each refund carries a reason (requested_by_customer, duplicate, or fraudulent) and a status you can track from pending through completion or failure.

For how refunds interact with order lifecycle and payments, see the Orders-first guide.

Endpoints

List refunds#

GET/v1/refundsRequires scope: commerce.refunds.read or commerce.refunds.write

Returns a paginated list of refunds for the authenticated merchant.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

order_idstring

Filter by order ID.

payment_intent_idstring

Filter by payment intent ID.

customer_idstring

Filter by customer ID.

statusenum

Filter by refund status.

pendingin_transitsucceededfailedrequires_actioncanceledpartially_succeeded
reasonarray of enum

Repeat the parameter to filter by multiple refund reasons.

duplicatefraudulentrequested_by_customerdefective_productwrong_item_shippednever_receivednot_as_describedarrived_too_latecustomer_changed_mindbetter_price_foundaccidental_orderother
refund_methodenum

Filter by refund method.

original_payment
min_amountinteger

Inclusive lower bound in minor units. Requires currency.

max_amountinteger

Inclusive upper bound in minor units. Requires currency.

currencystring

ISO 4217 currency for min_amount and max_amount.

external_reference_idstring

Exact-match filter on the caller-owned external reference ID.

return_idstring

Filter by linked Return ID.

return_resolution_idstring

Filter by linked ReturnResolution ID.

querystring

Search across refund_id, external_reference_id, and reason_message.

sort_byenum

Sort field.

created_atupdated_atamount
sort_directionenum

Sort direction.

ascdesc
created_afterstring

RFC3339 lower bound for created_at.

created_beforestring

RFC3339 upper bound for created_at.

updated_afterstring

RFC3339 lower bound for updated_at.

updated_beforestring

RFC3339 upper bound for updated_at.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl https://api.withflintpay.com/v1/refunds \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "refund_id": "ref_123",
      "amount_money": {
        "amount": 1000,
        "currency": "USD"
      },
      "refunded_tip_money": {
        "amount": 100,
        "currency": "USD"
      },
      "status": "succeeded",
      "reason": "requested_by_customer",
      "metadata": {
        "ticket_id": "tkt_123"
      },
      "merchant_id": "mer_123",
      "order_id": "ord_123",
      "payment_intent_id": "pi_123",
      "refund_method": "original_payment",
      "customer_id": "cus_123",
      "payment_refunds": [
        {
          "payment_intent_id": "pi_123",
          "amount_money": {
            "amount": 1000,
            "currency": "USD"
          },
          "refunded_tip_money": {
            "amount": 100,
            "currency": "USD"
          },
          "status": "succeeded"
        }
      ],
      "created_at": "2026-03-17T14:30:00Z",
      "updated_at": "2026-03-17T14:30:00Z"
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create refund#

POST/v1/refundsIdempotentRequires scope: commerce.refunds.write

Creates a refund for an order or payment intent. This is a financial operation.

Request body
amount_moneyobject

Monetary amount represented as integer minor units plus an ISO 4217 currency code.

chargesarray of object
external_reference_idstring
line_itemsarray of object
metadatamap of string
order_idstring
payment_intent_idstring
reasonenumrequired
duplicatefraudulentrequested_by_customerdefective_productwrong_item_shippednever_receivednot_as_describedarrived_too_latecustomer_changed_mindbetter_price_foundaccidental_orderother
reason_messagestring
refund_methodenum
original_payment
tax_breakdown_refundsarray of object
Response · 201
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDREQUEST_TIMEOUTSERVICE_UNAVAILABLE
Bash
curl -X POST https://api.withflintpay.com/v1/refunds \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "reason": "requested_by_customer",
    "metadata": {
      "ticket_id": "tkt_123"
    },
    "order_id": "ord_123",
    "amount_money": {
      "amount": 1000,
      "currency": "USD"
    }
  }'
JSON
{
  "data": {
    "refund_id": "ref_123",
    "amount_money": {
      "amount": 1000,
      "currency": "USD"
    },
    "refunded_tip_money": {
      "amount": 100,
      "currency": "USD"
    },
    "status": "succeeded",
    "reason": "requested_by_customer",
    "metadata": {
      "ticket_id": "tkt_123"
    },
    "merchant_id": "mer_123",
    "order_id": "ord_123",
    "payment_intent_id": "pi_123",
    "refund_method": "original_payment",
    "customer_id": "cus_123",
    "payment_refunds": [
      {
        "payment_intent_id": "pi_123",
        "amount_money": {
          "amount": 1000,
          "currency": "USD"
        },
        "refunded_tip_money": {
          "amount": 100,
          "currency": "USD"
        },
        "status": "succeeded"
      }
    ],
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Get refund#

GET/v1/refunds/{refund_id}Requires scope: commerce.refunds.read or commerce.refunds.write

Returns a single refund by ID.

Path parameters
refund_idstringrequired

Flint refund ID.

Query parameters
expandarray of enum

Supported expansions: customer, order, payment_intent, payment_refunds.payment_intent. Expansion requires commerce.refunds.read plus the read scope for each expanded resource. Limits: at most 10 unique expand paths per request; path depth at most 2. To-many expansions are capped at 20 related objects per path. Send repeated expand parameters as the canonical form, for example expand=customer&expand=order. Comma-separated values, expand[]=customer, and numeric expand[0]=customer are accepted for common client compatibility.

customerorderpayment_intentpayment_refunds.payment_intent
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDDANGLING_EXPANSION_REFERENCEEXPANSION_DEPENDENCY_UNAVAILABLEEXPANSION_RESOLUTION_FAILEDINSUFFICIENT_SCOPEINTERNAL_ERRORINVALID_API_KEYINVALID_EXPANDINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/refunds/ref_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Update refund#

PATCH/v1/refunds/{refund_id}IdempotentRequires scope: commerce.refunds.write

Updates refund metadata.

Path parameters
refund_idstringrequired

Flint refund ID.

Request body
metadatamap of string
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X PATCH https://api.withflintpay.com/v1/refunds/ref_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "metadata": {
      "reviewed_by": "ops"
    }
  }'
JSON
{
  "data": {
    "refund_id": "ref_123",
    "amount_money": {
      "amount": 1000,
      "currency": "USD"
    },
    "refunded_tip_money": {
      "amount": 100,
      "currency": "USD"
    },
    "status": "succeeded",
    "reason": "requested_by_customer",
    "metadata": {
      "ticket_id": "tkt_123"
    },
    "merchant_id": "mer_123",
    "order_id": "ord_123",
    "payment_intent_id": "pi_123",
    "refund_method": "original_payment",
    "customer_id": "cus_123",
    "payment_refunds": [
      {
        "payment_intent_id": "pi_123",
        "amount_money": {
          "amount": 1000,
          "currency": "USD"
        },
        "refunded_tip_money": {
          "amount": 100,
          "currency": "USD"
        },
        "status": "succeeded"
      }
    ],
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}
Rate this doc