Mercury: Unfreeze a card
Mercury cards.unfreezeCard: arguments, response, policy and SDK examples.
← Cards operations · Get started
Operation mercury.unfreezecard
Provider route: POST /cards/{cardId}/unfreeze. 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["cards"]["unfreezeCard"]>[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.cards.unfreezeCard(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.cards.unfreeze_card(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.cardId | string | Required within parent | Unique identifier for a card Format: uuid |
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 a card — response body |
Referenced models: Get a card — response body
Schemas
Section titled “Schemas”Get a card — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
accountId | string | Required within parent | The Mercury account this card is associated with. |
budgets | array | Required within parent | One entry per active budget linked to this card and cardholder. Empty under cardLimit, or when this response has no active budget for the cardholder. |
budgets[] | Model | Each item | Expand Get a card — response body — budgets item |
categoryLocks | array | Required within parent | Mercury spend-category locks applied to this card, in no particular order. Empty when the card has no category restrictions. |
categoryLocks[] | Model | Each item | Expand Get a card — response body — category Locks item |
createdAt | JSON | Required within parent | |
createdAt (allOf 1) | string | All variants apply | Format: yyyy-mm-ddThh:MM:ssZ |
createdAt (allOf 2) | JSON | All variants apply | Timestamp when the card was issued. |
expiration | JSON | Required within parent | |
expiration (allOf 1) | Model | All variants apply | Expand Get a card — response body — expiration Month and year the card expires |
expiration (allOf 2) | JSON | All variants apply | Month and year the card expires. |
id | string | Required within parent | Unique identifier for the card. Format: uuid |
isAgentCard | boolean | Required within parent | Whether the card is managed by the agentic spend-management agent. Only agent cards can have their full details revealed. |
isSingleUse | boolean | Required within parent | Whether the card closes automatically after its first approved purchase. A used single-use card reports a @singleUseConsumed@ status. |
kind | JSON | Required within parent | |
kind (allOf 1) | string | All variants apply | Known values: debit, credit |
kind (allOf 2) | JSON | All variants apply | Whether the card is a debit or credit card. |
lastFour | string | Required within parent | Last four digits of the card's primary account number (PAN). |
merchantLock | JSON | Optional | |
merchantLock (anyOf 1) | JSON | Alternative | |
merchantLock (anyOf 1) (allOf 1) | Model | All variants apply | Expand List merchants — response body — data item |
merchantLock (anyOf 1) (allOf 2) | JSON | All variants apply | Merchant lock applied to this card. Present only when the card is locked to a single merchant; otherwise omitted. |
merchantLock (anyOf 2) | null | Alternative | |
nameOnCard | string | Required within parent | Cardholder name printed on the card. |
nickname | JSON | Optional | |
nickname (anyOf 1) | string | Alternative | Optional user-assigned label for the card. |
nickname (anyOf 2) | null | Alternative | |
physicalCardStatus | JSON | Optional | |
physicalCardStatus (anyOf 1) | JSON | Alternative | |
physicalCardStatus (anyOf 1) (allOf 1) | string | All variants apply | Known values: inactive, active, locked |
physicalCardStatus (anyOf 1) (allOf 2) | JSON | All variants apply | Activation state of a physical card. Null for virtual cards. |
physicalCardStatus (anyOf 2) | null | Alternative | |
spendLimit | JSON | Optional | |
spendLimit (anyOf 1) | JSON | Alternative | |
spendLimit (anyOf 1) (allOf 1) | Model | All variants apply | Expand Get a card — response body — spend Limit amount Cents, atm Amount Cents, interval Spending controls applied to a card |
spendLimit (anyOf 1) (allOf 2) | JSON | All variants apply | Card-level spending controls. This is null when card-level limits are unavailable, including for credit cards governed by budgets. For debit cards, this includes the underlying card limits even when budgets govern purchase spending. In budget mode, the transaction limit does not gate purchases, but the ATM or cash limit can still apply to cash withdrawals. |
spendLimit (anyOf 2) | null | Alternative | |
spendLimitType | JSON | Required within parent | |
spendLimitType (allOf 1) | string | All variants apply | Known values: cardLimit, budgets |
spendLimitType (allOf 2) | JSON | All variants apply | Whether card-level limits or budgets govern purchase spending. |
status | JSON | Required within parent | |
status (allOf 1) | string | All variants apply | Known values: active, frozen, cancelled, inactive, expired, suspended, singleUseConsumed |
status (allOf 2) | JSON | All variants apply | Current lifecycle state of the card. |
type | JSON | Required within parent | |
type (allOf 1) | string | All variants apply | Known values: virtual, physical |
type (allOf 2) | JSON | All variants apply | Whether the card is virtual (digital-only) or physical (printed, supports ATM). |
updatedAt | JSON | Required within parent | |
updatedAt (allOf 1) | string | All variants apply | Format: yyyy-mm-ddThh:MM:ssZ |
updatedAt (allOf 2) | JSON | All variants apply | Timestamp of the last modification to the card or its settings. |
userId | string | Required within parent | Mercury User who owns the card. |
Referenced models: Get a card — response body — budgets item, Get a card — response body — expiration Month and year the card expires, List merchants — response body — data item, Get a card — response body — category Locks item, Get a card — response body — spend Limit amount Cents, atm Amount Cents, interval Spending controls applied to a card
Get a card — response body — budgets item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Current-cycle limits for one budget linked to this card and cardholder. |
amountCents | JSON | Required within parent | |
amountCents (anyOf 1) | integer | Alternative | The cardholder's spend limit for the current budget cycle, in cents. Minimum: 0 |
amountCents (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
id | string | Required within parent | Unique identifier for a budget Format: uuid |
name | string | Required within parent | Display name of the budget. |
remainingAmountCents | JSON | Required within parent | |
remainingAmountCents (anyOf 1) | integer | Alternative | Current-cycle limit minus recorded spend, clamped at zero, in cents. Authorization also uses cached allocations and in-flight holds, so its available amount may differ. Minimum: 0 |
remainingAmountCents (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
Get a card — response body — expiration Month and year the card expires
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Month and year the card expires. |
month | JSON | Required within parent | |
month (anyOf 1) | integer | Alternative | Calendar month. Maximum: 12 Minimum: 1 |
month (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
year | JSON | Required within parent | |
year (anyOf 1) | integer | Alternative | Four-digit calendar year. Maximum: 2999 Minimum: 2000 |
year (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
List merchants — response body — data item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Information about a merchant that can be used for spend controls like merchant locking. |
id | JSON | Required within parent | |
id (allOf 1) | string | All variants apply | Format: uuid |
name | string | Required within parent |
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 |
Get a card — response body — spend Limit amount Cents, atm Amount Cents, interval Spending controls applied to a card
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Spending controls applied to a card |
amountCents | JSON | Required within parent | |
amountCents (anyOf 1) | integer | Alternative | Maximum total spend allowed per interval, in cents. Minimum: 0 |
amountCents (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
atmAmountCents | JSON | Optional | |
atmAmountCents (anyOf 1) | JSON | Alternative | |
atmAmountCents (anyOf 1) (anyOf 1) | integer | Alternative | Maximum ATM withdrawal allowed per interval, in cents. Null for virtual cards and credit cards. Minimum: 0 |
atmAmountCents (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
atmAmountCents (anyOf 2) | null | Alternative | |
interval | JSON | Required within parent | |
interval (allOf 1) | string | All variants apply | Known values: daily, weekly, monthly, yearly |
interval (allOf 2) | JSON | All variants apply | Rolling window the limit applies to. |
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: mercury.unfreezecard. Catalog operation: mercury:unfreezeCard. 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.