# Enable in-context shopping on AI agents

Learn how to let your businesses sell their products on AI chat agents.

> If your platform wants to use agentic commerce to sell your businesses’ products, [join the waitlist](https://go.stripe.global/agentic-commerce-contact-sales). Agentic commerce for platforms is available to businesses in the US and requires waitlist approval.

Use agentic commerce to let your connected accounts sell products through AI chat agents. Your platform uploads [product feed data](https://docs.stripe.com/agentic-commerce/product-feed.md) and configures checkout hooks for tax and fees, and connected accounts opt in to agent channels. When a buyer makes a purchase through an agent, Stripe runs checkout and calls your platform’s hooks before completing the transaction.
A simplified overview of the agentic commerce flow for platforms (See full diagram at https://docs.stripe.com/connect/saas/tasks/enable-in-context-selling-on-ai-agents)
## Set up your platform

Go to the [Agentic commerce settings](https://dashboard.stripe.com/settings/connect/agentic-commerce) page in the Dashboard to onboard your platform. The onboarding wizard guides you through:

- Creating a [Stripe Profile](https://docs.stripe.com/get-started/account/profile.md) for your platform.
- Choosing your charge type (*direct* (A charge type where customers transact directly with a connected account, which is always the merchant of record. With each payment, the connected account pays fees to Stripe and, optionally, to your platform) or *destination* (A charge type where customers transact with your platform for products or services provided by a connected account. Your platform pays Stripe fees and immediately transfers funds to the connected account with each payment) with *on\_behalf\_of* (A parameter that allows a Connect platform to create an indirect payment where the connected account is the merchant of record (MoR))).
- Enabling AI agent channels your connected accounts can sell through.
- Configuring seller settings, including your webhook endpoint, receipt type and support policies.

After you complete onboarding, you can manage these settings from the same page.

## Choose your charge type

In the in-context shopping flow, Stripe creates an agentic checkout session for your platform. To create the session, Stripe needs to know which charge type to use. Stripe supports direct charges and destination charges with the `on_behalf_of` parameter. In both charge types, the connected account acts as the seller.

Configure your charge type during [platform onboarding](https://docs.stripe.com/connect/saas/tasks/enable-in-context-selling-on-ai-agents.md#set-up-platform), or update it later from the [Agentic commerce settings](https://dashboard.stripe.com/settings/connect/agentic-commerce) page in the Dashboard.

## Upload your product catalogue data to Stripe

### Prepare your product catalogue

For each connected account, create a CSV file that conforms to the [Stripe product catalogue specification](https://docs.stripe.com/agentic-commerce/product-feed.md).

### Upload the product catalogue data to Stripe

Upload product catalogue data for each connected account separately. You can send updates every 15 minutes. Use a sandbox to validate parsing, field mappings and data quality before enabling live updates.

#### API

Create a `ProductCatalogImport` for the connected account. A successful request returns a [ProductCatalogImport object](https://docs.stripe.com/api/v2/commerce/product-catalog-imports/object.md) in the `awaiting_upload` state. The `status_details.awaiting_upload.upload_url.url` field in the response contains the presigned URL for your file upload. The maximum upload size is 4GB.

```curl
curl -X POST https://api.stripe.com/v2/commerce/product_catalog/imports \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-04-22.preview" \
  -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \
  --json '{
    "feed_type": "product",
    "mode": "upsert",
    "metadata": {
        "file_name": "march_11_2026_product_upload.csv"
    }
  }'
```

```json
{
  "id": "pcimprt_xxx",
  "object": "v2.commerce.product_catalog_import",
  "created": "2026-03-26T00:35:01.000Z",
  "feed_type": "product",
  "status": "awaiting_upload",
  "status_details": {
    "awaiting_upload": {
      "upload_url": {
        "expires_at": "2026-03-26T00:40:02.000Z",
        "url": "https://stripeusercontent.com/files/us-west-2/upload/wksp_xxx"
      }
    }
  },
  "livemode": true
}
```

Upload your CSV to the presigned URL. The file must be in CSV or TSV format, where each row represents one product or variant. The maximum file size is 4 GB.

```curl
curl -X PUT \
  -H "Content-Type: text/csv" \
  --data-binary @"/path/to/your/file.csv" \
  "{{PRESIGNED_URL}}"
```

After Stripe receives the file, the import transitions from `awaiting_upload` to `processing`.

### Monitor feed status

Stripe validates and cleans the product catalogue data, indexes it and converts it to a format that AI agents can use. Poll the [import object](https://docs.stripe.com/api/v2/commerce/product-catalog-imports/object.md) until it reaches a terminal state: `succeeded`, `succeeded_with_errors`, or `failed`.

```curl
curl https://api.stripe.com/v2/commerce/product_catalog/imports/{{PRODUCTCATALOGIMPORT_ID}} \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-04-22.preview" \
  -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}"
```

Alternatively, listen for the `v2.commerce.product_catalog.imports.succeeded`, `v2.commerce.product_catalog.imports.succeeded_with_errors` and `v2.commerce.product_catalog.imports.failed` terminal webhook events. The webhook includes the import ID in `related_object.id`, which you can use to retrieve the full object.

If the import completes without errors, it reaches `succeeded`. If the file is structurally valid but contains row-level validation issues, the import reaches `succeeded_with_errors`. If the import can’t complete, for example because the file was never uploaded, the file is unreadable or an internal error occurs, it reaches `failed`.

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

1. Find the `status_details.succeeded_with_errors.error_file.url` field in the response.
1. Download the CSV directly from that URL before it expires.
1. The CSV contains only the rows that failed, with a leading `stripe_error_message` column describing each error.

> Error file URLs expire after 5 minutes. To get a new URL, call the [retrieve endpoint](https://docs.stripe.com/api/v2/commerce/product-catalog-imports/retrieve.md) again.

#### Dashboard

Go to the **Connected accounts** page and select the account, then scroll to the **Money Management** section. Under **Agentic commerce**, upload a product catalogue CSV for that account. You can view catalogue errors and product catalogue status from this page.

You can also filter your connected accounts list by **Product catalogue status** to see which accounts have catalogues uploaded.

## Configure taxes for your connected accounts

Use Stripe Tax for fully managed tax calculations, or implement a tax hook in your integration if you need custom tax logic or must integrate a third‑party tax provider.

#### Automated tax calculation with Stripe Tax

Use Stripe Tax to calculate and collect tax for each of your connected accounts. See the [Tax for platforms setup](https://docs.stripe.com/tax/tax-for-platforms.md) to configure Stripe Tax.

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

See [tax codes](https://docs.stripe.com/tax/tax-codes.md) for the full list of supported tax codes.

You can also calculate taxes through [third-party tax providers](https://docs.stripe.com/tax/third-party-apps.md), such as Anrok, Avalara and Sphere.

#### Custom tax calculation with hooks

Use a [checkout customisation hook](https://docs.stripe.com/connect/saas/tasks/enable-in-context-selling-on-ai-agents.md#checkout-customization-hook) to handle the `v1.delegated_checkout.customize_checkout` event and return `tax_rates` for each line item.

To set up the tax hook:

1. Create an endpoint on your server to receive checkout customisation events.

See [webhooks](https://docs.stripe.com/webhooks.md) for more information about setting up webhooks in your application.

#### Node.js

```javascript
const stripe = require('stripe');
const express = require('express');
const app = express();

app.use("/checkout-customization-hook", express.raw({ type: "application/json" }));
app.post("/checkout-customization-hook", (req, res) => {
  const sig = req.headers["stripe-signature"];
  const endpointSecret = process.env.WEBHOOK_SECRET; // Store this securely

  try {
    stripe.webhooks.signature.verifyHeader(req.body, sig, endpointSecret, stripe.webhooks.DEFAULT_TOLERANCE);
  } catch (err) {
    console.log(`Webhook signature verification failed: ${err.message}`);
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  const event = JSON.parse(req.body);
  if (event.type === "v1.delegated_checkout.customize_checkout") {
    const data = event.data;
    const connectedAccount = event.context;

    const response = {
      line_items:
        data.line_item_details?.map((item) => ({
          id: item.id,
          tax_rates: [
            {
              rate_data: {
                display_name: "Sales tax",
                inclusive: false,
                percentage: 8.5, // Replace with your actual tax rate
              },
            },
            {
              rate_data: {
                display_name: "Environmental fee",
                inclusive: false,
                percentage: 1.0, // Replace with your actual fee rate
              },
            },
          ],
        })) || [],
    };

    return res.status(200).json(response);
  }

  return res.status(400).json({ error: "Unsupported webhook type" });
});

app.listen(4567, () => console.log("Server is running on port 4567"));
```

1. Register your webhook endpoint URL on the [Agentic commerce settings](https://dashboard.stripe.com/settings/connect/agentic-commerce) page in the Dashboard.
1. Handle the `v1.delegated_checkout.customize_checkout` event and return tax rates for each line item, as shown in the code example.

## Monetise transactions

By default, when you create an agentic checkout session, no application fee is applied.

> You must add an application fee when your platform pays Stripe fees for a connected account. Without an application fee, you can lose money on each transaction.

#### Application fee hook

Use a [checkout customisation hook](https://docs.stripe.com/connect/saas/tasks/enable-in-context-selling-on-ai-agents.md#checkout-customization-hook) to handle the `v1.delegated_checkout.finalize_checkout` event and return an application fee.

See [webhooks](https://docs.stripe.com/webhooks.md) for information about setting up webhooks in your application.

#### Node.js

```javascript
const stripe = require('stripe');
const express = require('express');
const app = express();

app.use("/agentic-commerce-hook", express.raw({ type: "application/json" }));
app.post("/agentic-commerce-hook", async (req, res) => {
  const sig = req.headers["stripe-signature"];
  const endpointSecret = process.env.WEBHOOK_SECRET; // Store this securely

  try {
    stripe.webhooks.signature.verifyHeader(req.body, sig, endpointSecret, stripe.webhooks.DEFAULT_TOLERANCE);
  } catch (err) {
    console.log(`Webhook signature verification failed: ${err.message}`);
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  const event = JSON.parse(req.body);
  console.log("Received event:", event.type);
  if (event.type === "v1.delegated_checkout.finalize_checkout") {
    const data = event.data;
    // Perform validation checks for order approval
    const orderAmount = data.amount_total || 0;
    const lineItems = data.line_items_details || [];
    const connectedAccount = event.context;
    const stripeCheckoutSessionId = data.checkout_session;

    const applicatonFee = await calculateApplicationFee(lineItems);
    const {reason, isApproved} = await calculateOrderApproval();

    if (isApproved) {
      return res.status(200).json({
        manual_approval_details: {
          type: "approved"
        },
        application_fee_details: {
          application_fee_amount: applicatonFee
        }
      });
    } else {
      return res.status(200).json({
        manual_approval_details: {
          type: "declined",
          declined: {
            reason,
          }
        }
      });
    }
  }

  return res.status(400).json({ error: "Unsupported webhook type" });
});

app.listen(4567, () => console.log("Server is running on port 4567"));
```

#### Charge an application fee with the platform pricing tool

If a connected account uses a fee payer configuration where your platform pays Stripe fees, you can use the [platform pricing tool](https://docs.stripe.com/connect/platform-pricing-tools.md) to charge an application fee.

## Enable your connected accounts to sell with agents

Connected accounts must review the agent terms and enable an agent before they can sell through it. Stripe sends the agent an approval request that the agent must accept. Connected accounts can manage which AI agents sell their products, customise how their business appears across agent platforms, and pause or stop selling on any agent.

#### Embedded component

Embed the agentic commerce settings component directly in your platform’s UI to give connected accounts a native onboarding and management experience. For details on how to embed Dashboard functionality into your website, see [Get started with Connect embedded components](https://docs.stripe.com/connect/get-started-connect-embedded-components.md).

#### Ruby

```ruby
require 'sinatra'
require 'stripe'
# This is a placeholder - it should be replaced with your secret API key.
# Sign in to see your own test API key embedded in code samples.
# Don't submit any personally identifiable information in requests made with this key.
# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

post '/account_session' do
  content_type 'application/json'

  begin
    account_session = client.v1.account_sessions.create({
      account: '{{CONNECTED_ACCOUNT_ID}}',
      components: {
        agentic_commerce_settings: {
          enabled: true,
        }
      }
    })

    {
      client_secret: account_session[:client_secret]
    }.to_json
  rescue => error
    puts "An error occurred when calling the Stripe API to create an account session: #{error.message}";
    return [500, { error: error.message }.to_json]
  end
end
```

#### HTML + JS

```html
<head>
  <script type="module" src="index.js" defer></script>
</head>
<body>
  <h1>Payments</h1>
  <div id="container"></div>
  <div id="error" hidden>Something went wrong!</div>
</body>
```

```javascript
import {loadConnectAndInitialize} from '@stripe/connect-js';

const fetchClientSecret = async () => {
  // Fetch the AccountSession client secret
  const response = await fetch('/account_session', { method: "POST" });
  if (!response.ok) {
    // Handle errors on the client side here
    const {error} = await response.json();
    console.error('An error occurred: ', error);
    document.querySelector('#error').removeAttribute('hidden');
    return undefined;
  } else {
    const {client_secret: clientSecret} = await response.json();
    document.querySelector('#error').setAttribute('hidden', '');
    return clientSecret;
  }
}

const stripeConnectInstance = loadConnectAndInitialize({
    // This is a placeholder - it should be replaced with your publishable API key.
    // Sign in to see your own test API key embedded in code samples.
    // Don’t submit any personally identifiable information in requests made with this key.
    publishableKey: "<<YOUR_PUBLISHABLE_KEY>>",
    fetchClientSecret: fetchClientSecret,
  });
const paymentComponent = stripeConnectInstance.create("agentic-commerce-settings");
const container = document.getElementById("container");
container.appendChild(paymentComponent);
```

#### Full Stripe Dashboard

Connected accounts with access to the full Stripe Dashboard can onboard to agentic commerce by going to **Settings > Payments > Agentic commerce**. From this page, they can create a Stripe Profile, configure their seller settings and enable or disable agent channels.

#### Express Dashboard

Connected accounts using the Express Dashboard can go to **Settings** and find the **Agentic commerce** section. From there, they can manage their seller profile, configure settings and enable or disable agent channels.

## Respond to purchases and fulfil orders

Listen to Stripe webhooks to monitor orders made on AI chat agents.

When an order is confirmed, Stripe emits webhook events that your server can handle to run fulfilment logic. Set up an endpoint on your server to accept, process and acknowledge these events. See the [webhooks guide](https://docs.stripe.com/webhooks.md) for step-by-step instructions on integrating with and testing Stripe webhooks.

Stripe emits `checkout.session.completed` and `payment_intent.succeeded`. If your fulfilment logic already handles these events, you don’t need additional integration changes. You can customise your fulfilment logic for in-context agentic selling (for example, by noting in your order confirmation email that the checkout occurred through an agent).

For details on setting up webhooks for connected accounts, see [Connect webhooks](https://docs.stripe.com/connect/webhooks.md).

#### Node.js

```javascript
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
const express = require('express');
const app = express();

// Use the secret provided by Stripe CLI for local testing
// or your webhook endpoint's secret
const endpointSecret = 'whsec_...';

app.post('/webhook', async (request, response) => {
  const sig = request.headers['stripe-signature'];
  let event;

  try {
    event = stripe.webhooks.constructEvent(request.body, sig, endpointSecret);
  } catch (err) {
    response.status(400).send(`Webhook Error: ${err.message}`);
    return;
  }

  if (event.type === 'checkout.session.completed') {
    let session = event.data.object;
    // For V1 webhooks event.account is the connected account
    session = await stripe.checkout.sessions.retrieve(
      session.id,
      {
        expand: ["line_items.data.price.product", "line_items.data.price"],
      },
      // If using direct charges, the checkout session is created on the connected account and the `stripeAccount` parameter must be passed. If using destination charges the checkout session is created on the platform account and `stripeAccount` parameter can be ignored.
      {
        stripeAccount: "{{CONNECTED_ACCOUNT_ID}}",
      },
    );

    // SKU id is available at session.line_items.data[number].price.external_reference
    fulfillCheckout(event.account, session);
  }

  response.status(200).send();
});
```

After you receive the webhook, retrieve all required fields with a single API call. To avoid multiple requests, expand sub-resources using the [expand](https://docs.stripe.com/api/expanding_objects.md) request parameter with the preview header `Stripe-Version: 2025-12-15.preview`.

```curl
curl https://api.stripe.com/v1/checkout/sessions/{{SESSION_ID}}?expand[]=line_items.data.price.product&expand[]=line_items.data.taxes&expand[]=payment_intent.latest_charge \
  -u <<YOUR_SECRET_KEY>>: \
  -H "Stripe-Version: 2025-12-15.preview" \
  -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}"
```

See fields in the expanded [Checkout Session](https://docs.stripe.com/api/checkout/sessions/object.md), such as `amount_total`, quantity, and SKU ID.

### Checkout session field reference

| Order field                         | Available resource                            | API path                                                                            |
| ----------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- |
| **Order date**                      | `CheckoutSession.PaymentIntent.LatestCharge`  | `CheckoutSessions.PaymentIntent.LatestCharge.created`                               |
| **Order quantity**                  | `CheckoutSessions`                            | `CheckoutSession.LineItems.Data[].quantity`                                         |
| **SKU**                             | `CheckoutSessions`                            | `CheckoutSession.LineItems.Data[].price.external_reference`                         |
| **Product description**             | `CheckoutSessions`                            | `CheckoutSession.LineItems.Data[].price.product.description`                        |
| **Unit price**                      | `CheckoutSessions`                            | `CheckoutSession.LineItems.Data[].price.unit_amount`                                |
| **Tax amount**                      | `CheckoutSessions`                            | `CheckoutSession.LineItems.Data[]. Taxes[].amount`                                  |
| **Tax type**                        | `CheckoutSessions`                            | `CheckoutSession.LineItems.Data[]. Taxes[]. Rate.tax_type`                          |
| **Tax rate**                        | `CheckoutSessions`                            | `CheckoutSession.LineItems.Data[]. Taxes[]. Rate.percentage`                        |
| **ShippingAddress**                 | `CheckoutSessions`                            | `CheckoutSessions.CollectedInformation.shipping_details`                            |
| **BillingAddress**                  | `CheckoutSessions.PaymentIntent.LatestCharge` | `CheckoutSessions.PaymentIntent.LatestCharge.billing_details`                       |
| **Last4**                           | `CheckoutSessions.PaymentIntent.LatestCharge` | `CheckoutSessions.PaymentIntent.LatestCharge.payment_method_details.card.last4`     |
| **ExpMonth**                        | `CheckoutSessions.PaymentIntent.LatestCharge` | `CheckoutSessions.PaymentIntent.LatestCharge.payment_method_details.card.exp_month` |
| **ExpYear**                         | `CheckoutSessions.PaymentIntent.LatestCharge` | `CheckoutSessions.PaymentIntent.LatestCharge.payment_method_details.card.exp_year`  |
| **CreditCardType**                  | `CheckoutSessions.PaymentIntent.LatestCharge` | `CheckoutSessions.PaymentIntent.LatestCharge.payment_method_details.card.brand`     |
| **Final amount**                    | `CheckoutSessions`                            | `CheckoutSessions.amount_total`                                                     |
| **GTIN** (Private preview)          | `CheckoutSessions`                            | `CheckoutSession.LineItems.Data[].price.product.identifiers.gtin`                   |
| **MPN** (Private preview)           | `CheckoutSessions`                            | `CheckoutSession.LineItems.Data[].price.product.identifiers.mpn`                    |
| **Agent details** (Private preview) | `CheckoutSession.PaymentIntent`               | `CheckoutSessions.PaymentIntent.agent_details`                                      |
| **OrderNo**                         | `CheckoutSession.PaymentIntent.LatestCharge`  | `CheckoutSessions.PaymentIntent.LatestCharge.receipt_number`                        |

## Test your integration

You can test your integration directly from the Dashboard in a [sandbox](https://docs.stripe.com/sandboxes.md):

1. Open the [Trigger Agentic Purchase](https://dashboard.stripe.com/test/workbench/blueprints/agentic-commerce-turnkey-agentic-purchase) blueprint in Workbench
1. Enter the connected account’s ID and a SKU ID
1. Click **Run** to simulate a charge from an agent

## Optional: Manual capture

By default, Stripe captures payments immediately when a purchase completes. To use manual capture, enable it on the [Agentic commerce settings](https://dashboard.stripe.com/settings/connect/agentic-commerce) page in the Dashboard. After you enable manual capture, call the capture method on the `PaymentIntent` returned in the webhook described in the previous section.

```curl
curl -X POST https://api.stripe.com/v1/payment_intents/pi_3MrPBM2eZvKYlo2C1TEMacFD/capture \
  -u "<<YOUR_SECRET_KEY>>:"
```

## Optional: Set up an order approval hook

Before we confirm a payment, we check inventory based on your product catalogue data and might run fraud checks depending on your [Radar](https://docs.stripe.com/radar.md) setup. To control whether we complete a purchase, configure an order approval hook. Before we complete the checkout flow, we send an approval request to your service. You must approve or decline the request.

Stripe enforces a four-second timeout for your hook. If your hook doesn’t respond within this time, Stripe declines the payment.

To set up an order approval hook:

1. Specify the endpoint on the [Agentic Commerce settings](https://dashboard.stripe.com/settings/connect/agentic-commerce) page in the Dashboard.
1. Enable **Order approvals**.
1. Implement your logic at the endpoint and use the request and response formats below.

> Stripe returns a `424` status code to agents if your endpoint returns a non-`2xx` status code. Some agents might retry these API requests, so you must make sure that your endpoint is idempotent.

### Request format

Stripe sends the following request to your endpoint:

```typescript
{
  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
    }
  }
}
```

### Response format

Your endpoint must return `200` HTTP responses with the following format:

```typescript
{
  manual_approval_details: {
    type: "approved" | "declined",
    declined?: {
      reason: string
    }
  },
  // Connect only: set an application fee for the transaction
  application_fee_details?: {
    application_fee_amount: number,
    transfer_data?: {
      amount?: number,
    }
  }
}
```

## Optional: Set up a checkout customisation hook

By default, Stripe calculates taxes and shipping options for your products based on the options defined in your [product catalogue](https://docs.stripe.com/agentic-commerce/product-feed.md).

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

1. Specify the endpoint on the [Agentic Commerce settings](https://dashboard.stripe.com/settings/connect/agentic-commerce) page in the Dashboard.
1. Enable **Custom tax rates** or **Custom shipping options**.
1. Implement your logic at the endpoint and use the request and response formats below.

> Stripe returns a `424` status code to agents if your endpoint returns a non-`2xx` status code. Some agents might retry these API requests, so you must make sure that your endpoint is idempotent.

### Request format

Stripe sends the following request to your endpoint:

```typescript
{
  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: number,
          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' | 'inclusive' | 'exclusive',
        fixed_amount: {
          amount: number,
          currency: 'usd' | 'cad' | etc.,
          currency_options.<currency>: {
            amount: number,
            tax_behavior: 'unspecified' | 'inclusive' | 'exclusive',
          }
        },
        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' | 'inclusive' | 'exclusive',
        fixed_amount: {
          amount: number,
          currency: 'usd' | 'cad' | etc.,
          currency_options.<currency>: {
            amount: number,
            tax_behavior: 'unspecified' | 'inclusive' | 'exclusive',
          }
        },
        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
    }
  }
}
```

### Response format

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

```typescript
{
  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' | 'inclusive' | 'exclusive',
      // 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: number,
      }
    },
  }>
}
```

## Optional: Test your hooks

You can test your order approval or checkout customisation hook by providing a publicly accessible endpoint that can accept hook requests with a `POST` method. Set up your endpoint function so that it:

1. Handles `POST` requests with a JSON payload
1. Returns a successful status code (`200`)

For local development, use a tunnelling tool such as [ngrok](https://ngrok.com/) to expose your local endpoint.

### Example endpoint

This code snippet is an endpoint function configured to receive `v1.delegated_checkout.finalize_checkout` requests and return a `200` responses.

#### Ruby

```ruby
require 'json'
require 'sinatra'
require 'stripe'

set :port, 4242

# Replace with your endpoint's secret from your webhook settings
endpoint_secret = 'whsec_...'

# Using Sinatra
post '/hooks' do
  payload = request.body.read
  sig_header = request.env['HTTP_STRIPE_SIGNATURE']

  # Verify the webhook signature
  begin
    Stripe::Webhook::Signature.verify_header(
      payload, sig_header, endpoint_secret
    )
  rescue Stripe::SignatureVerificationError => e
    status 400
    return
  end

  # Handle the payload
  payload = JSON.parse(payload)
  case payload['type']
  when 'v1.delegated_checkout.finalize_checkout'
    # Check inventory and accept payment
    data = { manual_approval_details: { type: 'approved' } }
  end

  status 200
  body data.to_json
end
```

## Optional: Handle the agreement with agents

> This API is in private preview. Examples below are subject to change.

When a connected account onboards to an agent, Stripe creates an Agreement object between the seller and the agent. Stripe emits webhook events to the platform and the agent whenever the Agreement object’s status changes:

- `v2.orchestrated_commerce.agreement.created`: An Agreement was created between the seller and the agent.
- `v2.orchestrated_commerce.agreement.partially_confirmed`: The seller has confirmed the Agreement.
- `v2.orchestrated_commerce.agreement.confirmed`: The agent has confirmed the Agreement.
- `v2.orchestrated_commerce.agreement.terminated`: Either the seller or agent terminated the Agreement.

Listen for these events on your webhook endpoint to keep your platform’s state in sync (for example, updating UI, enabling/disabling agent access, or notifying sellers).

### Fetch an Agreement

Retrieve an Agreement object using the Agreements API:

```curl
curl https://api.stripe.com/v2/orchestrated_commerce/agreements/{{AGREEMENT_ID}} \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Stripe-Version: 2025-12-19-17.internal" \
  -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}"
```

## Optional: Send incremental inventory updates

In addition to uploading your product catalogue, you can send individual product inventory updates through the [Imports API](https://docs.stripe.com/api/v2/commerce/product-catalog-imports.md). Use the same upload process as catalogue uploads, but set `feed_type` to `inventory`. Inventory feeds support only `upsert` mode.

```curl
curl -X POST https://api.stripe.com/v2/commerce/product_catalog/imports \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-04-22.preview" \
  -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \
  --json '{
    "feed_type": "inventory",
    "mode": "upsert",
    "metadata": {
        "file_name": "march_11_2026_inventory_upload.csv"
    }
  }'
```

## Optional: Send incremental price updates

Upload your product catalogue data, then send individual price updates through the [Imports API](https://docs.stripe.com/api/v2/commerce/product-catalog-imports.md). Use the same upload process as catalogue uploads and set `feed_type` to `pricing`. Price feeds support only `upsert` mode.

```curl
curl -X POST https://api.stripe.com/v2/commerce/product_catalog/imports \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-04-22.preview" \
  -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \
  --json '{
    "feed_type": "pricing",
    "mode": "upsert",
    "metadata": {
        "file_name": "march_11_2026_pricing_upload.csv"
    }
  }'
```

## Optional: Handle refunds and disputes

If you already use the [Payment Intents API](https://docs.stripe.com/api/payment_intents.md) or [Checkout Sessions API](https://docs.stripe.com/api/checkout/sessions.md), your existing refund and dispute flows work without changes for in-context agentic selling. Stripe creates `PaymentIntents` for agentic checkout flows, so as long as you associate the `PaymentIntent` ID with your order, your integration continues to work.

If a customer cancels the order from your website or through customer service after checkout succeeds, you can initiate a refund. Manage refunds and disputes in the Dashboard from the [Transactions page](https://dashboard.stripe.com/payments), or use the [Refunds API](https://docs.stripe.com/api/refunds.md) to handle them programmatically.