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/refunds

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.

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
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/refundsIdempotent

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
Response · 201
dataobjectrequired
metaobject
request_idstring
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}

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
Bash
curl https://api.withflintpay.com/v1/refunds/ref_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Update refund#

PATCH/v1/refunds/{refund_id}Idempotent

Updates refund metadata.

Path parameters
refund_idstringrequired

Flint refund ID.

Request body
metadatamap of string
Response · 200
dataobjectrequired
metaobject
request_idstring
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