# Refund a contract

`POST https://app.shuttleglobal.com/c/api/instances/{instance_key}/contracts/{contract_id}/refund`

You can refund a contract, which allows you to refund multiple transactions at once for recurring 
payments / subscriptions.

## Authentication

- basicAuth: Basic Authentication using secret key
- bearerAuth: OAuth 2.0 Bearer Token Authentication

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `contract_id` | path | string | yes | The contract's ID (`co_...`), or the `alt_key` you gave it. |

## Request body (`application/json`), required

- `refund` (object)
  - `amount` (string): (Optional) The amount of the refund as a string e.g., "10". The amount should not have commas and use a `.` as a decimal separator. If omitted, the entire unrefunded amount of the contract will be refunded.
  - `legal_entities` (array of object): (Optional - enterprise) This field is an ALTERNATIVE to `amount`. For contracts splitting payments into multiple entities, this allows you to specify which legal_entities are refunded.
    - `code` (string, required): The code of the legal entity.
    - `amount` (string): (Optional) The amount to refund. If omitted, all transactions for this entity will be refunded.
  - `reason` (string): (Optional) The reason for the refund (free text)
  - `manual` (boolean): (Optional) Set to true if you do not want to process the refund via the gateway, but simply record that a refund was performed offline.
  - `validate_only` (boolean): (Optional) Set to true if you do not want to perform the refund, just check to see what would be refunded.

## Responses

### 200: Refund processed

```json
{
  "refund_candidates": [
    {
      "source_transaction": "tr_11842_11072",
      "amount": 10
    }
  ]
}
```

### 400: Bad request

```json
{
  "code": "string",
  "message": "string"
}
```

### 401: Unauthorised: the API key is missing or not valid

```json
{
  "code": "UNAUTHORIZED",
  "message": "Unauthorised"
}
```

## Example request

```sh
curl --request POST \
  --url https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/contracts/CONTRACT_ID/refund \
  --header 'Authorization: Basic <base64 of SECRET_KEY:>' \
  --header 'Content-Type: application/json' \
  --data '{
  "refund": {
    "amount": "15.00",
    "reason": "Subscription cancelled",
    "manual": false,
    "validate_only": false
  }
}'
```

Reference page: https://docs.shuttleglobal.com/platforms/reference/operations/refundcontract/