APIMethodRefundList

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/stripe/main/json-schema/stripe-apimethod-refund-list-schema.json",
  "title": "APIMethodRefundList",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/stripe-refunds-api-openapi.yml#/components/schemas/APIMethodRefundList",
  "type": "object",
  "required": [
    "data",
    "has_more",
    "object",
    "url"
  ],
  "properties": {
    "data": {
      "items": {
        "$ref": "#/$defs/refund"
      },
      "type": "array"
    },
    "has_more": {
      "description": "True if this list has another page of items after this one that can be fetched.",
      "type": "boolean"
    },
    "object": {
      "description": "String representing the object's type. Objects of the same type share the same value. Always has the value `list`.",
      "enum": [
        "list"
      ],
      "type": "string"
    },
    "url": {
      "description": "The URL where this list can be accessed.",
      "maxLength": 5000,
      "pattern": "^/v1/refunds",
      "type": "string"
    }
  },
  "$defs": {
    "balance_transaction": {
      "type": "object",
      "description": "Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.",
      "x-ae-placeholder": true
    },
    "charge": {
      "type": "object",
      "description": "Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.",
      "x-ae-placeholder": true
    },
    "payment_intent": {
      "type": "object",
      "description": "Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.",
      "x-ae-placeholder": true
    },
    "refund": {
      "description": "Refund objects allow you to refund a previously created charge that isn't\nrefunded yet. Funds are refunded to the credit or debit card that's\ninitially charged.\n\nRelated guide: [Refunds](https://stripe.com/docs/refunds)",
      "properties": {
        "amount": {
          "description": "Amount, in cents (or local equivalent).",
          "type": "integer"
        },
        "balance_transaction": {
          "anyOf": [
            {
              "maxLength": 5000,
              "type": "string"
            },
            {
              "$ref": "#/$defs/balance_transaction"
            }
          ],
          "description": "Balance transaction that describes the impact on your account balance.",
          "x-expansionResources": {
            "oneOf": [
              {
                "$ref": "#/$defs/balance_transaction"
              }
            ]
          }
        },
        "charge": {
          "anyOf": [
            {
              "maxLength": 5000,
              "type": "string"
            },
            {
              "$ref": "#/$defs/charge"
            }
          ],
          "description": "ID of the charge that's refunded.",
          "x-expansionResources": {
            "oneOf": [
              {
                "$ref": "#/$defs/charge"
              }
            ]
          }
        },
        "created": {
          "description": "Time at which the object was created. Measured in seconds since the Unix epoch.",
          "format": "unix-time",
          "type": "integer"
        },
        "currency": {
          "description": "Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).",
          "type": "string"
        },
        "description": {
          "description": "An arbitrary string attached to the object. You can use this for displaying to users (available on non-card refunds only).",
          "maxLength": 5000,
          "type": "string"
        },
        "destination_details": {
          "$ref": "#/$defs/refund_destination_details"
        },
        "failure_balance_transaction": {
          "anyOf": [
            {
              "maxLength": 5000,
              "type": "string"
            },
            {
              "$ref": "#/$defs/balance_transaction"
            }
          ],
          "description": "After the refund fails, this balance transaction describes the adjustment made on your account balance that reverses the initial balance transaction.",
          "x-expansionResources": {
            "oneOf": [
              {
                "$ref": "#/$defs/balance_transaction"
              }
            ]
          }
        },
        "failure_reason": {
          "description": "Provides the reason for the refund failure. Possible values are: `lost_or_stolen_card`, `expired_or_canceled_card`, `charge_for_pending_refund_disputed`, `insufficient_funds`, `declined`, `merchant_request`, or `unknown`.",
          "maxLength": 5000,
          "type": "string"
        },
        "id": {
          "description": "Unique identifier for the object.",
          "maxLength": 5000,
          "type": "string"
        },
        "instructions_email": {
          "description": "For payment methods without native refund support (for example, Konbini, PromptPay), provide an email address for the customer to receive refund instructions.",
          "maxLength": 5000,
          "type": "string"
        },
        "metadata": {
          "additionalProperties": {
            "maxLength": 500,
            "type": "string"
          },
          "description": "Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.",
          "type": [
            "object",
            "null"
          ]
        },
        "next_action": {
          "$ref": "#/$defs/refund_next_action"
        },
        "object": {
          "description": "String representing the object's type. Objects of the same type share the same value.",
          "enum": [
            "refund"
          ],
          "type": "string"
        },
        "payment_intent": {
          "anyOf": [
            {
              "maxLength": 5000,
              "type": "string"
            },
            {
              "$ref": "#/$defs/payment_intent"
            }
          ],
          "description": "ID of the PaymentIntent that's refunded.",
          "x-expansionResources": {
            "oneOf": [
              {
                "$ref": "#/$defs/payment_intent"
              }
            ]
          }
        },
        "reason": {
          "description": "Reason for the refund, which is either user-provided (`duplicate`, `fraudulent`, or `requested_by_customer`) or generated by Stripe internally (`expired_uncaptured_charge`).",
          "enum": [
            "duplicate",
            "expired_uncaptured_charge",
            "fraudulent",
            "requested_by_customer"
          ],
          "type": [
            "string",
            "null"
          ],
          "x-stripeBypassValidation": true
        },
        "receipt_number": {
          "description": "This is the transaction number that appears on email receipts sent for this refund.",
          "maxLength": 5000,
          "type": [
            "string",
            "null"
          ]
        },
        "source_transfer_reversal": {
          "anyOf": [
            {
              "maxLength": 5000,
              "type": "string"
            },
            {
              "$ref": "#/$defs/transfer_reversal"
            }
          ],
          "description": "The transfer reversal that's associated with the refund. Only present if the charge came from another Stripe account.",
          "x-expansionResources": {
            "oneOf": [
              {
                "$ref": "#/$defs/transfer_reversal"
              }
            ]
          }
        },
        "status": {
          "description": "Status of the refund. This can be `pending`, `requires_action`, `succeeded`, `failed`, or `canceled`. Learn more about [failed refunds](https://stripe.com/docs/refunds#failed-refunds).",
          "maxLength": 5000,
          "type": [
            "string",
            "null"
          ]
        },
        "transfer_reversal": {
          "anyOf": [
            {
              "maxLength": 5000,
              "type": "string"
            },
            {
              "$ref": "#/$defs/transfer_reversal"
            }
          ],
          "description": "This refers to the transfer reversal object if the accompanying transfer reverses. This is only applicable if the charge was created using the destination parameter.",
          "x-expansionResources": {
            "oneOf": [
              {
                "$ref": "#/$defs/transfer_reversal"
              }
            ]
          }
        }
      },
      "required": [
        "amount",
        "created",
        "currency",
        "id",
        "object"
      ],
      "title": "Refund",
      "type": "object",
      "x-expandableFields": [
        "balance_transaction",
        "charge",
        "destination_details",
        "failure_balance_transaction",
        "next_action",
        "payment_intent",
        "source_transfer_reversal",
        "transfer_reversal"
      ],
      "x-resourceId": "refund"
    },
    "refund_destination_details": {
      "type": "object",
      "description": "Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.",
      "x-ae-placeholder": true
    },
    "refund_next_action": {
      "type": "object",
      "description": "Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.",
      "x-ae-placeholder": true
    },
    "transfer_reversal": {
      "type": "object",
      "description": "Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.",
      "x-ae-placeholder": true
    }
  }
}