---
updatedAt: 2025-08-26T19:55:10.000Z
agentTools:
  projectIndex: https://docs.withreach.com/llms.txt
---

# Retrieve a list of refunds for a given order ID

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Reach's Drop-In API",
    "description": "API definition for Reach's Drop-In API's",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.sandbox.withreach.com"
    },
    {
      "url": "https://api.withreach.com"
    }
  ],
  "tags": [
    {
      "name": "Order",
      "description": "Manage a Order within Reach."
    }
  ],
  "paths": {
    "/v1/orders/{OrderId}/refunds": {
      "get": {
        "tags": [
          "Order"
        ],
        "summary": "Retrieve a list of refunds for a given order id",
        "operationId": "getRefundList",
        "security": [
          {
            "basicAuth": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "OrderId",
            "schema": {
              "type": "string",
              "format": "uuid",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
              "minLength": 36,
              "maxLength": 36,
              "example": "cc7236aa-d11b-436c-a29c-d26cecadc847"
            },
            "required": true,
            "description": "Order ID containing the desired refund."
          }
        ],
        "responses": {
          "200": {
            "description": "Operation Successful",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refund"
                },
                "example": [
                  {
                    "RefundId": "d6ebf380-6dd5-422f-8ae9-e028f9e6da05",
                    "RefundReference": "YourUniqueReference",
                    "State": "INPROGRESS",
                    "Amount": 1.23,
                    "Times": {
                      "Created": "2022-08-19T15:22:32.782Z"
                    }
                  },
                  {
                    "RefundId": "b7008b5c-8f5c-4343-9494-8dc2289fcdee",
                    "RefundReference": "AnotherUniqueReference",
                    "State": "INPROGRESS",
                    "Amount": 3.21,
                    "Times": {
                      "Created": "2022-08-19T17:04:59.163Z"
                    }
                  }
                ]
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "Code": "VALIDATION_ERROR",
                  "Message": "Not a valid UUID"
                }
              }
            }
          },
          "401": {
            "description": "Authentication Required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "Authentication required error": {
                    "value": {
                      "Code": "AUTHENTICATION_REQUIRED",
                      "Message": "Username/password must be supplied to access this resource"
                    }
                  },
                  "Invalid username/password error": {
                    "value": {
                      "Code": "AUTHENTICATION_REQUIRED",
                      "Message": "Supplied username/password are invalid"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "Code": "NOT_AUTHORIZED",
                  "Message": "User is not permitted to access this resource"
                }
              }
            }
          },
          "500": {
            "description": "Server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "Code": "INTERNAL_SERVER_ERROR",
                  "Message": "Refund failed due to an unexpected error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Times": {
        "description": "Gives times of various order state transitions",
        "type": "object",
        "properties": {
          "Created": {
            "description": "The RFC 3339 timestamp at which the order was created.",
            "type": "string"
          },
          "Authorized": {
            "description": "The RFC 3339 timestamp at which the order’s payment was authorized. This will be null if the payment has not yet been authorized or the payment method used for the order does not support pre-authorization (eg. Boleto).",
            "type": "string"
          },
          "Processed": {
            "description": "The RFC 3339 timestamp at which the order's payment was processed. This will be null if the order's payment has not been processed yet or has failed to be processed.",
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "Code": {
            "description": "Identifying code of a presented error.",
            "type": "string"
          },
          "Message": {
            "description": "Details of a presented error.",
            "type": "string"
          },
          "FieldErrors": {
            "description": "A list of field errors.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FieldErrors"
            }
          }
        },
        "required": [
          "Code",
          "Message"
        ]
      },
      "FieldErrors": {
        "type": "object",
        "properties": {
          "Field": {
            "description": "Field associated with the error.",
            "type": "string"
          },
          "Code": {
            "description": "Identifying code of a presented field error.",
            "type": "string"
          },
          "Message": {
            "description": "Details of a presented field error.",
            "type": "string"
          }
        },
        "required": [
          "Field",
          "Code",
          "Message"
        ]
      },
      "Refund": {
        "type": "object",
        "properties": {
          "RefundId": {
            "description": "Reach-generated unique id of a refund",
            "type": "string",
            "format": "uuid",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
            "minLength": 36,
            "maxLength": 36,
            "readOnly": true
          },
          "Amount": {
            "description": "Amount of the refund. Must be at most the total value of the original order, minus any other refunds.",
            "type": "number",
            "format": "float"
          },
          "State": {
            "description": "Refund state. See: https://docs.withreach.com/docs/states-and-events#refund-states",
            "type": "string",
            "enum": [
              "INPROGRESS",
              "SUCCEEDED",
              "FAILED"
            ],
            "readOnly": true
          },
          "RefundReference": {
            "description": "A merchant-supplied reference ID. This must be unique within the order for the given refund",
            "type": "string",
            "minLength": 1
          },
          "Times": {
            "readOnly": true,
            "allOf": [
              {
                "$ref": "#/components/schemas/Times"
              }
            ]
          }
        }
      }
    },
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic"
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  }
}
```