Issue an agent card
Issue a virtual card for the authenticated agent. The card belongs to the agent’s customer, who must have KYC status APPROVED and have accepted the cardholder agreement where the platform requires one. Its spend counts against the agent’s policy limits as the agent’s sends do, and Grid’s default agent merchant-category blocks apply. Requires the ISSUE_CARDS permission; reading the card afterwards needs MANAGE_CARDS.
Business customers: where the platform enables agents for business customers, an agent of a BUSINESS customer may be issued standard and purchase cards once the business’s KYB status is APPROVED. The request must name the person the card is for in cardholder; the card is issued on the business’s card account with that person as its authorized user, and carries the agent’s actingFor. A purchase card awaiting approval is issued to that person when it is approved.
Standard card (kind omitted or STANDARD): as POST /cards with agentId does for the platform. While any of the agent’s standard cards is not CLOSED, including one the platform issued for it, the request is rejected with AGENT_CARD_EXISTS. New cards start in status: "PROCESSING" and follow the same status transitions and card.status_change webhooks as cards issued with POST /cards.
Purchase card (kind: PURCHASE): a single-use card for one online purchase of amount, paid from the customer’s Embedded Wallet with the agent’s delegated key. Available only where the platform enables agent purchase cards. Its limit (purchase.spendLimit) is amount plus an allowance for tax and shipping, and that limit is evaluated against the agent’s policy as a send of the same amount would be:
-
Under the policy’s approval threshold and the approval threshold of the agent’s spending pool, if any, and with
defaultExecutionModeAUTO, the card is issued at once and returned with201. -
Otherwise the request becomes an
ISSUE_PURCHASE_CARDagent action inPENDING_APPROVAL, returned with202, and theAGENT_ACTION.PENDING_APPROVALwebhook fires. The card is issued when the action is approved withPOST /agents/{agentId}/actions/{actionId}/approve; the action then carriescardId. PollGET /agents/me/actions/{actionId}for the outcome. -
A request the policy denies outright (over a spending limit, or a funding account the policy does not allow) is rejected with
403.
The card is closed by its first approved authorization, and Grid closes it if it is still unused at purchase.expiresAt. Purchase cards are not counted by the one-standard-card rule, but an agent may hold only a limited number of open purchase cards, counting those awaiting approval; beyond that the request is rejected with PURCHASE_CARD_LIMIT_REACHED.
Recurring purchase card (kind: PURCHASE, recurring: true): for a subscription, a card saved with a merchant, a hotel or car rental, or an order that ships in parts. Available only where the platform enables recurring purchase cards. The card locks to the first merchant that charges it and declines every other merchant; that merchant may charge it again, up to amount in any trailing month (from a charge back to the same date a month earlier), with no allowance added. It always becomes an ISSUE_PURCHASE_CARD action awaiting the customer’s approval and is returned with 202, whatever the policy’s approval threshold or execution mode, though a request the policy denies is still rejected with 403. Its charges count against the agent’s policy limits as they are authorized. It has no purchase.expiresAt and stays open until the customer or platform closes it (PATCH /cards/{id} with status: CLOSED, a substatus and a reason). Pausing the agent does not close it, but its charges are declined while the agent is paused; deleting the agent freezes it, and POST /agents/{agentId}/card-handover with kind=PURCHASE can move it to the customer’s next agent. Recurring cards have their own, smaller limit on open cards, counting those awaiting approval, and do not use up the room for single-use cards. Card details are never returned here; request them with POST /agents/me/cards/{cardId}/reveal.
Card issuance cannot be reversed, so an Idempotency-Key header is required. Keys are scoped to the agent: a retry by the same agent with the same key returns what the first request created, whatever has changed since, and another agent’s key never matches. For a purchase card, a retry returns the issued card with 201, or the action with 202 while it is pending, rejected or failed.
Authorizations
Bearer token authentication for agent-scoped endpoints. The token is the accessToken returned when redeeming a device code via POST /agents/device-codes/redeem. Agent credentials are user-scoped: all requests are automatically bound to the agent's associated customer and subject to the agent's policy.
Headers
A unique identifier for the request, up to 255 characters, scoped to the agent. A retry carrying the same key returns the card created by the first request; reusing a key for a different card request is rejected with 409.
255"550e8400-e29b-41d4-a716-446655440000"
Body
Request body for POST /agents/me/cards. Without kind, or with kind: STANDARD, it issues the agent's standard card. With kind: PURCHASE it requests a single-use purchase card for one online purchase of amount, or with recurring: true a recurring purchase card that may spend up to amount a month at one merchant.
Internal account id that funds the card. The account must belong to the agent's customer and be denominated in a card-eligible currency; otherwise the request is rejected with INVALID_INPUT. A PURCHASE card must be funded from an Embedded Wallet on which the agent holds an active delegated key.
"InternalAccount:019542f5-b3e7-1d02-0000-000000000002"
The kind of card to issue. Defaults to STANDARD.
STANDARD, PURCHASE The purchase amount in the smallest unit of USD. Required for kind: PURCHASE and rejected otherwise. Grid adds an allowance for tax and shipping to set the card's limit; see AgentPurchaseCardDetails. For a recurring card it is the monthly limit itself, with no allowance added, so include tax and shipping in it. Each platform sets the largest amount an agent may ask for, separately for single-use and recurring cards; a larger one is rejected with INVALID_INPUT.
x >= 14999
What the card is for, such as the merchant and item, shown to the customer when they approve it. Allowed only with kind: PURCHASE.
255"Running shoes from example-store.com"
Request a recurring purchase card: one that locks to the first merchant that charges it and may be charged there again, up to amount in any trailing month (from a charge back to the same date a month earlier), until it is closed. Use it for a subscription, a card saved with a merchant, a hotel or car rental, or an order that ships in parts. It always needs the customer's approval, whatever the agent's policy says, and is available only where the platform enables recurring purchase cards. true is allowed only with kind: PURCHASE; false is accepted with any kind.
false
The person the card is for, named on the card as an authorized user of the business. Required for every card when the agent's customer is a BUSINESS, and rejected for an INDIVIDUAL. For a purchase card that awaits approval, Grid keeps it, encrypted, until the card is issued or the request ends.
Response
Card created. A standard card starts in PROCESSING while the issuer provisions it. A purchase card is returned with purchase set.
A card that belongs to the authenticated agent: the card itself and how the agent may use it.
The agent the card belongs to.
"Agent:019542f5-b3e7-1d02-0000-000000000042"
How an agent card is used and funded.
STANDARD, PURCHASE Every merchant category code the card declines: blockedMccs plus the categories Grid blocks for agent cards, unless the platform lifted those defaults (defaultMccBlocksLifted).
^[0-9]{4}$The platform's reference for the person the card was issued for: the issuing agent's actingFor when the card was issued. Absent when the agent had none.
"member_8f2c1a"
The purchase the card was issued for. Present for PURCHASE cards.