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

# Issue a refund against an order

# 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": {
      "post": {
        "tags": [
          "Order"
        ],
        "summary": "Issue a refund against an order",
        "operationId": "createRefund",
        "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 to issue a refund against."
          }
        ],
        "requestBody": {
          "description": "Refund to be issued",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Refund"
              },
              "example": {
                "RefundReference": "YourUniqueReference",
                "Amount": 1.23
              }
            }
          }
        },
        "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"
                  }
                }
              }
            }
          },
          "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"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "Code": "ORDER_NOT_FOUND",
                  "Message": "No order exists for order ID cc7236aa-d11b-436c-a29c-d26cecadc847"
                }
              }
            }
          },
          "409": {
            "description": "Conflict - The refund cannot be processed at this time due to the order state, but may be tried again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "AlreadyCaptured": {
                    "value": {
                      "Code": "ChargebackExists",
                      "Message": "A refund cannot be submitted because there is a chargeback issued against the order."
                    }
                  },
                  "AlreadyDeclined": {
                    "value": {
                      "Code": "OrderStateInvalid",
                      "Message": "The order was not in the correct state - it must be either PROCESSED or DECLINED to initiate a refund"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "Code": "REFUND_FAILED",
                  "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
  }
}
```