Skip to main content
POST
Increase a purchase card amount

Authorizations

Authorization
string
header
required

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

Idempotency-Key
string
required

Unique key for this increase, reused on retries.

Maximum string length: 255

Path Parameters

cardId
string
required

The unused single-use purchase card to increase.

Body

application/json

Increase an unused single-use purchase card's amount before checkout.

amount
integer<int64>
required

New purchase amount in USD cents, strictly above the current amount.

Required range: x >= 1
Example:

5999

reason
string
required

Why the purchase needs a higher amount, as reported by the app. The increase action returns it as purchaseCard.description, which is shown to the customer when they approve the increase.

Required string length: 1 - 255
Example:

"Shipping was added at checkout."

Response

The increase action, applied or awaiting approval.

An action submitted by an agent that may require platform approval before execution. All agent-initiated operations (quote execution, transfers) are represented as AgentActions, giving the platform a consistent object to approve, reject, and audit regardless of the underlying operation type.

id
string
required

System-generated unique identifier for this action.

Example:

"AgentAction:019542f5-b3e7-1d02-0000-000000000099"

agentId
string
required

The agent that submitted this action.

Example:

"Agent:019542f5-b3e7-1d02-0000-000000000042"

customerId
string
required

The customer on whose behalf the action was submitted.

Example:

"Customer:019542f5-b3e7-1d02-0000-000000000010"

platformCustomerId
string
required

Platform-specific ID of the customer.

Example:

"user-a1b2c3"

status
enum<string>
required

Status of an agent action.

Available options:
PENDING_APPROVAL,
APPROVED,
REJECTED,
FAILED
type
enum<string>
required

The type of action the agent is requesting.

Available options:
EXECUTE_QUOTE,
ISSUE_PURCHASE_CARD,
CLAIMABLE_PAYOUT,
USE_STORED_CARD,
CREATE_SETTLEMENT_RULE,
UPDATE_SETTLEMENT_RULE,
PAYOUT_RUN
expiresAt
string<date-time>
required

When the action expires. For an EXECUTE_QUOTE action with priceTolerance, this is the end of the platform's approval window, independent of the quote's own expiry: approval executes a live quote and quotes the send again once it has expired, and a pending action that reaches this time fails with APPROVAL_EXPIRED. For any other EXECUTE_QUOTE action, this is the quote's own expiry; a pending action that reaches it fails with QUOTE_EXPIRED, and approval never creates a replacement quote. For ISSUE_PURCHASE_CARD, USE_STORED_CARD, CREATE_SETTLEMENT_RULE, UPDATE_SETTLEMENT_RULE and PAYOUT_RUN, this is the end of the approval window, after which a pending action fails with APPROVAL_EXPIRED; a settlement rule's window is seven days, and a payout run's 24 hours.

Example:

"2025-10-03T15:05:00Z"

createdAt
string<date-time>
required

When the action was submitted by the agent.

Example:

"2025-10-03T15:00:00Z"

updatedAt
string<date-time>
required

When the action was last updated.

Example:

"2025-10-03T15:02:00Z"

quote
Agent Quote · object

The quote being executed. Contains the full amount, currency, destination, and rate details needed to present an approval decision to the user. Present for EXECUTE_QUOTE.

previousQuote
Agent Quote · object

The quote the customer was shown before an approval found that the price had moved past priceTolerance. Present only while the action is PENDING_APPROVAL after such an approval; quote is then the new quote to show the customer, and approving it again repeats the check against it.

priceTolerance
object

Present on a PENDING_APPROVAL EXECUTE_QUOTE action that Grid quotes again when it is approved after its quote expired: how far the price may move against the customer before they are asked again. Fixed when the action is created. Absent when approval can only execute quote as it is.

purchaseCard
object

The purchase card the agent asked for, so an approval decision can show its amount, limit, description and funding account. Present for ISSUE_PURCHASE_CARD.

claimablePayout
object

The claimable payout the agent asked to send, so an approval decision can show its amount and recipient. Present for CLAIMABLE_PAYOUT. Approving the action makes the payout AWAITING_CLAIM; rejecting it, or letting it expire, ends the payout and releases its hold.

storedCardUse
object

The stored card the agent asked to use, where, and for how much, so an approval decision can show them. Present for USE_STORED_CARD. Approving the action lets the agent collect a single-use link with POST /agents/me/stored-cards/{storedCardId}/reveal and actionId.

settlementRule
object

The settlement rule the agent proposed, so an approval decision can show what it matches, who it pays and its limits. Present for CREATE_SETTLEMENT_RULE and UPDATE_SETTLEMENT_RULE. For CREATE_SETTLEMENT_RULE, approving the action makes the rule ACTIVE; rejecting it, or letting it expire, deletes it. For UPDATE_SETTLEMENT_RULE, it is the rule as the change would make it, with the rule's id; approving the action applies the change, and rejecting it, or letting it expire, drops it while the rule keeps its terms. Approving a rule does not approve its payments in advance. Each share is still checked against the agent's policy when it is sent.

payoutRun
object

The payout run the agent created, so an approval decision can show every row. Present for PAYOUT_RUN. Approving the action starts the run; rejecting it, or letting it expire, cancels the run and skips every row. The approval covers each row's own approval, so no row waits for another.

cardId
string

The purchase card the action issued, or for an increase the card whose amount it raised. Present for an ISSUE_PURCHASE_CARD action once it is APPROVED and the card is issued or increased; read it with GET /agents/me/cards/{cardId}.

Example:

"Card:019542f5-b3e7-1d02-0000-000000000011"

transaction
Incoming Transaction · object

The resulting transaction, populated once the action has been approved and execution has begun. Absent while the action is PENDING_APPROVAL or REJECTED.

rejectionReason
string

Human-readable reason provided by the platform when rejecting the action. Only present when status is REJECTED.

Example:

"Transaction amount exceeds customer's current risk limit."

failureReason
enum<string>

Machine-readable reason the action failed. Only present when status is FAILED; rejectionReason is used only for REJECTED actions.

Available options:
QUOTE_EXPIRED,
POLICY_DENIED,
AGENT_INACTIVE,
EXECUTION_FAILED,
PRICE_MOVED,
ADDRESS_REFUSED,
APPROVAL_EXPIRED,
DELETED_BY_AGENT,
AGENT_CANCELLED