Skip to content

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.

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 os
from alter_sdk import App
from 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()
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
pathobjectRequired within parentAdditional keys: not allowed
path.transactionIdstringRequired within parentID for this transaction
Format: uuid
bodyModelOptionalExpand Update transaction metadata — request body — body

Referenced models: Update transaction metadata — request body — body

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

FieldTypePresenceDescription and constraints
$ModelRootExpand Get transaction by ID — response body

Referenced models: Get transaction by ID — response body

27 more schemas are linked from the tables above, on the schema pages.

Update transaction metadata — request body — body
FieldTypePresenceDescription and constraints
$objectRootRequest body for updating transaction metadata via the public API
Additional keys: not allowed
categoryIdJSONOptional
categoryId (allOf 1)ModelAll variants applyExpand Update transaction metadata — request body — body category Id value
categoryId (allOf 2)JSONAll variants applyHow to update the transaction's category. Omit field to keep current, send null to clear, send ID to set.
noteJSONOptional
note (allOf 1)ModelAll variants applyExpand Update transaction metadata — request body — body note value
note (allOf 2)JSONAll variants applyHow 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
FieldTypePresenceDescription and constraints
$stringRootKnown 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
FieldTypePresenceDescription and constraints
$objectRootRepresents an expense category for transaction classification.
idJSONRequired within parent
id (allOf 1)stringAll variants applyID for the category
Format: uuid
id (allOf 2)JSONAll variants applyThe ID of the category
namestringRequired within parentThe name of the category
visibleForCardSpendbooleanRequired within parentWhether this category is applicable to card transactions
visibleForOtherbooleanRequired within parentWhether this category is applicable to all other transaction kinds
visibleForReimbursementsbooleanRequired within parentWhether 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
FieldTypePresenceDescription and constraints
$objectRoot
convertedFromAmountJSONRequired within parent
convertedFromAmount (anyOf 1)numberAlternativeMultiple of: 0.01
convertedFromAmount (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
convertedFromCurrencyJSONRequired within parent
convertedFromCurrency (allOf 1)stringAll variants apply
convertedToAmountJSONRequired within parent
convertedToAmount (anyOf 1)numberAlternativeMultiple of: 0.01
convertedToAmount (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
convertedToCurrencyJSONRequired within parent
convertedToCurrency (allOf 1)stringAll variants apply
exchangeRateJSONRequired within parent
exchangeRate (anyOf 1)numberAlternativeExchange rate goes from "from currency" to "to currency"
(ie from currency * exchange rate = to currency)
Multiple of: 0.0001
exchangeRate (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
feeAmountJSONRequired within parent
feeAmount (anyOf 1)numberAlternativeMultiple of: 0.01
feeAmount (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
feePercentageJSONRequired within parent
feePercentage (anyOf 1)numberAlternativeMultiple of: 0.0001
feePercentage (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
feeTransactionIdJSONOptional
feeTransactionId (anyOf 1)JSONAlternative
feeTransactionId (anyOf 1) (allOf 1)stringAll variants applyID for this transaction
Format: uuid
feeTransactionId (anyOf 2)nullAlternative
Get transaction by ID — response body — gl Allocations item
FieldTypePresenceDescription and constraints
$objectRootA 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.
amountJSONRequired within parent
amount (anyOf 1)numberAlternativeThe amount allocated to this GL code
Multiple of: 0.01
amount (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
classNameJSONOptional
className (anyOf 1)stringAlternativeThe name of the class from the connected accounting integration, if assigned
className (anyOf 2)nullAlternative
departmentNameJSONOptional
departmentName (anyOf 1)stringAlternativeThe name of the department from the connected accounting integration, if assigned
departmentName (anyOf 2)nullAlternative
descriptionJSONOptional
description (anyOf 1)stringAlternativeOptional user-provided description for this allocation
description (anyOf 2)nullAlternative
glCodeNamestringRequired within parentThe 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
FieldTypePresenceDescription and constraints
$objectRootMerchant information for card transactions
amountJSONOptional
amount (anyOf 1)JSONAlternative
amount (anyOf 1) (anyOf 1)integerAlternativeThe 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)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
amount (anyOf 2)nullAlternative
categoryJSONOptional
category (anyOf 1)JSONAlternative
category (anyOf 1) (allOf 1)ModelAll variants applyExpand Get a card — response body — category Locks item
category (anyOf 1) (allOf 2)JSONAll variants applyMercury category for the merchant (e.g., "Restaurants", "Software")
category (anyOf 2)nullAlternative
categoryCodeJSONOptional
categoryCode (anyOf 1)stringAlternative4-digit merchant category code (MCC) for card transactions
categoryCode (anyOf 2)nullAlternative
currencyJSONOptional
currency (anyOf 1)JSONAlternative
currency (anyOf 1) (allOf 1)stringAll variants apply
currency (anyOf 1) (allOf 2)JSONAll variants applyISO 4217 currency code of the merchant's currency (e.g., "EUR", "GBP", "JPY").
Nothing if not available.
currency (anyOf 2)nullAlternative
idJSONOptional
id (anyOf 1)stringAlternativeMerchant ID for card transactions
id (anyOf 2)nullAlternative

Referenced models: Get a card — response body — category Locks item

Get transaction by ID — response body — related Transactions item
FieldTypePresenceDescription and constraints
$objectRootA Public API version of RelatedTransactionData.
accountIdJSONRequired within parent
accountId (allOf 1)stringAll variants applyID for a Mercury account.
Format: uuid
amountJSONRequired within parent
amount (anyOf 1)numberAlternativeMultiple of: 0.01
amount (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
idJSONRequired within parent
id (allOf 1)stringAll variants applyID for this transaction
Format: uuid
relationKindJSONRequired within parent
relationKind (allOf 1)ModelAll variants applyExpand 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

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.

Official provider source

Report an issue with this page

Necessary

Required for sign-in, security, authorization, and remembering your choices.

Always active

Analytics

Helps us understand which product and documentation features are useful.

Performance diagnostics

Uses performance tracing and privacy-masked session replay to diagnose problems.

You can change these choices at any time from Cookie settings.