# Change a transaction

`PUT /api/v1/vaults/{vault}/possessions/{possession}/transactions/{transaction}`

Change what a transaction says, under the rules that recorded it.

A field left out of the request keeps its value, and a field sent as null is cleared. The acquisition date and price of the possession follow, since they are read from its transactions.

The change is written to the account log.

## Parameters

- `vault` (string, required): The vault the possession is kept in, named either by the readable name it reports as slug or by its id. A vault of another account answers 404.
- `possession` (uuid, required): The id of the possession. A possession of another vault or of another account answers 404.
- `transaction` (uuid, required): The id of the transaction. A transaction of another possession answers 404.
- `type` (string, optional): What happened, one of the eleven types.
- `occurred_on` (string, optional): The day it happened, written as 2005-03-14, or null when it is not known.
- `counterparty` (string, optional): Who was on the other side, as text, up to 255 characters.
- `amount` (number, optional): The price or the amount. Zero or more, up to 9999999999.99. A figure below zero is refused with “Write an amount of zero or more.”
- `tax` (number, optional): The tax paid. Zero or more, up to 9999999999.99. A figure below zero is refused with “Write an amount of zero or more.”
- `fees` (number, optional): The fees paid. Zero or more, up to 9999999999.99. A figure below zero is refused with “Write an amount of zero or more.”
- `shipping` (number, optional): The shipping paid. Zero or more, up to 9999999999.99. A figure below zero is refused with “Write an amount of zero or more.”
- `entered_total` (number, optional): The total, when it is not the sum of the four figures. Zero or more, up to 9999999999.99. A figure below zero is refused with “Write an amount of zero or more.”
- `currency` (string, optional): The currency of every figure. Required once a figure is set, else refused with “Choose the currency of these amounts.”
- `reference` (string, optional): An invoice, receipt or deed number, up to 255 characters.
- `source_url` (string, optional): A full web address where the transaction can be checked.
- `note` (string, optional): Anything worth remembering about it.

## Returns

The transaction object as it now reads. A transaction of another possession or of another account answers 404.

- `data` (object): The possession transaction.
- `data.type` (string): Always possession_transaction. It names the kind of record, so a caller holding several kinds can tell them apart without looking at where they came from.
- `data.id` (string): The id of this record, as a string even when it reads as a number. It is what every endpoint naming this record takes.
- `data.attributes` (object): Everything the record holds.
- `data.attributes.type` (string): What happened: purchase, sale, exchange, gift_received, gift_given, inheritance, refund, fee, tax, shipping or other.
- `data.attributes.changes_ownership` (boolean): Whether the possession changed hands, true for the first six types and false for the money only ones.
- `data.attributes.is_acquisition` (boolean): Whether this is the transaction that brought the possession in: its earliest purchase, exchange, gift received or inheritance, undated ones first.
- `data.attributes.occurred_on` (string): The day it happened, written as 2005-03-14, or null when it is not known.
- `data.attributes.counterparty` (string): Who was on the other side, as text, or null.
- `data.attributes.amount` (string): The price or the amount, as a string with two decimals, or null.
- `data.attributes.tax` (string): The tax paid, or null.
- `data.attributes.fees` (string): The fees paid, or null.
- `data.attributes.shipping` (string): The shipping paid, or null.
- `data.attributes.entered_total` (string): The total typed in, which overrides the sum of the four figures, or null.
- `data.attributes.total` (string): The total of the transaction: the entered total, else the sum of the figures set, else null.
- `data.attributes.total_source` (string): Where the total comes from: entered, sum or unknown.
- `data.attributes.currency` (string): The currency of every figure, in lower case, or null when no figure is set. Nothing is ever converted.
- `data.attributes.reference` (string): An invoice, receipt or deed number, or null.
- `data.attributes.source_url` (string): Where the transaction can be checked, or null.
- `data.attributes.note` (string): Anything worth remembering about it, or null.
- `data.attributes.documents` (array): The invoices, receipts and deeds attached to it, oldest first.
- `data.attributes.documents[]` (object): One document.
- `data.attributes.documents[].id` (uuid): The id of the file, which is what removing the document takes.
- `data.attributes.documents[].name` (string): The name of the file as it was uploaded.
- `data.attributes.documents[].mime_type` (string): The kind of the file, such as application/pdf.
- `data.attributes.documents[].size_in_bytes` (integer): How much storage the file takes.
- `data.attributes.created_at` (timestamp): When the transaction was recorded, as a count of seconds since 1970.
- `data.attributes.updated_at` (timestamp): When it last changed, as a count of seconds, or null.
- `data.links` (object): Where to find this record.
- `data.links.self` (string): The absolute address this record is read from.
- `data.links.web` (string): The Transactions section of the possession in the application, which opens for somebody signed in rather than for a key. It is the link to give a person.

## Rate limit

Sixty requests per minute, per user, shared by every key and device. Every answer carries the budget left in `X-RateLimit-Remaining`.

## Request

```sh
curl https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions/9c4e2a71-5b38-4f06-8d1e-2a7f3c6b9e15/transactions/3f8a1c62-7d94-4b2e-a5c0-6e9b2d4f1a83 \
  -X PUT \
  -H "Authorization: Bearer $MONICA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "shipping": 6
  }'
```

```javascript
const response = await fetch('https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions/9c4e2a71-5b38-4f06-8d1e-2a7f3c6b9e15/transactions/3f8a1c62-7d94-4b2e-a5c0-6e9b2d4f1a83', {
  method: 'PUT',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    shipping: 6,
  }),
})
const data = await response.json()
```

```php
$response = Http::withToken($token)->put('https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions/9c4e2a71-5b38-4f06-8d1e-2a7f3c6b9e15/transactions/3f8a1c62-7d94-4b2e-a5c0-6e9b2d4f1a83', [
    'shipping' => 6,
]);
```

## Response

`200`

```json
{
    "data": {
        "type": "possession_transaction",
        "id": "3f8a1c62-7d94-4b2e-a5c0-6e9b2d4f1a83",
        "attributes": {
            "type": "purchase",
            "changes_ownership": true,
            "is_acquisition": true,
            "occurred_on": "2005-03-14",
            "counterparty": "Dundies Inc.",
            "amount": "40.00",
            "tax": "3.20",
            "fees": null,
            "shipping": "6.00",
            "entered_total": null,
            "total": "49.20",
            "total_source": "sum",
            "currency": "usd",
            "reference": "Invoice 4021",
            "source_url": null,
            "note": "For Kevin, the hottest in the office award.",
            "documents": [
                {
                    "id": "5c2e8f14-9a63-4d7b-b0e1-3f6a9c4d2e58",
                    "name": "Invoice 4021.pdf",
                    "mime_type": "application/pdf",
                    "size_in_bytes": 88000
                }
            ],
            "created_at": 1761436800,
            "updated_at": 1761436800
        },
        "links": {
            "self": "https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions/9c4e2a71-5b38-4f06-8d1e-2a7f3c6b9e15/transactions/3f8a1c62-7d94-4b2e-a5c0-6e9b2d4f1a83",
            "web": "https://my.monicahq.com/vaults/dunder-mifflin/possessions/9c4e2a71-5b38-4f06-8d1e-2a7f3c6b9e15/transactions"
        }
    }
}
```
