> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ACP Request Schemas

> Request objects for ACP order submission — every field, with a complete worked example.

# ACP Request Schemas

Use these request objects when submitting orders through the
[ACP API](/stateset-acp/stateset-acp-endpoints).

## A complete request

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

```json theme={null}
{
  "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"
  }
}
```

```bash theme={null}
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
```

<Tip>
  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.
</Tip>

## 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 |

<Warning>
  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.
</Warning>

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.

## Related

* [ACP Endpoints](/stateset-acp/stateset-acp-endpoints) — where to send this
* [ACP](/stateset-acp/stateset-acp) — what the protocol is for
* [Deploy an ACP handler](/stateset-deploy-acp-handler)