ACP Request Schemas

Use these request objects when submitting orders through the ACP API.

A complete request

Everything below is one nested object. This is a valid submission with only the required fields plus routing:

{
  "orderId": "src_88213",
  "orderNumber": "#1042",
  "source": "agent",
  "customer": {
    "email": "avery@example.com",
    "firstName": "Avery",
    "lastName": "Chen"
  },
  "shippingAddress": {
    "name": "Avery Chen",
    "address1": "500 Market St",
    "address2": "Suite 300",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94105",
    "countryCode": "US"
  },
  "lineItems": [
    {
      "sku": "SHOE-RED-10",
      "title": "Trail Runner — Red, 10",
      "quantity": 1,
      "price": 128.00
    }
  ],
  "routing": {
    "sendToFulfillment": true,
    "sendToErp": true,
    "createInStateset": true,
    "fulfillmentProvider": "auto"
  }
}

curl -X POST https://api.stateset.com/v1/acp/orders \
  -H "Authorization: Bearer $STATESET_API_KEY" \
  -H 'content-type: application/json' \
  -H "Idempotency-Key: src_88213" \
  -d @order.json

Use your own orderId as the Idempotency-Key. A retried submission then replays the original result instead of creating a duplicate order — which matters when an agent is doing the retrying.

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

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

All three routing booleans default to true. Omitting routing entirely sends the order to fulfillment, to the ERP, and into StateSet. Set the ones you don’t want to false explicitly — a test submission with no routing block is a real order downstream.

Set fulfillmentProvider to "auto" unless you have a reason to pin a provider; auto selects based on the shipping address and current inventory position.

Field notes

Money and weight are numbers, not strings. price is the unit price, not the line total — the line total is price × quantity.
quantity must be greater than zero, and lineItems must contain at least one item.
state and countryCode are codes, not names — "CA" and "US", not "California" and "United States".
billingAddress defaults to shippingAddress. Only send it when they genuinely differ.
netsuiteId and netsuiteItemId are optional pass-throughs. Supply them when you already hold the NetSuite internal IDs and want to skip a lookup on the ERP side.
createdAt defaults to now. Set it when backfilling so ordering and SLAs stay accurate.

ACP Endpoints — where to send this
ACP — what the protocol is for
Deploy an ACP handler

ACP Routing Options Agentic Commerce Protocol Handler

Get started

Platform

StateSet One

StateSet Response

StateSet ResponseCX

Temporal Engine

StateSet iCommerce

StateSet EDI

StateSet Mail

StateSet Voice

StateSet NSR

AI Agents

StateSet Sandbox

StateSet ACP

StateSet UCP

StateSet ICP

StateSet Sequencer

StateSet Set L2

StateSet Cloud

Tools

ACP Request Schemas

ACP Request Schemas

A complete request

AcpOrderRequest

Customer

Address

LineItem

RoutingConfig

Field notes

​ACP Request Schemas

​A complete request

​AcpOrderRequest

​Customer

​Address

​LineItem

​RoutingConfig

​Field notes

​Related

ACP Request Schemas

A complete request

AcpOrderRequest

Customer

Address

LineItem

RoutingConfig

Field notes

Related