Agent Commerce Protocol (ACP) Guide

The Agent Commerce Protocol (ACP) enables AI agents to place orders directly into your commerce infrastructure. With a single API call, an AI agent can create an order that automatically flows through to fulfillment and ERP systems.

Overview

┌─────────────────────────────────────────────────────────────────────┐
│                         AI AGENT LAYER                              │
│   (ChatGPT, Claude, Custom Agents, Voice Assistants, Chatbots)     │
└─────────────────────────────────────────────────────────────────────┘
                                  │
                                  │ POST /acp/orders
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    STATESET SYNC SERVER                             │
│                                                                     │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐            │
│  │  Validate   │───▶│   Route     │───▶│   Track     │            │
│  │   Order     │    │   Order     │    │    Job      │            │
│  └─────────────┘    └─────────────┘    └─────────────┘            │
└─────────────────────────────────────────────────────────────────────┘
                                  │
                ┌─────────────────┼─────────────────┐
                ▼                 ▼                 ▼
┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐
│     STATESET      │ │    FULFILLMENT    │ │       ERP         │
│                   │ │                   │ │                   │
│  • Order Record   │ │  • DCL Warehouse  │ │  • NetSuite       │
│  • Line Items     │ │  • Cart.com       │ │  • Sales Order    │
│  • Status Track   │ │  • Ship to Cust.  │ │  • Revenue Rec.   │
└───────────────────┘ └───────────────────┘ └───────────────────┘

Why ACP?

Traditional e-commerce requires customers to navigate websites, add items to carts, and go through checkout flows. Agent Commerce allows AI assistants to handle the entire purchase flow conversationally:

“I’d like to order 2 blue widgets shipped to my office”
The AI collects details, confirms the order, and places it via ACP
The order is fulfilled and tracked automatically

This enables:

Conversational Commerce - Order via ChatGPT, Claude, Alexa, etc.
Automated Purchasing - Agents that reorder supplies automatically
B2B Order Entry - Sales reps using AI to place orders
Multi-channel Unification - Single API for all agent-based ordering

Quick Start

1. Basic Order Submission

curl -X POST https://your-server.com/v1/tenants/{tenant_id}/acp/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "agent-order-001",
    "orderNumber": "ORD-1001",
    "customer": {
      "email": "customer@example.com",
      "firstName": "John",
      "lastName": "Doe"
    },
    "shippingAddress": {
      "name": "John Doe",
      "address1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94102",
      "countryCode": "US"
    },
    "lineItems": [
      {
        "sku": "WIDGET-001",
        "title": "Blue Widget",
        "quantity": 2,
        "price": 29.99
      }
    ]
  }'

2. Response

{
  "data": {
    "accepted": true,
    "statesetOrderId": "550e8400-e29b-41d4-a716-446655440000",
    "fulfillment": {
      "provider": "dcl",
      "success": true,
      "externalId": "ORD-1001"
    },
    "erp": {
      "provider": "netsuite",
      "success": true,
      "netsuiteId": "12345",
      "tranId": "SO-12345"
    },
    "warnings": [],
    "requestId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  },
  "meta": {
    "requestId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

API Reference

Endpoints

Method	Endpoint	Description
POST	`/v1/tenants/{tenant_id}/acp/orders`	Process order synchronously
POST	`/v1/tenants/{tenant_id}/acp/orders/async`	Process order in background
POST	`/v1/tenants/{tenant_id}/acp/orders/batch`	Process multiple orders

Authentication

Include your API key in the Authorization header:

Authorization: Bearer your-api-key-here

Or use the X-API-Key header:

X-API-Key: your-api-key-here

Request Schema

AcpOrderRequest

Field	Type	Required	Description
`orderId`	string	Yes	Unique order identifier from source system
`orderNumber`	string	Yes	Display order number
`source`	string	No	Source system (default: “agent”)
`customer`	Customer	Yes	Customer information
`shippingAddress`	Address	Yes	Shipping destination
`billingAddress`	Address	No	Billing address (defaults to shipping)
`lineItems`	LineItem[]	Yes	Order line items (min 1)
`createdAt`	datetime	No	Order timestamp (default: now)
`tags`	string[]	No	Tags for categorization
`shippingMethod`	string	No	Requested shipping method
`notes`	string	No	Order notes/instructions
`routing`	RoutingConfig	No	Control where order is sent
`metadata`	object	No	Additional custom data

Customer

Field	Type	Required	Description
`id`	string	No	Customer ID in source system
`email`	string	Yes	Customer email
`firstName`	string	Yes	First name
`lastName`	string	Yes	Last name
`phone`	string	No	Phone number
`netsuiteId`	string	No	NetSuite customer internal ID

Address

Field	Type	Required	Description
`name`	string	Yes	Full name
`company`	string	No	Company name
`address1`	string	Yes	Street address line 1
`address2`	string	No	Street address line 2
`city`	string	Yes	City
`state`	string	Yes	State/province code
`postalCode`	string	Yes	ZIP/postal code
`countryCode`	string	Yes	2-letter country code (e.g., “US”)
`phone`	string	No	Phone number

LineItem

Field	Type	Required	Description
`sku`	string	Yes	Product SKU
`title`	string	Yes	Product title
`quantity`	number	Yes	Quantity (must be > 0)
`price`	number	Yes	Unit price
`variantId`	string	No	Variant ID from source system
`netsuiteItemId`	string	No	NetSuite item internal ID
`weight`	number	No	Weight in pounds

RoutingConfig

Control where the order is sent:

Field	Type	Default	Description
`sendToFulfillment`	boolean	true	Send to DCL/Cart.com
`sendToErp`	boolean	true	Send to NetSuite
`createInStateset`	boolean	true	Create in StateSet
`fulfillmentProvider`	string	”auto"	"dcl”, “cart”, or “auto”
`dclLocation`	string	null	Override DCL warehouse location

Routing Options

Full Integration (Default)

Order flows to all configured systems:

{
  "routing": {
    "sendToFulfillment": true,
    "sendToErp": true,
    "createInStateset": true
  }
}

Fulfillment Only

Skip ERP, just fulfill the order:

{
  "routing": {
    "sendToFulfillment": true,
    "sendToErp": false,
    "createInStateset": true
  }
}

Record Only

Just create the record, don’t fulfill yet:

{
  "routing": {
    "sendToFulfillment": false,
    "sendToErp": false,
    "createInStateset": true
  }
}

Specific Fulfillment Provider

Force a specific fulfillment provider:

{
  "routing": {
    "fulfillmentProvider": "dcl",
    "dclLocation": "LA"
  }
}

Async Processing

For high-volume or time-sensitive responses, use async processing:

Submit Order

curl -X POST https://your-server.com/v1/tenants/{tenant_id}/acp/orders/async \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... order data ... }'

Response

{
  "data": {
    "jobId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "queued",
    "message": "Order ORD-1001 accepted for processing"
  }
}

Check Status

curl https://your-server.com/v1/tenants/{tenant_id}/jobs/{jobId} \
  -H "Authorization: Bearer YOUR_API_KEY"

Job Status Response

{
  "data": {
    "jobId": "550e8400-e29b-41d4-a716-446655440000",
    "jobType": "acp_order_process",
    "state": "succeeded",
    "createdAt": "2024-01-15T10:30:00Z",
    "startedAt": "2024-01-15T10:30:01Z",
    "finishedAt": "2024-01-15T10:30:03Z",
    "result": {
      "orderId": "agent-order-001",
      "orderNumber": "ORD-1001",
      "statesetOrderId": "550e8400-e29b-41d4-a716-446655440000",
      "fulfillment": { "provider": "dcl", "success": true },
      "erp": { "provider": "netsuite", "success": true, "netsuiteId": "12345" }
    }
  }
}

Batch Processing

Process up to 100 orders in a single request:

curl -X POST https://your-server.com/v1/tenants/{tenant_id}/acp/orders/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orders": [
      { "orderId": "order-001", "orderNumber": "ORD-001", ... },
      { "orderId": "order-002", "orderNumber": "ORD-002", ... },
      { "orderId": "order-003", "orderNumber": "ORD-003", ... }
    ]
  }'

Response

{
  "data": {
    "jobId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "queued",
    "message": "Batch of 3 orders accepted for processing"
  }
}

Batch Result

{
  "total": 3,
  "processed": 3,
  "succeeded": 2,
  "failed": 1,
  "results": [
    { "orderId": "order-001", "success": true, "statesetOrderId": "..." },
    { "orderId": "order-002", "success": true, "statesetOrderId": "..." },
    { "orderId": "order-003", "success": false, "fulfillment": { "error": "..." } }
  ]
}

Integration Examples

ChatGPT Function Calling

Define this function for ChatGPT to place orders:

{
  "name": "place_order",
  "description": "Place an order for products",
  "parameters": {
    "type": "object",
    "properties": {
      "customerEmail": { "type": "string" },
      "customerFirstName": { "type": "string" },
      "customerLastName": { "type": "string" },
      "shippingAddress": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "address1": { "type": "string" },
          "city": { "type": "string" },
          "state": { "type": "string" },
          "postalCode": { "type": "string" },
          "countryCode": { "type": "string" }
        }
      },
      "items": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "sku": { "type": "string" },
            "title": { "type": "string" },
            "quantity": { "type": "number" },
            "price": { "type": "number" }
          }
        }
      }
    },
    "required": ["customerEmail", "customerFirstName", "customerLastName", "shippingAddress", "items"]
  }
}

Python Integration

import requests
import uuid

def place_acp_order(tenant_id: str, api_key: str, order_data: dict) -> dict:
    """Place an order via the ACP endpoint."""

    url = f"https://your-server.com/v1/tenants/{tenant_id}/acp/orders"

    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }

    # Ensure order has an ID
    if "orderId" not in order_data:
        order_data["orderId"] = f"agent-{uuid.uuid4()}"

    response = requests.post(url, json=order_data, headers=headers)
    response.raise_for_status()

    return response.json()


# Example usage
order = {
    "orderNumber": "ORD-1001",
    "customer": {
        "email": "customer@example.com",
        "firstName": "John",
        "lastName": "Doe"
    },
    "shippingAddress": {
        "name": "John Doe",
        "address1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "postalCode": "94102",
        "countryCode": "US"
    },
    "lineItems": [
        {"sku": "WIDGET-001", "title": "Blue Widget", "quantity": 2, "price": 29.99}
    ]
}

result = place_acp_order("my-tenant", "my-api-key", order)
print(f"Order accepted: {result['data']['accepted']}")
print(f"NetSuite ID: {result['data']['erp']['netsuiteId']}")

Node.js Integration

const axios = require('axios');
const { v4: uuidv4 } = require('uuid');

async function placeAcpOrder(tenantId, apiKey, orderData) {
  const url = `https://your-server.com/v1/tenants/${tenantId}/acp/orders`;

  // Ensure order has an ID
  if (!orderData.orderId) {
    orderData.orderId = `agent-${uuidv4()}`;
  }

  const response = await axios.post(url, orderData, {
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    }
  });

  return response.data;
}

// Example usage
const order = {
  orderNumber: 'ORD-1001',
  customer: {
    email: 'customer@example.com',
    firstName: 'John',
    lastName: 'Doe'
  },
  shippingAddress: {
    name: 'John Doe',
    address1: '123 Main St',
    city: 'San Francisco',
    state: 'CA',
    postalCode: '94102',
    countryCode: 'US'
  },
  lineItems: [
    { sku: 'WIDGET-001', title: 'Blue Widget', quantity: 2, price: 29.99 }
  ]
};

placeAcpOrder('my-tenant', 'my-api-key', order)
  .then(result => {
    console.log('Order accepted:', result.data.accepted);
    console.log('NetSuite ID:', result.data.erp.netsuiteId);
  });

Error Handling

Validation Errors (422)

{
  "error": {
    "code": "validation_error",
    "message": "lineItems[0].sku is required; shippingAddress missing required fields: postalCode",
    "requestId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  }
}

Integration Not Configured (424)

{
  "error": {
    "code": "integration_not_configured",
    "message": "DCL integration not configured for this tenant",
    "requestId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  }
}

Partial Success (207)

When some integrations succeed but others fail:

{
  "data": {
    "accepted": false,
    "statesetOrderId": "550e8400-e29b-41d4-a716-446655440000",
    "fulfillment": {
      "provider": "dcl",
      "success": true
    },
    "erp": {
      "provider": "netsuite",
      "success": false,
      "error": "NetSuite API timeout"
    },
    "warnings": ["ERP submission failed but order was fulfilled"]
  }
}

Configuration

Tenant Configuration

Ensure your tenant has the required integrations configured in app_config.json:

{
  "tenants": [
    {
      "id": "my-tenant",
      "displayName": "My Store",
      "auth": {
        "apiKeys": ["your-api-key"]
      },
      "stateset": {
        "graphqlUrl": "https://your-hasura.com/v1/graphql",
        "adminSecret": "your-admin-secret"
      },
      "dcl": {
        "apiUrl": "https://api.dclcorp.com",
        "username": "dcl-user",
        "password": "dcl-pass",
        "accountNumber": "12345",
        "defaultLocation": "LA"
      },
      "netsuite": {
        "domain": "123456.suitetalk.api.netsuite.com",
        "consumerKey": "...",
        "consumerSecret": "...",
        "tokenKey": "...",
        "tokenSecret": "...",
        "defaultCustomerId": "14",
        "defaultSubsidiaryId": "1"
      }
    }
  ]
}

Environment Variables

Sensitive values can be stored as environment variables:

MY_TENANT_DCL_PASSWORD=dcl-password
MY_TENANT_NETSUITE_CONSUMER_SECRET=netsuite-secret
MY_TENANT_NETSUITE_TOKEN_SECRET=token-secret

Best Practices

1. Use Idempotent Order IDs

Always provide a unique, deterministic orderId to prevent duplicate orders:

{
  "orderId": "chatgpt-session-abc123-order-1"
}

2. Validate Before Submitting

Have your AI agent confirm order details with the customer before calling ACP.

3. Handle Partial Failures

Check both fulfillment.success and erp.success in responses. An order might be fulfilled even if ERP entry fails.

4. Use Async for High Volume

For bulk imports or high-traffic scenarios, use /acp/orders/async or /acp/orders/batch.

5. Include Customer NetSuite ID

If you know the customer’s NetSuite ID, include it to ensure proper customer linking:

{
  "customer": {
    "email": "customer@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "netsuiteId": "12345"
  }
}

6. Map SKUs to NetSuite Items

For fastest NetSuite processing, include NetSuite item IDs:

{
  "lineItems": [
    {
      "sku": "WIDGET-001",
      "title": "Blue Widget",
      "quantity": 2,
      "price": 29.99,
      "netsuiteItemId": "5678"
    }
  ]
}

Glossary

Term	Description
ACP	Agent Commerce Protocol - API for AI agents to place orders
DCL	Distributed Commerce Logistics - 3PL fulfillment provider
ERP	Enterprise Resource Planning - Business management system (NetSuite)
StateSet	Order management and tracking system
Tenant	A configured merchant/store in the multi-tenant system

Support

For issues or questions:

GitHub Issues: https://github.com/stateset/stateset-sync-server/issues
Documentation: https://docs.stateset.com

​Agent Commerce Protocol (ACP) Guide

​Overview

​Why ACP?

​Quick Start

​1. Basic Order Submission

​2. Response

​API Reference

​Endpoints

​Authentication

​Request Schema

​AcpOrderRequest

​Customer

​Address

​LineItem

​RoutingConfig

​Routing Options

​Full Integration (Default)

​Fulfillment Only

​Record Only

​Specific Fulfillment Provider

​Async Processing

​Submit Order

​Response

​Check Status

​Job Status Response

​Batch Processing

​Response

​Batch Result

​Integration Examples

​ChatGPT Function Calling

​Python Integration

​Node.js Integration

​Error Handling

​Validation Errors (422)

​Integration Not Configured (424)

​Partial Success (207)

​Configuration

​Tenant Configuration

​Environment Variables

​Best Practices

​1. Use Idempotent Order IDs

​2. Validate Before Submitting

​3. Handle Partial Failures

​4. Use Async for High Volume

​5. Include Customer NetSuite ID

​6. Map SKUs to NetSuite Items

​Glossary

​Support

Agent Commerce Protocol (ACP) Guide

Overview

Why ACP?

Quick Start

1. Basic Order Submission

2. Response

API Reference

Endpoints

Authentication

Request Schema

AcpOrderRequest

Customer

Address

LineItem

RoutingConfig

Routing Options

Full Integration (Default)

Fulfillment Only

Record Only

Specific Fulfillment Provider

Async Processing

Submit Order

Response

Check Status

Job Status Response

Batch Processing

Response

Batch Result

Integration Examples

ChatGPT Function Calling

Python Integration

Node.js Integration

Error Handling

Validation Errors (422)

Integration Not Configured (424)

Partial Success (207)

Configuration

Tenant Configuration

Environment Variables

Best Practices

1. Use Idempotent Order IDs

2. Validate Before Submitting

3. Handle Partial Failures

4. Use Async for High Volume

5. Include Customer NetSuite ID

6. Map SKUs to NetSuite Items

Glossary

Support