Spend requests
A spend request is Link’s record of a proposed purchase. It identifies the seller, amount, reason for the purchase, selected payment method, and type of credential the agent needs. It also tracks the customer’s approval and the purchase outcome. Start with the CLI quickstart or hosted integration guide to create your first request. Use this page to look up shared behavior while building your integration.
A spend request moves through three main phases:
- Create the request with the seller, context, and amount.
- Request approval from the Link account owner.
- Use the credential returned after approval.
Statuses
Handle all ten spend-request statuses explicitly:
| Status | Meaning | What to do |
|---|---|---|
created | The request exists, but approval isn’t pending yet. | Request approval. If you just requested it, continue polling the same request. |
pending_approval | The customer hasn’t approved or denied the request. | Continue polling. |
requires_action | The customer must complete another action. | Follow status_details.requires_action.next_action. |
approved | The credential is available. | Complete the purchase. |
denied | The customer denied the request. | Stop. Create a new request only if the customer asks to retry. |
expired | The 30-minute approval window elapsed, or the approved credential wasn’t used in time. | Create a new request if the customer still wants to proceed. |
canceled | The request was canceled. | Create a new request if the customer still wants to proceed. |
submitted | The request was approved, and the agent received a card credential. | No further action is required. |
succeeded | The request was approved, and Link received a successful payment event. | No further action is required. |
failed | The request failed and is terminal. | Inspect status_details.failed.code and optional status_details.failed.next_action for recovery. Use the latest payment's payment_status_details.code and payment_status_details.decline_code for payment outcomes. |
Poll for approval
Poll for a decision during the 30-minute approval window:
link-cli spend-request retrieve lsrq_001 \
--interval 2 \
--max-attempts 300In an interactive terminal, approval commands poll internally. In non-interactive or structured-output mode, create and request-approval commands return immediately with _next. Run the previous spend-request retrieve command to poll.
Polling can exit successfully at approved, denied, expired, submitted, succeeded, failed, or canceled. It returns a non-auto_resume requires_action so you can involve the customer. An auto_resume action continues polling the same request. Exit code zero means the command completed, not that the customer approved or the payment succeeded. Always inspect status.
If --timeout elapses or --max-attempts is exhausted, Link CLI exits non-zero with code: "POLLING_TIMEOUT". The request is still pending. Retrieve the same request again to learn its current status. Don’t create a duplicate or report a failed purchase based on the timeout alone.
The SDKs don’t poll for you. When you write your own loop, keep polling created and pending_approval, and keep polling requires_action only when the resolution is auto_resume. Return on every other status. Show an auto_resume action to the customer once, when its action_url or expires_at changes, instead of on every poll.
Purchase details
Use these parameters to describe a virtual-card or Shared Payment Token purchase:
| Parameter | Applies to | Requirements |
|---|---|---|
merchant_name | Virtual card | Required. The seller shown to the customer. |
merchant_url | Virtual card | Required. The seller’s URL. |
network_id | Shared Payment Token | Required. Use the network ID from the seller’s HTTP 402 challenge. Omit the merchant fields. |
context | Both | Required. At least 100 characters explaining what the agent is buying and why. |
amount | Both | Required. Uses the currency’s smallest unit and can’t exceed 50,000 cents for USD. |
currency | Both | A three-letter ISO code. If omitted, Link uses the consumer’s default spend-request currency. See Currency. |
payment_details | Both | The ID of an eligible payment method. Omit it to use the customer’s default, or the first eligible method. |
line_items | Both | Each item requires name. Optional fields are quantity, unit_amount, description, sku, url, image_url, and product_url. |
totals | Both | Each total requires type, display_text, and amount. Types are subtotal, tax, total, items_base_amount, items_discount, discount, fulfillment, shipping, fee, gift_wrap, tip, and store_credit. |
metadata | Both | Up to 50 string keys. Keys can contain 40 characters and values 500 characters. |
idempotency_key | Both | Optional. 1–255 UTF-8 bytes with no personal data. Repeating a create with the same key returns the original response. |
recurring | Card, Shared Payment Token, and Link Pay Token | Optional, create-only. Sets a repeating spending-limit period with interval (day, week, month, or year) and an optional positive interval_count that defaults to 1. Omit it for a one-time request. See Recurring payments. |
completion_callback_url and nonce | All credential types | Optional, create-only, and supplied together. See Completion callbacks. |
Link Pay Token requests use a different set of fields. See Link Pay Token.
Currency
If currency is omitted, Link uses the consumer’s default spend-request currency, reported by user-info retrieve as default_spend_request_currency. For an amount taken from a checkout, specify that checkout’s currency. Amounts, line-item unit_amount, and total amount use that currency’s minor units. The client performs no currency conversion. Existing requests retain their stored currency.
Check for blockers before you create a request
Retrieve the customer’s spend limits and verification requirement first, so you can avoid a request that can’t be approved:
link-cli user-info retrieve --format jsonagent_wallet_spend_limits has per_transaction, daily, and thirty_day entries, each with limit, used, and remaining in cents. A null value means unlimited. agent_wallet_verification_requirement has a status and a nullable action_url that the customer must visit if verification is required.
Manage a spend request
Retrieve a request to inspect its current state, payment outcome, and any refunds. List requests to recover work across agent runs. You can cancel requests in created, pending_approval, or approved.
The command examples assume you have completed Link CLI setup. Each command demonstrates a separate operation; don’t run them all as one purchase flow. For SDK setup and language-specific examples, use the TypeScript, Go, or Python page.
# Update before approval
link-cli spend-request update lsrq_001 \
--merchant-url https://press.stripe.com/working-in-public
# Request approval separately
link-cli spend-request request-approval lsrq_001
# Retrieve at any point
link-cli spend-request retrieve lsrq_001
# List the user's spend requests
link-cli spend-request list
# Cancel a created, pending, or approved request
link-cli spend-request cancel lsrq_001See Limits for approval windows and credential validity.
Increase the amount of an approved request
If the final total turns out to be higher than the approved amount, and you haven’t used the card yet, update the request with the new total, not the difference, and ask for approval again:
link-cli spend-request update lsrq_abc123 --amount 7500
link-cli spend-request request-approval lsrq_abc123
link-cli spend-request retrieve lsrq_abc123 --interval 2 --max-attempts 300Then poll the same request until it returns to approved. After the customer approves, Link increments the authorization. Increases aren’t guaranteed. If one fails, the request stays usable at its original amount. Cancel it and create a new request if you need the higher total. A one-time card can’t be used twice, so don’t request an increase after you’ve used the credential. Recurring terms can’t be changed with update; see Recurring payments.
Test mode
Pass --test to receive test credentials instead of a real payment credential:
link-cli spend-request create \
--test \
--merchant-name "Example Store" \
--merchant-url "https://example.com" \
--context "Testing the agent purchase flow for Example Store without charging a real payment method in the connected wallet." \
--amount 100Test-mode requests don’t charge the underlying payment method. With an SDK, set test: true in TypeScript, Test to a pointer to true in Go, or test=True in Python. Test mode supports virtual cards and Shared Payment Tokens, but not Link Pay Tokens.
Virtual card
The default request returns a virtual card that can be entered into a standard checkout form. It works beyond Link-enabled or Stripe-powered sellers.
After approval, request the full credential only at the point of use:
link-cli spend-request retrieve lsrq_001 \
--include card \
--output-file "$(mktemp -d)/link-card.json" \
--format jsonThe expanded card object contains these properties:
{
"id": "card_...",
"brand": "visa",
"number": "4242...",
"cvc": "123",
"exp_month": 12,
"exp_year": 2028,
"billing_address": {
"name": "Jenny Rosen",
"line1": "510 Townsend St",
"city": "San Francisco",
"state": "CA",
"postal_code": "94103",
"country": "US"
},
"valid_until": "2026-06-13T03:40:10Z"
}The cvc, billing_address, and valid_until fields are optional, as are line2, city, state, and postal_code within billing_address. Keep returned card credentials out of model context, logs, and customer-visible messages.
Read a failed payment
When a request has status: "failed", inspect status_details.failed.code and optional status_details.failed.next_action for recovery instructions. The request is terminal, but the customer might be able to unblock a replacement. Follow Handle errors and retries before retrying.
For payment outcomes, inspect payment_status_details. It contains outcome, code, decline_code, amount, currency, and refund_details (amount, currency, state, and created) when Link refunded part of the payment.
Shared Payment Token
Use a Shared Payment Token (SPT) for a seller that accepts Stripe payments through Machine Payments Protocol and returns an HTTP 402 challenge.
Decode the raw WWW-Authenticate challenge to extract its network_id:
link-cli mpp decode \
--challenge 'Payment id="ch_001", realm="merchant.example", method="stripe", intent="charge", request="..."'Create the spend request with --credential-type shared_payment_token. The network ID, amount, and currency must all come from the same seller challenge. The values below are illustrative; use the currency from your challenge, not necessarily usd:
link-cli spend-request create \
--credential-type shared_payment_token \
--network-id network_xxx \
--context "Purchasing a contribution from the MPP endpoint the user selected, at the amount in the seller's HTTP 402 challenge." \
--amount 100 \
--currency usdAfter approval, complete the purchase:
link-cli mpp pay https://climate.stripe.dev/api/contribute \
--spend-request-id lsrq_001 \
--method POST \
--data '{"amount":100}' \
--header "X-Custom: value"For a one-time request, an SPT is one-time-use. If the payment fails, follow the returned recovery instructions before creating a replacement. Reusing a consumed token returns a verification-failed error.
The Link SDK creates and retrieves the SPT. Your application’s MPP client is responsible for decoding the seller’s challenge and sending the credential back to the endpoint. See Machine payments for the complete flow.
Link Pay Token
Some Stripe-hosted checkouts accept a Link Pay Token (LPT) in place of card details. The token also fills in billing and shipping details.
Request it by setting credential_type to link_pay_token; it is a distinct credential type, not a value requested alongside a virtual card. Provide merchant_account_id and omit the merchant name and URL. After approval, retrieve with include set to link_pay_token.
Link Pay Tokens don’t support test mode or Shared Payment Tokens. See Link Pay Tokens to check checkout support, request the credential, and submit it. See Limits for credential validity.
Recurring payments
Add recurring when the customer approves a repeating spending limit, such as a subscription. Omit it for a one-time purchase.
link-cli spend-request create \
--merchant-name "Example Pro" \
--merchant-url "https://example.com/subscribe" \
--context "Monthly access to Example Pro requested by the user, with a spending limit of 20 USD per month including all taxes." \
--amount 2000 \
--currency usd \
--recurring-interval month| Input | CLI flag | SDK field | Requirements |
|---|---|---|---|
| Interval | --recurring-interval | recurring.interval | day, week, month, or year. |
| Interval count | --recurring-interval-count | recurring.interval_count | Optional positive integer. It requires an interval and defaults to 1 on the server. week with a count of 2 resets the limit every two weeks. |
Keep these rules in mind:
- Amount is a per-period limit.
amountis the spending limit for each period in the selected currency’s minor units, not a lifetime subscription budget. Confirm the limit, currency, and cadence with the customer, and state them incontextso they appear in approval. - Credential types. Card, Shared Payment Token, and Link Pay Token creation accept recurring inputs. Each keeps its normal targeting and checkout requirements, and Link enforces availability and limits. Machine payments started with
mpp paycreate one-time requests; see Machine payments. - The merchant schedules billing. Link CLI doesn’t schedule charges. A recurring card request stays active after individual charges, so don’t create a new request each period or wait for
succeededafter each charge. Confirm payments through the merchant’s results or transaction records, and don’t treat the request status alone as proof that a payment succeeded. - Terms are create-only.
updatecan’t change the interval or count. Cancel the request and create a new one to change them. - Respect credential expiry. Use the expiry returned with the credential, such as
valid_until, rather than assuming a fixed lifetime.
Recurring Shared Payment Token limits
For a recurring Shared Payment Token (SPT), Link sets the token’s usage_limits.max_amount to the spend request’s amount, in the selected currency’s minor units. Payments share this limit until the next reset. It isn’t a separate allowance for each payment or a lifetime budget.
recurring.interval sets the unit of time: day, week, month, or year. recurring.interval_count sets how many of those units make up each spending period and defaults to 1. For example, month with a count of 2 resets usage every two months. The count doesn’t limit how many periods the credential can be used.
Usage counts against the current period’s limit and resets for the next period. Unused allowance doesn’t carry over. For example, amount: 2000 with currency: usd and a monthly interval allows up to 20 USD in each period, not 20 USD plus any unused amount from the previous period. A reset doesn’t extend the credential’s expiry.
Recurring card spending periods
For a recurring virtual card:
- Spending periods start when the underlying credential is created, normally during approval, and use UTC.
- Retrieving the existing card doesn’t reset its spending period.
- Reuse the approved card across periods, within its spending limit and expiry. Don’t create a new request each period.
- A recurring card still expires. Check the request’s
expires_atand the card’svalid_until.
This timing is documented for recurring virtual cards. Don’t assume Shared Payment Tokens or Link Pay Tokens share it, even though they accept the same recurring inputs.
Cancel a recurring payment
Two separate steps stop a subscription:
- Cancel the subscription with the merchant so it stops billing.
- Run
link-cli spend-request cancelto revoke the Link credential.
cancel revokes the credential only. It doesn’t cancel the merchant’s subscription, and the merchant can still try to bill until you cancel there.
Handle required actions
Read the next action from the branch matching the returned status: status_details.requires_action.next_action for requires_action, or status_details.failed.next_action for failed.
Branch on the returned resolution. For auto_resume, show the customer the instructions and keep retrieving the same request. For a new-request resolution, complete the indicated recovery before creating a replacement. A failed request is already terminal, and a requires_action request isn't necessarily resumable.
See Handle errors and retries for recovery scenarios and retry guidance. If you configured a callback at creation, use returned URLs unchanged and follow the completion callback rules.
Partner verification
A card network can ask the customer to verify themselves before it issues a credential. Link reports this as partner_auth_challenge (auto_resume) or partner_auth_challenge_retry (create_new_spend_request). Keep branching on resolution, not on a fixed list of action types.
action_urlcan benull. Don’t assume verification has a browser URL; always showdisplay_message, and show the link only whenaction_urlis present.- Don’t create a replacement request just because a
partner_auth_challengeis pending. Keep polling the same request until its status changes. - If verification times out, retrieve the same request to learn its current status. Don’t automatically create another. Create a new request only when the action is
partner_auth_challenge_retryor another action with acreate_new_spend_requestresolution.
In an interactive terminal, spend-request create --request-approval and spend-request request-approval keep polling through an auto_resume action reached after approval. In agent or other non-interactive mode, the command returns instead of polling, so follow the returned continuation for the same request. A successful exit doesn’t prove approval or payment; inspect the returned status.
Handle errors and retries
Plan how your integration handles authentication failures, rate limits, and uncertain request outcomes:
- Expired access tokens: When a request returns
401, an SDK configured with a token provider calls it once with a forced refresh and retries the request once. An SDK configured with a fixed token doesn’t retry. If a refresh request fails withinvalid_grant, the grant is no longer valid. Send the customer through authorization again. - Rate limits and server errors: The SDKs don’t retry
429or5xxresponses. Use bounded exponential backoff with jitter and your own operation tracking. - Timeouts: The Python SDK uses a 30-second timeout by default. The Go SDK uses
http.DefaultClientunless you passHTTPClient, which has no timeout, so set one. - Link CLI: Errors are JSON objects with
codeandmessagefields, and the exit code is1. APOLLING_TIMEOUTerror is markedretryable. Retrieve the same request again instead of creating another.
Read the response
After creating a spend request, the response might contain a request with status: "failed". Depending on the response, you might need to ask the customer to complete an action or create a new spend request with different parameters. Inspect these details in the returned response:
| Response status | Inspect | Meaning |
|---|---|---|
failed | status_details.failed.code and optional status_details.failed.next_action | The request has failed and must be recreated to try again. If next_action is present, use it to give the customer recovery instructions before creating a new request. |
requires_action | status_details.requires_action.next_action | Ask the customer to follow the instructions in next_action to continue approval. Follow resolution to determine whether to continue the same request or create a new one. |
Evaluate next_action
Use these properties to understand the required customer action:
| Property | How to use it |
|---|---|
resolution | Determine whether the spend request can continue or must be recreated. See Handle the next action for resolution types. |
type | Identify the customer action, such as identity verification or updating a payment method. See Failure scenarios and examples for action types and recovery guidance. |
display_message | A suggested message to show the customer. |
action_url | A suggested URL for the customer to visit when an action is required. |
expires_at | The ISO 8601 expiry for the action URL. Can be null. |
Handle the next action
Use resolution to control the workflow and type to identify the action the customer must take.
| Resolution | What to do |
|---|---|
auto_resume | Show action_url to the customer. Keep retrieving the same spend request until its status or action changes. |
create_new_spend_request_after_completion | Ask the customer to complete verification or setup, then create a new spend request. For verification, check completion as described in Confirm verification completion. For supported setup actions, use a completion callback to return the customer to your app. |
create_new_spend_request | First follow the returned instructions, such as selecting another payment method or correcting the amount. Then create a new spend request with appropriate purchase authorization. |
Confirm verification completion
For verification actions, call GET /userinfo or run link-cli user-info retrieve --format json to check agent_wallet_step_up.status. After the status is complete or not_required, create a new spend request. If the field is absent, completion hasn't been confirmed.
Failure scenarios and examples
| Failure code | Action type | Resolution | Customer action | Recovery guidance |
|---|---|---|---|---|
verification_required | ssn_verification | create_new_spend_request_after_completion | Complete the requested verification. | Returned when you create a spend request that requires verification. Send the customer to next_action.action_url. |
verification_required | identity_verification | create_new_spend_request_after_completion | Complete identity verification. | Returned when you create a spend request that requires identity verification. Send the customer to next_action.action_url. |
verification_required | contact_support | create_new_spend_request_after_completion | Contact Link support and resolve the verification issue. | Wait for resolution before creating a replacement. |
link_payment_method_authorization_declined | select_payment_method | create_new_spend_request | Select another eligible payment method. | Returned when another eligible method is available. |
link_payment_method_authorization_declined | add_payment_method | create_new_spend_request_after_completion | Add an eligible payment method. | Returned when no other eligible method is available. |
authorization_declined | update_payment_method | create_new_spend_request | Update the expired payment method. | Returned for an expired payment method. |
avs_mismatch | update_payment_method | create_new_spend_request | Correct the billing address. | Send the customer to next_action.action_url. |
cvc_check_failed | update_payment_method | create_new_spend_request | Update the payment method's security code. | Send the customer to next_action.action_url. |
missing_cardholder_name | update_payment_method | create_new_spend_request | Add the cardholder name. | Send the customer to next_action.action_url. |
overspend_limit | re_authorize | create_new_spend_request | Authorize the correct purchase amount, or reduce the purchase to fit the authorized amount. | Create a new spend request. |
| None required | three_d_secure | auto_resume | Complete the bank's 3D Secure (3DS) challenge. | Ask the customer to complete next_action. Keep retrieving the same request. |
authorization_declined | three_d_secure_retry | create_new_spend_request | Follow the instructions to retry bank verification. | Create a new spend request. |
| None required | partner_auth_challenge | auto_resume | Complete card-network verification, such as Visa verification. | Ask the customer to complete next_action. Keep retrieving the same request. |
| None required | partner_create_card_enrollment | auto_resume | Complete agentic token enrollment through the returned URL. | Ask the customer to complete next_action. Keep retrieving the same request. |
transaction_not_permitted | None | None | Inform the customer that the transaction can't proceed. | Terminal failure. Don't retry. |
Sample responses
These JSON excerpts illustrate the recovery flows. Use the values returned by Link in your integration.
Identity verification
This failed request requires verification before you create a replacement:
{
"status": "failed",
"status_details": {
"failed": {
"code": "verification_required",
"next_action": {
"type": "identity_verification",
"resolution": "create_new_spend_request_after_completion",
"display_message": "Complete identity verification to continue.",
"action_url": "https://app.link.com/finish_setup?verify=identity_verification",
"expires_at": null
}
}
}
}Payment-method recovery
Ask the customer to choose another eligible payment method before creating a replacement. A null URL means there's no browser redirect for this action:
{
"status": "failed",
"status_details": {
"failed": {
"code": "link_payment_method_authorization_declined",
"next_action": {
"type": "select_payment_method",
"resolution": "create_new_spend_request",
"display_message": "Select another payment method to continue.",
"action_url": null,
"expires_at": null
}
}
}
}Live 3DS challenge
Send the customer to the returned action URL, then keep retrieving this request:
{
"id": "lsrq_example",
"status": "requires_action",
"status_details": {
"requires_action": {
"next_action": {
"type": "three_d_secure",
"resolution": "auto_resume",
"display_message": "Complete your bank's verification to continue.",
"action_url": "https://app.link.com/finish_setup?verify=3ds_complete&spend_request_id=lsrq_example",
"expires_at": "2027-01-15T12:00:00Z"
}
}
}
}Failed 3DS recovery
This response requires a new spend request because resolution is create_new_spend_request:
{
"status": "failed",
"status_details": {
"failed": {
"code": "authorization_declined",
"next_action": {
"type": "three_d_secure_retry",
"resolution": "create_new_spend_request",
"display_message": "The verification attempt failed. Create a new request to try again.",
"action_url": null,
"expires_at": null
}
}
}
}Terminal failure without an action
For transaction_not_permitted, don't keep retrieving the failed request or create a new spend request:
{
"status": "failed",
"status_details": {
"failed": {
"code": "transaction_not_permitted"
}
}
}Retry safely
When next_action is present, complete it before creating a new spend request. If no action is returned, follow the failure code and API error guidance. For example, payment_credential_creation_failed requires a new spend request, while transaction_not_permitted must not be retried. Link rate-limits duplicate spend requests based on a combination of fields, such as amount, currency, business name, line items, and payment details.
Completion callbacks
A completion callback returns the customer to your app after a supported approval or required action. It improves continuity when the customer leaves your app to finish verification or payment-method setup. It's separate from the OAuth redirect and a server-to-server webhook, and it doesn't prove that a purchase succeeded.
Configure the callback when you create the spend request. To use a callback, you must supply both completion_callback_url and nonce. Supplying only one returns an error. The following JSON is an excerpt to add to your create parameters:
{
"completion_callback_url": "https://agent.example.com/link/callback",
"nonce": "example-opaque-nonce-replace-with-a-random-value"
}Sample URL with callback:
https://agent.example.com/link/callback?nonce=example-opaque-nonce-replace-with-a-random-value&status=successCallback requirements
- Use HTTPS in live mode. The callback must be a valid URL with a host and no embedded username or password.
- Keep the callback URL within 2,048 characters, including the nonce added to it. Leave room for URL encoding when choosing its length.
- Generate an unpredictable, opaque nonce using a cryptographically secure random source. It must contain a character other than whitespace and be no longer than 512 UTF-16 code units.
- Persist the nonce with the request and compare it exactly on return. Don't trim or normalize it.
When the customer returns, validate the nonce, retrieve the spend request, and apply the same resolution and lifecycle rules.
Recover from unavailable payment details
When selected payment details are unavailable to the authenticated account, Link returns HTTP 404:
{
"error": {
"code": "payment_details_not_found",
"message": "The specified payment details were not found or are not available. Fetch and use current payment details before resubmitting the request."
}
}Handle this failure by error.code, not by matching the message. Link intentionally does not reveal whether the ID is missing, inactive, or belongs to another account. The response applies to these operations:
POST /spend_requestswith selected payment detailsPOST /spend_requests/create_delegatedwith selected payment detailsPOST /spend_requests/:idwhen replacing payment details through the regular update operationPOST /spend_requests/:id/request_approvalwhen the request’s stored payment details are unavailable
Requesting approval starts the approval process; it is distinct from the customer actually approving the request.
Clear the stale selection, fetch GET /payment-details, obtain appropriate purchase authorization for a currently available eligible method, and then resubmit the intended operation. Deleting and re-adding the same underlying card can produce a new payment-details ID. The unavailable ID continues to fail while it remains unavailable, so do not retry it unchanged or silently substitute a default or different card.
A rejected create makes no new spend request and starts no approval. It is not a failed payment or a requires_action spend request. For an existing request, use the regular update operation to replace the stale selection when the request state permits, and then request approval again. If the state does not permit editing, follow the existing lifecycle rules rather than inventing a transition or unconditionally recreating the request.
Resubmission remains subject to existing purchase authorization and idempotency rules. Do not automatically omit an explicit payment-details ID, choose a new idempotency key, or repurchase something that was already completed or canceled. Handle service errors through your existing error and retry policy instead of clearing the payment-method selection.
Recover from an uncertain create
If a create call fails and you don’t know whether Link received it, don’t create a second request blindly.
- Create requests with an
idempotency_keyso that repeating the call returns the original response. - If Link rejects a create as a duplicate, it responds with HTTP
429and the codespend_request_rate_limited. The error details include the existing request. UsegetDuplicateSpendRequest(TypeScript),GetDuplicateSpendRequest(Go), orget_duplicate_spend_request(Python) to read it, then continue with that request instead of creating a new one. - Otherwise, list requests with
includeHistoryenabled to find the one you created.
Use the recovery example for TypeScript, Go, or Python.
Report purchase outcomes
Reporting is optional, but it helps improve agent checkout reliability.
link-cli report \
--domain shop.example.com \
--outcome success \
--spend-request-id lsrq_abc123
link-cli report \
--domain shop.example.com \
--outcome blocked \
--spend-request-id lsrq_abc123 \
--tag captcha \
--step "checkout page" \
--freeform-context "Turnstile challenge appeared"Supported outcomes are success, blocked, and abandoned. Add one or more --tag values to explain the result: stripe_checkout, captcha, anti_bot_script, cdn_block, waf_block, dns_block, rate_limited, login_required, 3ds_challenge, page_inaccessible, timeout, site_error, payment_declined, or other.
Use --step (up to 500 characters) to say where the agent was, and --attempt-trace for a numbered, step-by-step record of the attempt, one line per step. Replace personal data with placeholders such as [email] and [address]. The server truncates traces longer than 8,000 characters instead of rejecting them.