---
title: "Checkout — AVCodex Docs"
description: "Checkout — AVCodex documentation for AV integrators, programmers, and ops teams."
lang: en
json-ld:
---

[](/)

Solutions

[Pricing](/pricing)[The Signal](/blog)[Resources](/resources)

Learn

[Free AI Assessment](/scorecard)[Get Started →](/pricing)

[Documentation Home](/docs)

Guides 

Custom Actions 

Pro Actions 

API 

Builder API 

Agentic Commerce (ACP) 

-   [Overview](/docs/acp/overview)
-   [Authentication](/docs/acp/authentication)
-   [Agent Discovery](/docs/acp/agent-discovery)
-   [Checkout](/docs/acp/checkout)
-   [Webhooks](/docs/acp/webhooks)

Integrations 

[Docs](/docs)/ Agentic Commerce (ACP) / Agentic Commerce (ACP) 

# Checkout

Last updated · MAR 2026 · [Read as Markdown](/docs/acp/checkout.md)

Checkout endpoints let agents create purchase sessions, add buyer information, and complete transactions. All checkout endpoints require [authentication](/docs/acp/authentication).

## [Create checkout session# ](#create-checkout-session)

code 

```
POST /acp/{appId}/checkout_sessions
```

Creates a new checkout session with one or more products.

### [Headers# ](#headers)

Header

Required

Description

`Authorization`

Yes

`Bearer acp_xxxxx`.

`Content-Type`

Yes

`application/json`.

`Idempotency-Key`

No

Unique string to prevent duplicate sessions.

### [Request body# ](#request-body)

json 

```
{
  "line_items": [
    { "product_id": "550e8400-e29b-41d4-a716-446655440000", "quantity": 2 },
    { "product_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "quantity": 1 }
  ],
  "buyer": {
    "name": "Jane Smith",
    "email": "jane@integrator.com",
    "phone": "+1-555-0100"
  },
  "shipping_address": {
    "line1": "123 Main St",
    "line2": "Suite 4B",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "country": "US"
  }
}
```

### [Parameters# ](#parameters)

Field

Type

Required

Description

`line_items`

array

Yes

At least one item.

`line_items[].product_id`

string (UUID)

Yes

Product ID from the catalog.

`line_items[].quantity`

integer

No

Defaults to 1. Must be >= 1.

`buyer`

object

No

Purchaser information.

`buyer.name`

string

No

Buyer's name.

`buyer.email`

string

No

Buyer's email (must be a valid format).

`buyer.phone`

string

No

Buyer's phone number.

`shipping_address`

object

No

Shipping address.

`shipping_address.line1`

string

No

Street address.

`shipping_address.line2`

string

No

Suite, floor, etc.

`shipping_address.city`

string

No

City.

`shipping_address.state`

string

No

State or province.

`shipping_address.postal_code`

string

No

Postal code.

`shipping_address.country`

string

No

Country code.

### [Example request# ](#example-request)

bash 

```
curl -X POST https://app.avcodex.com/acp/{appId}/checkout_sessions \
  -H "Authorization: Bearer acp_xxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-abc-123" \
  -d '{
    "line_items": [
      { "product_id": "550e8400-e29b-41d4-a716-446655440000", "quantity": 1 }
    ],
    "buyer": {
      "name": "Jane Smith",
      "email": "jane@integrator.com"
    }
  }'
```

### [Response (201 Created)# ](#response-201-created)

json 

```
{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "ready_for_payment",
    "line_items": [
      {
        "productId": "550e8400-e29b-41d4-a716-446655440000",
        "productName": "Room Audit Report",
        "sku": "AUDIT-001",
        "quantity": 1,
        "unitPriceCents": 25000,
        "totalCents": 25000
      }
    ],
    "subtotal": { "amount": 25000, "currency": "usd" },
    "total": { "amount": 25000, "currency": "usd" },
    "buyer": {
      "name": "Jane Smith",
      "email": "jane@integrator.com",
      "phone": null
    },
    "shipping_address": null,
    "payment": null,
    "expires_at": "2025-01-15T13:00:00.000Z",
    "created_at": "2025-01-15T12:00:00.000Z",
    "updated_at": "2025-01-15T12:00:00.000Z"
  }
}
```

### [Idempotency# ](#idempotency)

Pass an `Idempotency-Key` header to safely retry requests. If a session with the same idempotency key already exists for this agent, the existing session is returned instead of creating a duplicate.

bash 

```
curl -X POST https://app.avcodex.com/acp/{appId}/checkout_sessions \
  -H "Authorization: Bearer acp_xxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-123" \
  -d '{ "line_items": [{ "product_id": "...", "quantity": 1 }] }'
```

* * *

## [Get checkout session# ](#get-checkout-session)

code 

```
GET /acp/{appId}/checkout_sessions/{id}
```

Retrieve the current status and details of a checkout session.

### [Example request# ](#example-request)

bash 

```
curl https://app.avcodex.com/acp/{appId}/checkout_sessions/{sessionId} \
  -H "Authorization: Bearer acp_xxxxx"
```

### [Response (200 OK)# ](#response-200-ok)

Returns the same shape as the create response:

json 

```
{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "ready_for_payment",
    "line_items": [...],
    "subtotal": { "amount": 25000, "currency": "usd" },
    "total": { "amount": 25000, "currency": "usd" },
    "buyer": { "name": "Jane Smith", "email": "jane@integrator.com", "phone": null },
    "shipping_address": null,
    "payment": null,
    "expires_at": "2025-01-15T13:00:00.000Z",
    "created_at": "2025-01-15T12:00:00.000Z",
    "updated_at": "2025-01-15T12:00:00.000Z"
  }
}
```

* * *

## [Update checkout session# ](#update-checkout-session)

code 

```
POST /acp/{appId}/checkout_sessions/{id}
```

Update line items, buyer information, or shipping address on an existing session. Only works when the session is in a pre-payment state (`not_ready_for_payment` or `ready_for_payment`).

### [Request body# ](#request-body)

All fields are optional. Only include the fields you want to update.

json 

```
{
  "line_items": [
    { "product_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "quantity": 3 }
  ],
  "buyer": {
    "email": "updated@integrator.com"
  }
}
```

### [Example request# ](#example-request)

bash 

```
curl -X POST https://app.avcodex.com/acp/{appId}/checkout_sessions/{sessionId} \
  -H "Authorization: Bearer acp_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "buyer": { "name": "Jane Smith", "email": "jane.updated@integrator.com" }
  }'
```

### [Response (200 OK)# ](#response-200-ok)

Returns the updated session in the same shape as the create response.

* * *

## [Complete checkout# ](#complete-checkout)

code 

```
POST /acp/{appId}/checkout_sessions/{id}/complete
```

Completes the checkout, triggering order creation, fulfillment (for automatic products), and webhook delivery. The session must be in `ready_for_payment` status and must not be expired.

### [Example request# ](#example-request)

bash 

```
curl -X POST https://app.avcodex.com/acp/{appId}/checkout_sessions/{sessionId}/complete \
  -H "Authorization: Bearer acp_xxxxx"
```

### [Response (200 OK)# ](#response-200-ok)

json 

```
{
  "data": {
    "checkout_session": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "completed",
      "line_items": [...],
      "subtotal": { "amount": 25000, "currency": "usd" },
      "total": { "amount": 25000, "currency": "usd" },
      "buyer": { "name": "Jane Smith", "email": "jane@integrator.com", "phone": null },
      "shipping_address": null,
      "payment": null,
      "expires_at": "2025-01-15T13:00:00.000Z",
      "created_at": "2025-01-15T12:00:00.000Z",
      "updated_at": "2025-01-15T12:05:00.000Z"
    },
    "order": {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "status": "fulfilled",
      "fulfillment_result": [
        { "toolName": "generate_audit_report", "success": true, "output": "Audit complete" }
      ],
      "created_at": "2025-01-15T12:05:00.000Z"
    }
  }
}
```

### [Order status values# ](#order-status-values)

Status

Description

`created`

Order created, awaiting processing.

`manual_review`

Requires human review before fulfillment.

`confirmed`

Order confirmed, awaiting fulfillment.

`fulfilled`

Automatic fulfillment completed successfully.

`shipped`

Physical order shipped.

`canceled`

Order canceled.

> **Note:** Products with `fulfillment_type: "automatic"` are fulfilled immediately on checkout completion **only if a bound tool is configured** on the product. The order status will be `fulfilled` with results in the `fulfillment_result` field. If no bound tool is configured **or if all bound tool executions fail**, the order receives status `confirmed` instead. Manual products will also have status `confirmed` and require human action.

* * *

## [Cancel checkout# ](#cancel-checkout)

code 

```
POST /acp/{appId}/checkout_sessions/{id}/cancel
```

Cancels an active checkout session. Only works for sessions in pre-payment states (`not_ready_for_payment` or `ready_for_payment`). Sessions that are already completed or in progress cannot be canceled.

### [Example request# ](#example-request)

bash 

```
curl -X POST https://app.avcodex.com/acp/{appId}/checkout_sessions/{sessionId}/cancel \
  -H "Authorization: Bearer acp_xxxxx"
```

### [Response (200 OK)# ](#response-200-ok)

json 

```
{
  "data": { "canceled": true }
}
```

* * *

## [Checkout session status values# ](#checkout-session-status-values)

Status

Description

`not_ready_for_payment`

Session created without line items (internal only. The external API requires at least one line item, so sessions created via the API will never have this status).

`ready_for_payment`

Has line items, ready to complete.

`in_progress`

Payment is being processed.

`completed`

Checkout finished, order created.

`canceled`

Session was canceled.

## [Checkout response fields# ](#checkout-response-fields)

Field

Type

Description

`id`

string (UUID)

Checkout session identifier.

`status`

string

Current session status (see table above).

`line_items`

array

Products in the checkout.

`subtotal`

object

`{ amount, currency }`. Sum of line item totals.

`total`

object

`{ amount, currency }`. Final amount to charge.

`buyer`

object or null

`{ name, email, phone }`. Requires at least `name` or `email` to be present. Returns `null` if neither is set, even if `phone` was provided.

`shipping_address`

object or null

Shipping address if provided.

`payment`

object or null

`{ payment_intent_id }` when payment exists.

`expires_at`

string (ISO 8601)

Session expiration time (default: 1 hour after creation).

`created_at`

string (ISO 8601)

When the session was created.

`updated_at`

string (ISO 8601)

Last modification time.

## [Error responses# ](#error-responses)

### [400 Bad Request# ](#400-bad-request)

Invalid request body or state transition:

json 

```
{ "error": "Cannot complete checkout in status: canceled" }
```

### [404 Not Found# ](#404-not-found)

Session does not exist or belongs to a different agent:

json 

```
{ "error": "Checkout session not found" }
```

### [405 Method Not Allowed# ](#405-method-not-allowed)

Attempting to cancel a session that cannot be canceled:

json 

```
{ "error": "Cannot cancel checkout in status: completed" }
```

### [410 Gone# ](#410-gone)

Session has expired:

json 

```
{ "error": "Checkout session has expired" }
```

\*AVCodex · Your AV expertise. Amplified by AI.\*

Was this helpful? 

[Edit this page →](#)

[

Previous

Agent Discovery

](/docs/acp/agent-discovery)[

Next

Webhooks

](/docs/acp/webhooks)

On this page

-   [Create checkout session](#create-checkout-session)
-   [Headers](#headers)
-   [Request body](#request-body)
-   [Parameters](#parameters)
-   [Example request](#example-request)
-   [Response (201 Created)](#response-201-created)
-   [Idempotency](#idempotency)
-   [Get checkout session](#get-checkout-session)
-   [Example request](#example-request)
-   [Response (200 OK)](#response-200-ok)
-   [Update checkout session](#update-checkout-session)
-   [Request body](#request-body)
-   [Example request](#example-request)
-   [Response (200 OK)](#response-200-ok)
-   [Complete checkout](#complete-checkout)
-   [Example request](#example-request)
-   [Response (200 OK)](#response-200-ok)
-   [Order status values](#order-status-values)
-   [Cancel checkout](#cancel-checkout)
-   [Example request](#example-request)
-   [Response (200 OK)](#response-200-ok)
-   [Checkout session status values](#checkout-session-status-values)
-   [Checkout response fields](#checkout-response-fields)
-   [Error responses](#error-responses)
-   [400 Bad Request](#400-bad-request)
-   [404 Not Found](#404-not-found)
-   [405 Method Not Allowed](#405-method-not-allowed)
-   [410 Gone](#410-gone)

[](/)

The AI platform built exclusively for professional AV. Build, deploy, and sell AI tools that understand your industry.

### Platform

-   What You Can Build
-   Templates
-   [Pricing](/pricing)

### Services

-   [Done-For-You](/pricing)
-   [Academy](/academy)
-   [Contact](/contact)

### Company

-   About
-   [The Signal](/blog)
-   [Docs](/docs)
-   [LinkedIn](#)

© 2026 AVCodex. A Future Ready Holdings Inc. product. SOC 2 Type II Certified · HIPAA Compliant