Mercury: Update transaction metadata
Mercury transactions.updateTransaction: arguments, response, policy and SDK examples.
← Transactions operations · Get started
Operation mercury.updatetransaction
Provider route: PATCH /transaction/{transactionId}. Alter supplies the connection’s credentials and routing.
Call through Alter
Section titled “Call through Alter”Install @alter-ai/sdk @alter-ai/mercury with npm, or alter-sdk-mercury with pip. Supply your connected customer’s grant ID and the arguments described below.
import { App } from "@alter-ai/sdk";import { MercuryIntegration } from "@alter-ai/mercury";
async function execute(input: Parameters<MercuryIntegration["transactions"]["updateTransaction"]>[0]) { const app = new App({ apiKey: process.env.ALTER_API_KEY! }); try { const provider = new MercuryIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! }); const call = await provider.transactions.updateTransaction(input); const result = await call.wait(); return result.bodyJson(); } finally { await app.close(); }}import osfrom alter_sdk import Appfrom alter_sdk_mercury import MercuryIntegration
async def execute(arguments): async with App(api_key=os.environ["ALTER_API_KEY"]) as app: provider = MercuryIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]}) call = await provider.transactions.update_transaction(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
path | object | Required within parent | Additional keys: not allowed |
path.transactionId | string | Required within parent | ID for this transaction Format: uuid |
body | Model | Optional | Expand Update transaction metadata — request body — body |
Referenced models: Update transaction metadata — request body — body
Response
Section titled “Response”Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | Model | Root | Expand Get transaction by ID — response body |
Referenced models: Get transaction by ID — response body
Schemas
Section titled “Schemas”27 more schemas are linked from the tables above, on the schema pages.
Update transaction metadata — request body — body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Request body for updating transaction metadata via the public API Additional keys: not allowed |
categoryId | JSON | Optional | |
categoryId (allOf 1) | Model | All variants apply | Expand Update transaction metadata — request body — body category Id value |
categoryId (allOf 2) | JSON | All variants apply | How to update the transaction's category. Omit field to keep current, send null to clear, send ID to set. |
note | JSON | Optional | |
note (allOf 1) | Model | All variants apply | Expand Update transaction metadata — request body — body note value |
note (allOf 2) | JSON | All variants apply | How to update the transaction's note. Omit field to keep current, send null/empty to clear, send text to set. |
Referenced models: Update transaction metadata — request body — body category Id value, Update transaction metadata — request body — body note value
Get a card — response body — category Locks item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | string | Root | Known values: Other, Advertising, Airlines, AlcoholAndBars, BooksAndNewspaper, CarRental, Charity, Clothing, Conferences, Education, Electronics, Entertainment, FacilitiesExpenses, Fees, FoodDelivery, FuelAndGas, Gambling, GovernmentServices, Grocery, GroundTransportation, Insurance, InternetAndTelephone, Legal, Lodging, Medical, Memberships, OfficeSupplies, OtherTravel, Parking, Political, ProfessionalServices, Restaurants, Retail, RideshareAndTaxis, Shipping, Software, Taxes, Utilities, VehicleExpenses |
Edit a category — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Represents an expense category for transaction classification. |
id | JSON | Required within parent | |
id (allOf 1) | string | All variants apply | ID for the category Format: uuid |
id (allOf 2) | JSON | All variants apply | The ID of the category |
name | string | Required within parent | The name of the category |
visibleForCardSpend | boolean | Required within parent | Whether this category is applicable to card transactions |
visibleForOther | boolean | Required within parent | Whether this category is applicable to all other transaction kinds |
visibleForReimbursements | boolean | Required within parent | Whether this category is applicable to expense reimbursement transactions |
Get transaction by ID — response body — currency Exchange Info converted From Amount, converted From Currency, converted To Amount, converted To Currency, exchange Rate, fee Amount, fee Percentage, fee Transaction Id converted From Amount, converted From Currency, converted To Amount, converted To Currency, exchange Rate, fee Amount, fee Percentage, fee Transaction Id
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
convertedFromAmount | JSON | Required within parent | |
convertedFromAmount (anyOf 1) | number | Alternative | Multiple of: 0.01 |
convertedFromAmount (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
convertedFromCurrency | JSON | Required within parent | |
convertedFromCurrency (allOf 1) | string | All variants apply | |
convertedToAmount | JSON | Required within parent | |
convertedToAmount (anyOf 1) | number | Alternative | Multiple of: 0.01 |
convertedToAmount (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
convertedToCurrency | JSON | Required within parent | |
convertedToCurrency (allOf 1) | string | All variants apply | |
exchangeRate | JSON | Required within parent | |
exchangeRate (anyOf 1) | number | Alternative | Exchange rate goes from "from currency" to "to currency" (ie from currency * exchange rate = to currency) Multiple of: 0.0001 |
exchangeRate (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
feeAmount | JSON | Required within parent | |
feeAmount (anyOf 1) | number | Alternative | Multiple of: 0.01 |
feeAmount (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
feePercentage | JSON | Required within parent | |
feePercentage (anyOf 1) | number | Alternative | Multiple of: 0.0001 |
feePercentage (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
feeTransactionId | JSON | Optional | |
feeTransactionId (anyOf 1) | JSON | Alternative | |
feeTransactionId (anyOf 1) (allOf 1) | string | All variants apply | ID for this transaction Format: uuid |
feeTransactionId (anyOf 2) | null | Alternative |
Get transaction by ID — response body — gl Allocations item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A GL code allocation on a transaction — a GL code name paired with the amount allocated to it. When a transaction is fully categorized, the amounts across all allocations sum to the transaction total. |
amount | JSON | Required within parent | |
amount (anyOf 1) | number | Alternative | The amount allocated to this GL code Multiple of: 0.01 |
amount (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
className | JSON | Optional | |
className (anyOf 1) | string | Alternative | The name of the class from the connected accounting integration, if assigned |
className (anyOf 2) | null | Alternative | |
departmentName | JSON | Optional | |
departmentName (anyOf 1) | string | Alternative | The name of the department from the connected accounting integration, if assigned |
departmentName (anyOf 2) | null | Alternative | |
description | JSON | Optional | |
description (anyOf 1) | string | Alternative | Optional user-provided description for this allocation |
description (anyOf 2) | null | Alternative | |
glCodeName | string | Required within parent | The name of the GL code from the connected accounting integration |
Get transaction by ID — response body — merchant amount, category, category Code, currency, id Merchant information for card transactions
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Merchant information for card transactions |
amount | JSON | Optional | |
amount (anyOf 1) | JSON | Alternative | |
amount (anyOf 1) (anyOf 1) | integer | Alternative | The transaction amount in the smallest unit of the merchant's currency (e.g., cents for USD/EUR, yen for JPY, fils for BHD). For debits this is negative, for credits positive. Use 'merchantCurrency' to determine the appropriate decimal scaling: most currencies use 2 decimal places (divide by 100), but JPY uses 0 (no division needed) and BHD/KWD/OMR use 3 (divide by 1000). This is useful for international transactions where the merchant charges in a currency different from the account currency. Nothing if not available. Format: int64 Maximum: 9223372036854776000 Minimum: -9223372036854776000 |
amount (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
amount (anyOf 2) | null | Alternative | |
category | JSON | Optional | |
category (anyOf 1) | JSON | Alternative | |
category (anyOf 1) (allOf 1) | Model | All variants apply | Expand Get a card — response body — category Locks item |
category (anyOf 1) (allOf 2) | JSON | All variants apply | Mercury category for the merchant (e.g., "Restaurants", "Software") |
category (anyOf 2) | null | Alternative | |
categoryCode | JSON | Optional | |
categoryCode (anyOf 1) | string | Alternative | 4-digit merchant category code (MCC) for card transactions |
categoryCode (anyOf 2) | null | Alternative | |
currency | JSON | Optional | |
currency (anyOf 1) | JSON | Alternative | |
currency (anyOf 1) (allOf 1) | string | All variants apply | |
currency (anyOf 1) (allOf 2) | JSON | All variants apply | ISO 4217 currency code of the merchant's currency (e.g., "EUR", "GBP", "JPY"). Nothing if not available. |
currency (anyOf 2) | null | Alternative | |
id | JSON | Optional | |
id (anyOf 1) | string | Alternative | Merchant ID for card transactions |
id (anyOf 2) | null | Alternative |
Referenced models: Get a card — response body — category Locks item
Get transaction by ID — response body — related Transactions item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A Public API version of RelatedTransactionData. |
accountId | JSON | Required within parent | |
accountId (allOf 1) | string | All variants apply | ID for a Mercury account. Format: uuid |
amount | JSON | Required within parent | |
amount (anyOf 1) | number | Alternative | Multiple of: 0.01 |
amount (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
id | JSON | Required within parent | |
id (allOf 1) | string | All variants apply | ID for this transaction Format: uuid |
relationKind | JSON | Required within parent | |
relationKind (allOf 1) | Model | All variants apply | Expand Get transaction by ID — response body — related Transactions item relation Kind string |
Referenced models: Get transaction by ID — response body — related Transactions item relation Kind string
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: mercury.updatetransaction. Catalog operation: mercury:updateTransaction. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.
Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.