Skip to content
Create account or Sign in
The Stripe Docs logo
/
Create accountSign in

Enable in-context selling on AI agentsPrivate preview

Learn how to start selling your products in-context on AI agents using a low-code solution.

Private preview

If your business wants to use agentic commerce to sell products, join the waitlist.

Note

This guide is for ecommerce businesses. If you’re a marketplace and want to offer in-context agentic selling on your platform, see our guide for platforms and marketplaces.

Set up your Stripe account

If you don’t already have a Stripe account, create one. After verifying your email, you need to activate payments by providing detailed business and personal information, linking a bank account for payouts, and setting up security features like two-step authentication.

Then, create your business’s public identity by setting up a Stripe profile in the Dashboard.

Configure taxes

Use Stripe Tax to manage taxes and apply configurations to individual products. Follow the tax setup guide to configure Stripe Tax.

In your product catalog CSV upload, set the stripe_product_tax_code column to associate a product with a tax treatment.

Stripe also supports tax calculations by third-party tax providers, including Anrok, Avalara, Sphere.

Upload your product catalog data to Stripe

Create a CSV file that conforms to the Stripe product catalog spec.

Upload the catalog data to Stripe

Deliver the feed in the Stripe Dashboard or through the Stripe API. You can send updates every 15 minutes.

You can use Stripe APIs to upload your product catalog CSV. We recommend using sandbox to validate parsing, field mappings, and data quality before enabling live updates.

First, upload your product catalog CSV using the Files API. A successful request returns a File object, which includes the id.

  • Specify the data_management_manual_upload purpose.
  • The MIME type of the file upload must correspond to its file format. Acceptable formats include CSV and TSV, where each row represents one product or variant.
  • The maximum file size is 200 MB.
Command Line
curl https://files.stripe.com/v1/files \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -F purpose=data_management_manual_upload \
  -F file="@/path/to/your/file.csv;type=text/csv"

Then, use the Data Management API to create an ImportSet. This call starts catalog processing and makes the data available in the Dashboard. Include the following:

  • The file id returned
  • The preview header (for example,Stripe-Version: 2025-09-30.clover;udap_beta=v1)
Command Line
curl https://api.stripe.com/v1/data_management/import_sets \
  -H "Stripe-Version: 2025-09-30.clover;udap_beta=v1" \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d file={{FILE_ID}} \
  --data-urlencode standard_data_format="product_catalog_feed"

Monitor feed status and resolve errors

Stripe processes the catalog data, validating and cleaning it before indexing in a format that can be sent to AI agents. You can monitor Stripe’s indexing progress using the status field on the ImportSet. The status can be pending, failed, succeeded, succeeded_with_errors, pending_archive, or archived.

Command Line
curl https://api.stripe.com/v1/data_management/import_sets/{{IMPORT_SET_ID}} \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:

The response includes the status and any errors:

{
  "id": "impset_7MabcdZ8b617780e5145413",
  "object": "data_management.import_set",
  "created": 1643992696,
  "livemode": true,
  "result": {
    "errors": {
      "file": "file_234923sIENc",
      "row_count": 30
    },
    "rows_processed": 120,
    "successes": {
      "row_count": 90
    }
  },
  "status": "succeeded_with_errors"
}

If your import status is succeeded_with_errors, you can download the error report:

  1. Look for the result.errors.file field in the response.
  2. Use the Files API to retrieve the content of the error file using the file ID.
  3. The downloaded CSV file contains your original data with a leading column named stripe_error_message that describes why each row failed.
Command Line
curl https://files.stripe.com/v1/files/{{ERROR_FILE_ID}}/contents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:

The API returns a CSV file containing only the rows that failed, with a stripe_error_message column describing each error.

Respond to purchases and fulfill orders

You can monitor orders placed through AI chat agents in three ways:

View orders on the Transactions page in the Dashboard—they’re tagged with the originating agent.

Enable selling on AI chat agents

When you’re ready to sell on an AI chat agent, review the agent terms and enable the agent in the Stripe Dashboard. Stripe sends the agent an approval request that the agent must accept.

To pause or stop selling on an AI chat agent, disable the agent in the Dashboard, or send a termination request through the Stripe API:

Command Line
curl -X POST https://api.stripe.com/v2/agentic_commerce/agreements/{{AGREEMENT_ID}}/terminate \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:

We send webhooks when your agreement with an AI agent is confirmed or terminated:

  • agentic_commerce_agreement.confirmed
  • agentic_commerce_agreement.terminated

OptionalSet up manual capture

By default, Stripe captures payments immediately after purchase. To use manual capture, open the Agentic Settings page in the Dashboard and set capture mode to manual. When you enable manual capture, call the capture method on the PaymentIntent:

Command Line
curl -X POST https://api.stripe.com/v1/payment_intents/pi_3MrPBM2eZvKYlo2C1TEMacFD/capture \
  -u "<secret_key>:" \
  -H "Stripe-Version: 2025-09-30.preview"

OptionalSet up a pre-confirmation approval hook

By default, before confirming a payment, we check inventory based on your product catalog data and run fraud checks with Radar. To add control over whether to complete a purchase, configure a manual approval hook. Before we complete checkout, we send an approval request to your service. Approve or decline the request.

To set up a manual approval hook:

  1. Specify the endpoint in the Dashboard.
  2. Implement your logic at the endpoint and use the request and response formats below.

Approval request format

Stripe sends the following request to your endpoint:

{
  type: String,
  id: String,
  livemode: Boolean,
  // account ID
  context?: String,
  // request specific data
  data: {
    amount_total: Integer,
    amount_subtotal: Integer,
    total_details?: {
      amount_discount?: Number,
      amount_fulfillment?: Number,
      amount_tax?: Number
    },
    currency: String,
    line_items_details: Array<{
      sku_id: String,
      unit_amount: Number,
      quantity: Number,
      amount_subtotal: Integer,
      amount_total: Integer,
      amount_tax: Integer,
      amount_discount: Integer
    }>,
    payment_method_details?: {
      type: "card" | ...,
      card?: {
        brand: "amex" | "visa" | "master_card" | ...,
        country?: String,
        exp_month: Number,
        exp_year: Number,
        funding: "credit" | "debit" | "prepaid" | "unknown",
        last4: String,
        wallet?: {
          type: "apple_pay" | "google_pay" | ...
        }
      },
      billing_details?: {
        name?: String,
        address?: {
          line1?: String,
          line2?: String,
          city?: String,
          state?: String,
          postal_code?: String,
          country?: String
        }
      },
    },
    fulfillment_details?: {
      name?: String,
      address?: {
        line1?: String,
        line2?: String,
        city?: String,
        state?: String,
        postal_code?: String,
        country?: String
      },
      email?: String,
      phone?: String,
    }
  }
}

Response format 

{
  manual_approval_details?: {
    type: "approved" | "declined",
    declined?: {
      reason: String
    }
  }
}

OptionalSet up shipping options hook

By default, Stripe computes shipping options for your products based on the options defined in your product catalog. Each option includes a name, description, estimated delivery time, and cost. You can configure free shipping per product in the product catalog.

To compute shipping options and costs dynamically with your own logic, implement the shipping options hook. We call your hook before returning checkout to the agent, with the items in the cart. The agent UI then renders the shipping options and prices you compute.

Request format

The following example shows the inputs in the compute_shipping_options request that we send to the reverse API endpoint you configure to calculate shipping options:

{
  livemode: Boolean,
  currency: String,
  amount_total: Integer,
  amount_subtotal: Integer,
  total_details?: {
      amount_discount?: Number,
      amount_tax?: Number
  },
  line_items_details: [
      {
        sku_id: String,
        unit_amount: Integer,
        quantity: Integer,
        amount_subtotal: Integer,
        amount_total: Integer,
        amount_tax: Integer,
        amount_discount: Integer
      }
    ],
  fulfillment_details?: {
      address?: {
        line1?: String,
        line2?: String,
        city?: String,
        state?: String,
        postal_code?: String,
        country?: String
      }
    }
  }

Response format 

HTTP/1.1 200 OK
{
  fulfillment_options: [
    {
        display_name: String,
        description: String,
        earliest_delivery_time: Integer,
        latest_delivery_time: Integer,
        shipping_amount: Integer
     }
  ]
}

OptionalSend incremental inventory updates

In addition to uploading your product catalog, send individual product inventory updates through the Inventory Feed API. Use the same upload process as catalog uploads, but set standard_data_format to inventory_feed:

Command Line
# Step 1: Upload your CSV using the Files API
curl https://files.stripe.com/v1/files \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -F purpose=data_management_manual_upload \
  -F file="@/path/to/your/file.csv;type=text/csv"

# Step 2: Create an ImportSet object
curl https://api.stripe.com/v1/data_management/import_sets \
  -H "Stripe-Version: 2025-09-30.clover;udap_beta=v1" \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d file={{FILE_ID}} \
  --data-urlencode standard_data_format="inventory_feed"

OptionalHandle refunds and disputes

After checkout succeeds, if a customer cancels the order on your website or through customer service, initiate a refund. If you already use the Checkout Sessions or PaymentIntents API, your existing refund flow works without changes for agentic checkouts.

You can manage refunds and disputes in the Dashboard on the Transactions page, or use the Refunds API to handle cancellations and refunds programmatically.

See also