Sign in
Vendor card

Update a card

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

ActionRequired permission
Change status_preference or nameCard owner, admin, or vendor_cards_manage permission
Change allocation paramsAdmin or vendor_cards_manage permission
Change spending limit paramsAdmin 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.

patch/v1/vendor_cards/{vendor_card_id}

Path parameters

vendor_card_idstring required

The id of the vendor card

Parameters

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

Request body

namestring

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_centsinteger 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_centsinteger 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_centsinteger 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.

Example request

{
  "name": "AWS",
  "allocated_amount_preference_cents": 50000,
  "recurring_allocation_amount_cents": 50000,
  "limit_amount_preference_cents": 100000
}

Response

Body of the updated vendor card.

idstring

Card id. Cardda card ids are vendor-prefixed base64-encoded strings (e.g. Q2FyZDoxMDIwNjQ5Mw==), not UUIDs.

user_idstring

Firebase user id of the cardholder (not a UUID).

company_idstring 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.

namestring
last4string
status'active' | 'inactive' | 'pending' | 'canceled'
status_preferencestring
migratedboolean
usageinteger nullable
limit_interval'daily' | 'weekly' | 'monthly' | 'yearly' | 'all_time' | 'per_authorization'

Current spending limit interval.

limit_interval_preference'daily' | 'weekly' | 'monthly' | 'yearly' | 'all_time' | 'per_authorization' nullable

Requested spending limit interval.

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_centsinteger nullable

Recurring allocation amount in cents.

remaining_balancestring 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.

spentinteger
company_expendable_balance_in_limit_currencystring 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_currencynumber 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.

{"stackTrail":"components:schemas:Vendor_card:properties:vendor_max_spending_limits","oasType":"schema","type":"unknown","description":"**Deprecated / always `null`.** No card type currently defines\nvendor-side hard spending limits, so this field is `null` for every card\ntoday (the base `VendorCard#vendor_max_spending_limits` returns `nil` and\nno subclass overrides it). Historically a `{ interval, amount }` map keyed\nby interval. **Show-only** — returned by `GET /v1/vendor_cards/{id}` only.\n","nullable":true}
non_sensitive_informationobject 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_statusstring 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_atstring date-time nullable

Creation timestamp of the most recent allocation transaction. Show-only — returned by GET /v1/vendor_cards/{id} only.

allocation_priority_statsobject 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_spendablestring 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_intervalnumber float
spent_in_vendor_intervalnumber float
fees_in_vendor_intervalnumber float
created_atstring date-time
updated_atstring date-time

Example response

{
  "id": "Q2FyZDoxMDIwNjQ5Mw==",
  "user_id": "U2MGkNZT6zNPKtB85OpJi9SjFvG2",
  "type": "PomeloCard",
  "name": "AWS",
  "last4": "4163",
  "status_preference": "inactive",
  "migrated": true,
  "limit_amount": {
    "amount": "3000.0",
    "formatted": "$3.000 CLP",
    "cents": "3000.0",
    "currency_iso": "CLP"
  },
  "limit_interval": "daily",
  "limit_amount_preference": {
    "amount": "3000.0",
    "formatted": "$3.000 CLP",
    "cents": "3000.0",
    "currency_iso": "CLP"
  },
  "allocated_amount": {
    "amount": "3000.0",
    "formatted": "$3.000 CLP",
    "cents": "3000.0",
    "currency_iso": "CLP"
  },
  "allocated_amount_preference": {
    "amount": "3000.0",
    "formatted": "$3.000 CLP",
    "cents": "3000.0",
    "currency_iso": "CLP"
  },
  "recurring_allocation_amount_cents": 50000,
  "remaining_balance": "2000.0",
  "spent": 472025,
  "company_expendable_balance_in_limit_currency": "3200000.0",
  "spent_in_interval_with_limit_currency": 472025,
  "vendor_max_allocation": {
    "amount": "3000.0",
    "formatted": "$3.000 CLP",
    "cents": "3000.0",
    "currency_iso": "CLP"
  },
  "preference_restricted_spendable": "2000.0",
  "spent_in_interval": 472025,
  "spent_in_vendor_interval": 472025
}

Changes

No recorded changes to this endpoint across all 1 revision of this API.