Skip to content
Create account or Sign in
The Stripe Docs logo
/
Create accountSign in
OverviewAccept a paymentUpgrade your integration
Online payments
OverviewFind your use caseRecurring payments
In-person payments
Payment methods
Payment operations
Balances and settlement timeReceiptsRefunds and cancellations
Advanced integrations
Beyond payments

Enable in-context selling on AI agentsPrivate preview

Learn how to start selling your products in-context using AI agents.

Private preview

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

Note

Use this guide if you run an e-commerce business. If you operate 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 you verify your email, activate payments by providing business and personal information, linking a bank account for payouts, and setting up two-step authentication. Then, go to Agentic Commerce Onboarding in the Stripe Dashboard. This guides you through creating a Stripe Profile and configuring settings for agentic commerce.

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, and 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

Send the feed in the Stripe Dashboard or through the Stripe API. You can upload feeds at whatever interval you choose. To keep data current, upload product data once per day and send more frequent incremental updates for inventory and pricing.

Note

Feed uploads are processed as independent, asynchronous tasks. We don’t guarantee uploads are processed or completed in the order you submit them. If you upload multiple files in quick succession, a later upload can finish before an earlier one.

Use Stripe APIs to upload your product catalog CSV. We recommend using the 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 match 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 that the Files API 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 your catalog data, validates and cleans it, then indexes it in a format you can send to AI agents. You can monitor indexing progress in two ways:

Make a GET request and check the status field on the ImportSet object. 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}} \
  -H "Stripe-Version: 2025-09-30.clover;udap_beta=v1" \
  -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

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 sales on an AI chat agent

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.

Test your integration

You can test your integration directly from the Dashboard in a sandbox:

  1. Go to the Agentic Commerce page, then click View catalog.
  2. Hover over the product you want to test, then click Test in Workbench.

OptionalSet up manual capture

By default, Stripe captures payments immediately after purchase. To use manual capture, open the Agentic Commerce 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 order approval hook

Before confirming a payment, we check inventory based on your product catalog data and run fraud checks with Radar by default. To add control over whether to complete a purchase, configure a order approval hook. Before we complete checkout, we send an approval request to your service. Approve or decline the request. Stripe imposes a 4 second timeout threshold on your hook. If your hook doesn’t respond within this threshold, Stripe declines the payment.

To set up a manual approval hook:

  1. Specify the endpoint on the Agentic Commerce Settings page in the Dashboard.
  2. Toggle on Order approvals.
  3. 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: "v1.delegated_checkout.finalize_checkout",
  id: string,
  livemode: boolean,
  // account ID
  context?: string,
  // request specific data
  data: {
    amount_subtotal?: number,
    amount_total?: number,
    billing_details?: {
      name?: string,
      address?: {
        line1?: string,
        line2?: string,
        city?: string,
        state?: string,
        postal_code?: string,
        country?: string
      }
    },
    currency: string,
    email?: string,
    line_items_details: Array<{
      id: string,
      unit_amount: number,
      quantity: number,
      name: string
    }>,
    payment_method_details?: {
      type: "card" | ...,
      card?: {
        brand: "amex" | "visa" | "master_card" | ...,
        country?: string,
        exp_month: number,
        exp_year: number,
        fingerprint?: string,
        funding: "credit" | "debit" | "prepaid" | "unknown",
        iin?: string,
        last4: string,
        wallet?: {
          type: "apple_pay" | "google_pay" | ...
        }
      }
    },
    phone?: string,
    shipping_details?: {
      name?: string,
      address?: {
        line1?: string,
        line2?: string,
        city?: string,
        state?: string,
        postal_code?: string,
        country?: string
      },
    },
    total_details?: {
      amount_discount?: number,
      amount_shipping?: number,
      amount_tax?: number
    }
  }
}

Pre-confirmation approval response format

Your endpoint needs to return 200 HTTP responses with the following format:

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

OptionalSet up checkout customization hook

By default, Stripe computes taxes and shipping options for your products based on the options defined in your product catalog.

To compute taxes or shipping options and costs dynamically with your logic:

  1. Specify the endpoint on the Agentic Commerce Settings page in the Dashboard.
  2. Toggle on Custom tax rates or Custom shipping options.
  3. Implement your logic at the endpoint and use the request and response formats below.

Request format

Stripe sends the following request to your endpoint:

{
  type: "v1.delegated_checkout.customize_checkout",
  id: string,
  livemode: boolean,
  // Connected account ID
  context?: string,
  // Request specific data
  data: {
    // Used by the seller to determine whether they can set manual tax rates on line items
    automatic_tax: {
      enabled: boolean,
    },
    currency: string,
    line_item_details?: Array<{
      id: string,
      sku_id: string,
      unit_amount: number,
      amount_discount: number,
      amount_subtotal: number,
      amount_tax: number,
      amount_total: number,
      quantity: number,
      name: string,
      tax_rates: Array<{
        rate: {
          id: string,
          display_name: string,
          percentage: float,
          inclusive: boolean,
        }
        // Amount of tax applied for this rate.
        amount: number
      }>
    }>,
    shipping_details?: {
      // Same as the shipping rate object described at https://docs.stripe.com/api/shipping_rates/object#shipping_rate_object
      shipping_rate?: {
        id: string,
        display_name?: string,
        metadata?: Map<string,string>,
        tax_code?: string ,
        tax_behavior: 'unspecified' | 'included' | 'excluded',
        fixed_amount: {
          amount: number,
          currency: 'usd' | 'cad' | etc.,
          currency_options.<currency>: {
            amount: number,
            tax_behavior: 'unspecified' | 'included' | 'excluded',
          }
        },
        delivery_estimate?: {
          maximum: { unit: 'business_day' | 'day' | 'hour' | 'month' | 'year', value: number },
          minimum: { unit: 'business_day' | 'day' | 'hour' | 'month' | 'year', value: number }
        }
      },
      // Same as the shipping rate object described at https://docs.stripe.com/api/shipping_rates/object#shipping_rate_object
      shipping_rates?: Array<{
        id: string,
        display_name?: string,
        metadata?: Map<string,string>,
        tax_code?: string,
        tax_behavior: 'unspecified' | 'included' | 'excluded',
        fixed_amount: {
          amount: number,
          currency: 'usd' | 'cad' | etc.,
          currency_options.<currency>: {
            amount: number,
            tax_behavior: 'unspecified' | 'included' | 'excluded',
          }
        },
        delivery_estimate?: {
          maximum: { unit: 'business_day' | 'day' | 'hour' | 'month' | 'year', value: number },
          minimum: { unit: 'business_day' | 'day' | 'hour' | 'month' | 'year', value: number }
        }
      },
      address?: {
        line1?: string,
        line2?: string,
        city?: string,
        state?: string,
        postal_code?: string,
        country?: string
      }
    },
    amount_total?: number,
    amount_subtotal?: number,
    total_details?: {
      amount_discount?: number,
      amount_shipping?: number,
      amount_tax?: number
    }
  }
}

Shipping options response format

Your endpoint must return a 200 HTTP response with the following format:

{
  shipping_options?: Array<{
    // ID of the shipping rate, or data provided to create the shipping rate. Only provide one; not both
    shipping_rate?: string,
    shipping_rate_data: {
      display_name?: string,
      fixed_amount: {
        amount: number,
        currency: 'usd' | 'cad' | etc.,
      },
      metadata?: Map<string,string>,
      tax_code?: string ,
      tax_behavior?: 'unspecified' | 'included' | 'excluded',
      // Same as the shipping rate object described at https://docs.stripe.com/api/shipping_rates/create#create_shipping_rate-delivery_estimate
      delivery_estimate?: {
        maximum: { unit: 'business_day' | 'day' | 'hour' | 'month' | 'year', value: number },
        minimum: { unit: 'business_day' | 'day' | 'hour' | 'month' | 'year', value: number }
      }
    },
  }>,
  line_items?: Array<{
    // Corresponding ID of the line item to update
    id: string,
    // List of tax rates to apply to this line item
    // Provide either `rate` or `rate_data`
    tax_rates: Array<{
      // ID of a v1 tax rate
      rate?: string,
      // Or `rate_data`.
      // This will use an existing tax rate that matches the params or will create one if a matching rate does not exist
      rate_data?: {
        display_name: string,
        inclusive: boolean,
        // percentage out of 100
        percentage: float,
      }
    },
  }>
}

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"

OptionalSend incremental price updates

Upload your product catalog, then send individual price updates through the Price Feed API. Use the same upload process as catalog uploads and set standard_data_format to price_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="price_feed"

OptionalHandle refunds and disputes

If a customer cancels the order on your website or through customer service after checkout succeeds, 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