---
title: "Update a card"
method: PATCH
path: "/v1/vendor_cards/{vendor_card_id}"
tags: ["Vendor card"]
---

# Update a card

`PATCH /v1/vendor_cards/{vendor_card_id}`

Updates the specified card. Use this endpoint to:

- Activate or deactivate a card
- Allocate funds to a card
- Configure recurring allocations
- Set spending limits

## Permissions

| Action | Required permission |
|--------|-------------------|
| Change `status_preference` or `name` | Card owner, admin, or `vendor_cards_manage` permission |
| Change allocation params | Admin or `vendor_cards_manage` permission |
| Change spending limit params | Admin or `vendor_cards_manage` permission |

## Top-up

If you send `allocated_amount_preference_cents` with the **same value** the card already has, but the card has spent some of those funds (i.e. the actual balance is lower), the system will automatically **top-up** the card back to the requested amount. This is useful for refilling a card to its original balance after spending.

**Example:** A card was allocated 50,000 CLP. The user spent 20,000 CLP, so the actual balance is 30,000 CLP. Sending `{"allocated_amount_preference_cents": 50000}` again will top-up the card back to 50,000 CLP.

For a complete guide with examples, see [Card Allocations](/reference/card-allocations).

## Path parameters

- `vendor_card_id` string, required

## Parameters

- `#/paths/~1v1~1merchants/get/parameters/0` — unresolved $ref

## Request body

- VendorCardUpdate
  - `name` string — Display name for the card.
  - `status_preference` 'inactive' | 'active' | 'canceled' — Desired card status. Changing to 'active' activates the card, 'inactive' temporarily disables it, and 'canceled' permanently cancels it.
  - `allocated_amount_preference_cents` integer, nullable — Target amount to allocate to the card, in cents. The card will be loaded with funds up to this amount. If you send the same value the card already has but the actual balance is lower (because the card has spent funds), the system will automatically top-up the card back to this amount.
  - `allocation_interval_preference` 'daily' | 'weekly' | 'monthly' | 'yearly', nullable — Interval at which the recurring allocation is applied.
  - `allocation_priority_preference` 'low' | 'mid' | 'high' | 'max', nullable — Priority level for allocation when company funds are distributed across multiple cards.
  - `recurring_allocation_amount_cents` integer, nullable — Amount in cents to automatically allocate on each recurring interval. Use this together with `allocation_interval_preference` for scheduled fund loads. While `allocated_amount_preference_cents` sets the target amount immediately, this field configures automatic reloads on a recurring schedule.
  - `limit_amount_preference_cents` integer, nullable — Spending limit for the card, in cents. The card will block transactions once spending reaches this amount within the configured interval.
  - `limit_interval_preference` 'daily' | 'weekly' | 'monthly' | 'yearly' | 'all_time' | 'per_authorization', nullable — Interval for the spending limit. Spending resets at the beginning of each interval.

## Response `200`

Body of the updated vendor card.

- VendorCard
  - `id` string — Card id. Cardda card ids are vendor-prefixed base64-encoded strings (e.g. `Q2FyZDoxMDIwNjQ5Mw==`), not UUIDs.
  - `user_id` string — Firebase user id of the cardholder (not a UUID).
  - `company_id` string, uuid
  - `type` 'AptoCard' | 'BrexCard' | 'Cards::Increase::Card' | 'Cards::Plh::Card' | 'DivvyCard' | 'Issuing::Relay::Card' | 'Issuing::Slash::Card' | 'MercuryCard' | 'MeshCard' | 'PomeloCard' | 'StripeCard' — Single Table Inheritance discriminator (issuing vendor / STI sub-class). A persisted column, so it always serializes into the row for **every** caller.
  - `name` string
  - `last4` string
  - `status` 'active' | 'inactive' | 'pending' | 'canceled'
  - `status_preference` string
  - `migrated` boolean
  - `usage` integer, nullable
  - `limit_amount` MoneyAmount, nullable — Monetary amount. All numeric fields are serialized as strings to preserve precision (BigDecimal).
    - `amount` string — Amount in the main currency unit (e.g., '3000.0' for 3,000 CLP, '176.0' for 176 USD).
    - `formatted` string — Human-readable formatted amount including currency symbol.
    - `cents` string — Amount in the currency's smallest subunit. For CLP (no subunits) this equals the main amount; for USD this is 100× the main amount.
    - `currency_iso` string — ISO 4217 currency code.
  - `limit_interval` 'daily' | 'weekly' | 'monthly' | 'yearly' | 'all_time' | 'per_authorization' — Current spending limit interval.
  - `limit_amount_preference` MoneyAmount, nullable — Monetary amount. All numeric fields are serialized as strings to preserve precision (BigDecimal).
    - `amount` string — Amount in the main currency unit (e.g., '3000.0' for 3,000 CLP, '176.0' for 176 USD).
    - `formatted` string — Human-readable formatted amount including currency symbol.
    - `cents` string — Amount in the currency's smallest subunit. For CLP (no subunits) this equals the main amount; for USD this is 100× the main amount.
    - `currency_iso` string — ISO 4217 currency code.
  - `limit_interval_preference` 'daily' | 'weekly' | 'monthly' | 'yearly' | 'all_time' | 'per_authorization', nullable — Requested spending limit interval.
  - `allocated_amount` MoneyAmount, nullable — Monetary amount. All numeric fields are serialized as strings to preserve precision (BigDecimal).
    - `amount` string — Amount in the main currency unit (e.g., '3000.0' for 3,000 CLP, '176.0' for 176 USD).
    - `formatted` string — Human-readable formatted amount including currency symbol.
    - `cents` string — Amount in the currency's smallest subunit. For CLP (no subunits) this equals the main amount; for USD this is 100× the main amount.
    - `currency_iso` string — ISO 4217 currency code.
  - `allocated_amount_preference` MoneyAmount, nullable — Monetary amount. All numeric fields are serialized as strings to preserve precision (BigDecimal).
    - `amount` string — Amount in the main currency unit (e.g., '3000.0' for 3,000 CLP, '176.0' for 176 USD).
    - `formatted` string — Human-readable formatted amount including currency symbol.
    - `cents` string — Amount in the currency's smallest subunit. For CLP (no subunits) this equals the main amount; for USD this is 100× the main amount.
    - `currency_iso` string — ISO 4217 currency code.
  - `allocation_interval_preference` 'daily' | 'weekly' | 'monthly' | 'yearly', nullable — Interval at which recurring allocations are applied.
  - `allocation_priority_preference` 'low' | 'mid' | 'high' | 'max', nullable — Priority level for fund allocation across multiple cards.
  - `recurring_allocation_amount_cents` integer, nullable — Recurring allocation amount in cents.
  - `remaining_balance` string, nullable — Actual amount the card can spend right now, as a decimal string in the card's currency (not cents). This is the minimum between the user's spending limit and the company's available balance.
  - `spent` integer
  - `company_expendable_balance_in_limit_currency` string, nullable — Company funds this card can still draw, expressed in the card's `limit_currency`, as a decimal string (a BigDecimal serialized to JSON, not a number). **Show-only** — returned by `GET /v1/vendor_cards/{id}` only, and only when the caller can read the company balance (`policy(company).balance?`). Absent from the list endpoint.
  - `spent_in_interval_with_limit_currency` number, float — Amount spent in the current limit interval, converted to the card's `limit_currency`. Always a number (defaults to `0.0`); never `null`. **Show-only** — returned by `GET /v1/vendor_cards/{id}` only.
  - `vendor_max_spending_limits` unknown
  - `vendor_max_allocation` MoneyAmount, nullable — Monetary amount. All numeric fields are serialized as strings to preserve precision (BigDecimal).
    - `amount` string — Amount in the main currency unit (e.g., '3000.0' for 3,000 CLP, '176.0' for 176 USD).
    - `formatted` string — Human-readable formatted amount including currency symbol.
    - `cents` string — Amount in the currency's smallest subunit. For CLP (no subunits) this equals the main amount; for USD this is 100× the main amount.
    - `currency_iso` string — ISO 4217 currency code.
  - `non_sensitive_information` object, nullable — Non-sensitive cardholder/configuration attributes (`user_name`, `user_identifier`, `country`, `address`, `postal_code`, `restricted_merchants`, `phone`). Empty object when unavailable. **Show-only** — returned by `GET /v1/vendor_cards/{id}` only.
  - `last_allocation_transaction_status` string, nullable — Status of the most recent allocation transaction on this card. **Show-only** — returned by `GET /v1/vendor_cards/{id}` only.
  - `last_allocation_transaction_created_at` string, date-time, nullable — Creation timestamp of the most recent allocation transaction. **Show-only** — returned by `GET /v1/vendor_cards/{id}` only.
  - `allocation_priority_stats` object, nullable — Total recurring allocation (cents) per priority group across the company's active cards (e.g. `{ "low": 5000000, "mid": 3000000 }`), or `null` for card types that don't compute it. **Show-only** — returned by `GET /v1/vendor_cards/{id}` only.
  - `preference_restricted_spendable` string, nullable — Amount the card can still spend before hitting its configured spending limit, as a decimal string in the card's currency (not cents). Calculated as the spending limit minus amount already spent in the current interval. Unlike `remaining_balance`, this does not consider the company's available funds.
  - `spent_in_interval` number, float
  - `spent_in_vendor_interval` number, float
  - `fees_in_vendor_interval` number, float
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `401` — Unauthorized. The API key user does not have the required permissions (admin or `vendor_cards_manage`) to modify allocations or spending limits.
- `404` — Vendor card not found (or not visible to the caller).
- `422` — Unprocessable Entity. Possible causes: read-only spending-limit fields sent (`limit_amount_cents` / `limit_interval` / `allocated_amount_cents` → `{ "error_code": "vendor_cards/spending_limits_readonly" }`), modifying a canceled card, invalid interval value, insufficient company balance, a missing user (`{ "message": "User not found" }`), or a generic update failure (`{ "error_code": "vendor_cards/update_failed" }`).

---

[API](https://skmtc.dev/cardda/apis/banking-api.md) · [All operations](https://skmtc.dev/cardda/apis/banking-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cardda/banking-api/revisions/ff1aeb3fda8b/schema)