# Update match

Update match status or allocated amount.

Partial update. This call cannot change which invoice or bank line is linked. It only updates matchedAmount, status, or metadata on an existing row, and the path is the match UUID from List, Create, or a webhook — not from the product.

status cancelled on an active or confirmed match reverses the payment with reason other, exactly like Reverse match: the row is kept as cancelled with who and when, and one invoice.settlement_changed webhook is sent. Use Reverse match to give the real reason or match the right transaction in the same step. pending_review can be confirmed or rejected. Changing matchedAmount on an active match recalculates invoice and transaction remaining amounts.

To change the amount on the same pair, list the match then send matchedAmount. To confirm a suggestion, list pending_review then send status confirmed. To deny a suggestion, Create match with status rejected and the invoice number plus transaction code. To undo an auto-match, Reconcile transaction with unlink_all on the transaction code. To point the payment at another invoice, unlink then Create match with the new invoice number. Do not use Reconcile save; that is the Invunion workbench.

## See also

- [Matches](https://www.invunion.com/knowledge-base/api/matches/). Which call to use for each change.
- [List matches](https://www.invunion.com/knowledge-base/api/list-matches/) (`GET /api/v1/matches`). Get the UUID by invoice number and transaction code.
- [Create match](https://www.invunion.com/knowledge-base/api/create-match/) (`POST /api/v1/matches`). Allocate, or deny a pair with status rejected.
- [Reconcile transaction](https://www.invunion.com/knowledge-base/api/reconcile-transaction/) (`POST /api/v1/transactions/:code/reconcile`). Undo every live match on a bank line with unlink_all.
- [Reverse match](https://www.invunion.com/knowledge-base/api/reverse-match/) (`POST /api/v1/matches/:id/reverse`). Reverse a wrong payment with a reason.
- [Delete match](https://www.invunion.com/knowledge-base/api/cancel-match/) (`DELETE /api/v1/matches/:id`). Delete a suggested, rejected, or cancelled row.

- HTTP method: `PUT`
- Path: `/api/v1/matches/:id`
- URL: `https://api.invunion.com/api/v1/matches/:id`
- Required scope: `matches:write`
- Idempotency-Key header: accepted. See https://www.invunion.com/knowledge-base/api/idempotency/
- HTML docs: https://www.invunion.com/knowledge-base/api/update-match/
- Markdown docs: https://www.invunion.com/knowledge-base/api/update-match.md

## Path parameters

| Name | Type | Required | Description | Allowed values | Example |
| --- | --- | --- | --- | --- | --- |
| `id` | string, no maximum | required | Match UUID. |  | `1c9e6679-7425-40de-944b-e07fc1f90ae7` |


## Body parameters

| Name | Type | Required | Description | Allowed values | Example |
| --- | --- | --- | --- | --- | --- |
| `status` | string, no maximum | optional | New match status. | `active`, `cancelled`, `confirmed`, `rejected` |  |
| `matchedAmount` | number | optional | New positive allocated amount. |  | `800` |
| `metadata` | object | optional | JSON object. At most 32 keys, nested depth 3, 8 KB serialized, and 64-character key names. Keys __proto__, constructor, and prototype are rejected. |  | `{"reason":"partial bank fee"}` |

## Errors

| Error | HTTP code | Description |
| --- | --- | --- |
| `Missing Bearer token` | `401` | The Authorization header is missing or is not a Bearer token. |
| `Invalid or revoked API key` | `401` | The API key is unknown, malformed, expired, or has been revoked. |
| `API key is missing scope matches:write` | `403` | The key does not include matches:write. A write scope does not imply the matching read scope. |
| `Too many requests, please try again later` | `429` | More than 100 requests in one minute from this API key or IP address. Wait for the Retry-After header (seconds) and retry. |
| `Validation failed` | `400` | The body failed schema validation. details lists field and message. |
| `Match not found` | `404` | No match with this UUID exists in the authenticated tenant. |
| `Internal server error` | `500` | Unexpected server error. The JSON body includes correlationId. Retry with backoff. |
| `Idempotency-Key must be 8-255 characters: letters, digits, ".", "_", ":" or "-".` | `400` | The Idempotency-Key header is present but malformed. |
| `A request with this Idempotency-Key is still being processed.` | `409` | The first request with this key has not finished. Retry after it completes. code is idempotency_in_progress. |
| `This Idempotency-Key was already used with a different request body.` | `422` | Send a new key for a different request. code is idempotency_key_reuse. |

## Request (curl)

```bash
curl --request PUT \
  --url https://api.invunion.com/api/v1/matches/1c9e6679-7425-40de-944b-e07fc1f90ae7 \
  --header 'accept: application/json' \
  --header 'authorization: Bearer uk_live_YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{
  "status": "cancelled"
}'
```

## Request (Python)

```python
import requests

url = "https://api.invunion.com/api/v1/matches/1c9e6679-7425-40de-944b-e07fc1f90ae7"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer uk_live_YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "status": "cancelled"
}
response = requests.put(url, json=payload, headers=headers)
print(response.json())
```

## Request (Ruby)

```ruby
require 'net/http'
require 'json'
require 'uri'

uri = URI("https://api.invunion.com/api/v1/matches/1c9e6679-7425-40de-944b-e07fc1f90ae7")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Put.new(uri)
request['Accept'] = 'application/json'
request['Authorization'] = 'Bearer uk_live_YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = "{\n  \"status\": \"cancelled\"\n}"
response = http.request(request)
puts response.body
```

## Request (JavaScript)

```javascript
const response = await fetch("https://api.invunion.com/api/v1/matches/1c9e6679-7425-40de-944b-e07fc1f90ae7", {
  method: "PUT",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer uk_live_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "status": "cancelled"
}),
});
const data = await response.json();
```

## Request (Go)

```go
package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	payload := []byte(`{
  "status": "cancelled"
}`)
	req, err := http.NewRequest("PUT", "https://api.invunion.com/api/v1/matches/1c9e6679-7425-40de-944b-e07fc1f90ae7", bytes.NewBuffer(payload))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Authorization", "Bearer uk_live_YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}
```

## Request (Node)

```javascript
const response = await fetch("https://api.invunion.com/api/v1/matches/1c9e6679-7425-40de-944b-e07fc1f90ae7", {
  method: "PUT",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer uk_live_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "status": "cancelled"
}),
});
console.log(await response.json());
```

## Success (200)

```json
{
  "success": true,
  "message": "Match cancelled"
}
```