Intake Agent

Convert unstructured customer input into a Cart, Quote Request, or Shopping List through the HTTP API.

The Intake Agent accepts a natural-language prompt, file uploads, or both. It extracts line items and resolves the Customer, Business Unit, and Store from the input. It then creates a Cart, Quote Request, or Shopping List in commercetools REST representation. The caller chooses which entity to create, then reviews and acts on the result using the standard commercetools APIs.

AI use: This feature uses AI to analyze data you provide.

Your data: We do not use your data to train models.

Opt-in: To enable this feature, submit a support request and include the Project key.

When to use the Intake Agent

Use the Intake Agent to:

Convert a list of SKUs, ISBNs, or product names from an email into a Cart without entering each line manually.
Convert a customer request from a CSV, PDF, or free-text email into a Cart or Quote Request with catalog matches, pricing, and customer context.
Convert a product list from an email, spreadsheet, or order form into a Shopping List that the Customer can turn into a Cart later.
Convert inbound emails or support tickets into commerce objects without implementing document parsing, product matching, and customer resolution.

Required information

Every request must include:

outputType: whether to create a Cart, a Quote Request, or a Shopping List. The Intake Agent never infers the entity from the input.
locale: a valid BCP-47 language tag, for example en-US.

The request must also include input that contains at least one Product reference (name, key, SKU, or Product Variant key). For application/json requests, provide a prompt. For multipart/form-data requests, provide a prompt, one or more files, or both.

The remaining information is read from the input, and what is mandatory depends on outputType:

Information	Cart	Quote Request	Shopping List
Customer email address	Required	Required	Required
Shipping country, used for pricing and tax	Required	Required	Not used
Name for the Shopping List	Not applicable	Not applicable	Required

The Intake Agent must also resolve the Business Unit and Store for the request, either from the input or from an explicit reference.

If a required value is missing or cannot be resolved, the request fails with a 400 error. The response names the missing information: RequiredField for a missing request field, and codes such as MissingCustomerEmail, MissingCountry, MissingShoppingListName, BusinessUnitUnresolved, or StoreUnresolved for information that couldn't be found in the input.

Shopping List name

When outputType is ShoppingList, the input must state the name to give the list, for example Create a shopping list called "Q3 restock" for jane.doe@example.com with 12 of SKU ABC-123.

The Intake Agent never invents a name. If the input doesn't contain one, no Shopping List is created and the request fails with a 400 error with the code MissingShoppingListName.

The name is stored as a LocalizedString under the locale of the request. If the input also describes the list, that text is stored as the Shopping List description in the same way.

Supported input

Input type	Notes
Free text	A natural-language prompt, such as the body of an email, a message, or a note.
File upload	PDF, TXT, CSV, DOCX, XLSX, EML, Markdown, and HTML. Up to 3 files, 20 MB each.

Handling unmatched input

The Intake Agent creates the requested entity even when it cannot match every part of the input. Non-fatal issues are returned as warnings alongside the 201 response:

When every referenced Product is matched to your catalog, warnings is omitted.
When one or more Products cannot be matched, a ProductsNotFound warning lists the unmatched identifiers. The caller can then address them, for example by editing the entity or asking the customer for more information.
When an uploaded file cannot be parsed, a FileNotProcessed warning names the file.

If no line items can be extracted from the input at all, the request fails with a NoLineItemsExtracted error instead.

Unpublished Products in a Shopping List

A Shopping List can contain Products that are not published, which Carts and Quote Requests cannot. Product Search doesn't index unpublished Products, so for ShoppingList requests each identifier that Product Search can't match is looked up a second time against staged Product data. That lookup is an exact match against the Product key, the Product Variant sku or key, or the Product name in the locale of the request or in a language configured for the Store or the Project. Partial names and misspellings don't match.

A line item resolved this way is added to the Shopping List with published set to false.

Store availability is validated by commercetools when the Shopping List is created. If the bound Store doesn't carry some of the requested Products, those Products are omitted, the Shopping List is created with the remaining items, and the omitted SKUs are reported in the ProductsNotFound warning. If no requested Product remains, the request fails with a ShoppingListCreationFailed error.

Endpoints

The Intake Agent exposes a single, stateless endpoint. Each call starts a fresh workflow run and returns its terminal outcome: either a created entity or an error. Multi-turn conversation is not supported by this endpoint.

To call this endpoint, use an API Client with the manage_intake_agent:{projectKey} scope.

Create a Cart, Quote Request, or Shopping List

POST

https://api.{region}.commercetools.com/{projectKey}/agents/intake/v1/responses

Turns a natural-language prompt, optionally with supporting files, into a created Cart, QuoteRequest, or ShoppingList, returned in commercetools REST representation. The entity to create is set by outputType and is never inferred from the input.

A ShoppingList additionally requires a name for the list in the input. The Intake Agent never invents one. Unlike a Cart or Quote Request, a Shopping List does not require a country.

Non-fatal issues, such as requested Products that could not be matched to the catalog or a file that failed to parse, are reported as warnings alongside a successful 201 response rather than failing the request.

Accepts either an application/json body or a multipart/form-data request. An application/json body requires prompt. A multipart/form-data request requires prompt, an uploaded file, or both. See Multipart form data for the file upload format.

If the Intake Agent is not enabled for the Project, a FeatureDisabled error is returned.

For a list of possible errors returned by the Intake Agent, see Intake Agent Errors type.

OAuth 2.0 Scopes:

manage_intake_agent:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.

Request Body:AgentResponsesRequestasapplication/json, multipart/form-data

Response:

201

AgentResponsesSuccess

application/json

curl https://api.{region}.commercetools.com/{projectKey}/agents/intake/v1/responses -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "outputType" : "Cart",
  "locale" : "en-US",
  "prompt" : "Please prepare a cart for jane.doe@example.com. We need 12 of SKU ABC-123 shipped to Germany.",
  "businessUnit" : {
    "typeId" : "business-unit",
    "key" : "acme-west"
  },
  "store" : {
    "typeId" : "store",
    "key" : "west-coast"
  }
}
DATA

{
  "entityType": "Cart",
  "entity": {
    "id": "27b39077-aa57-48a5-b504-914f68fa44dc",
    "version": 1,
    "createdAt": "2026-06-23T13:06:28.569Z",
    "lastModifiedAt": "2026-06-23T13:06:28.569Z",
    "lastModifiedBy": {
      "isPlatformClient": false
    },
    "createdBy": {
      "isPlatformClient": false
    },
    "customerEmail": "jane.doe@example.com",
    "businessUnit": {
      "key": "acme-west",
      "typeId": "business-unit"
    },
    "store": {
      "typeId": "store",
      "key": "west-coast"
    },
    "lineItems": [
      {
        "id": "b925a817-d5ad-48bb-a407-29ad8e0649b5",
        "productId": "9f10dcfb-5cc9-4a18-843a-c07f7e22d01f",
        "name": {
          "en": "SAPPHIRE"
        },
        "productType": {
          "typeId": "product-type",
          "id": "2543e1d8-4915-4f72-a3c9-1df9b1b0082d",
          "version": 8
        },
        "productSlug": {
          "en": "sapphire1421832124423"
        },
        "variant": {
          "id": 1,
          "sku": "sku_SAPPHIRE_variant1_1421832124423",
          "prices": [
            {
              "value": {
                "type": "centPrecision",
                "fractionDigits": 2,
                "currencyCode": "EUR",
                "centAmount": 2800
              },
              "id": "8da659ef-9e54-447d-9c36-84912db1848f"
            }
          ],
          "images": [],
          "attributes": [],
          "assets": []
        },
        "price": {
          "value": {
            "type": "centPrecision",
            "fractionDigits": 2,
            "currencyCode": "EUR",
            "centAmount": 2800
          },
          "id": "8da659ef-9e54-447d-9c36-84912db1848f"
        },
        "quantity": 2,
        "discountedPricePerQuantity": [],
        "state": [],
        "priceMode": "Platform",
        "lineItemMode": "Standard",
        "totalPrice": {
          "type": "centPrecision",
          "fractionDigits": 2,
          "currencyCode": "EUR",
          "centAmount": 5600
        },
        "perMethodTaxRate": [],
        "taxedPricePortions": []
      }
    ],
    "cartState": "Active",
    "totalPrice": {
      "type": "centPrecision",
      "currencyCode": "EUR",
      "centAmount": 5600,
      "fractionDigits": 2
    },
    "shippingMode": "Single",
    "shipping": [],
    "customLineItems": [],
    "discountCodes": [],
    "directDiscounts": [],
    "inventoryMode": "None",
    "taxMode": "Platform",
    "priceRoundingMode": "HalfEven",
    "taxRoundingMode": "HalfEven",
    "taxCalculationMode": "LineItemLevel",
    "refusedGifts": [],
    "origin": "Customer",
    "itemShippingAddresses": [],
    "totalLineItemQuantity": 2
  },
  "threadId": "run_01j2x8qz6qfz5b3v9c2d4e6f8g"
}

curl -X POST https://api.{region}.commercetools.com/{projectKey}/agents/intake/v1/responses \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "outputType": "ShoppingList",
    "locale": "en-US",
    "prompt": "Create a shopping list called \"Q3 restock\" for jane.doe@example.com with 12 of SKU ABC-123 and 4 of SKU XYZ-789."
  }'

Multipart form data

Send an AgentResponsesPayload as a single payload part and attach files under files parts. Uploading a file under any other field name is rejected with an InvalidField error.

You can upload up to 3 files, 20 MB each. The allowed content types are:

PDF (application/pdf)
Plain text (text/plain)
CSV (text/csv)
DOCX (application/vnd.openxmlformats-officedocument.wordprocessingml.document)
XLSX (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet)
EML (message/rfc822)
Markdown (text/markdown)
HTML (text/html)

curl -X POST https://api.{region}.commercetools.com/{projectKey}/agents/intake/v1/responses \
  -H "Authorization: Bearer {token}" \
  -F 'payload={"outputType":"QuoteRequest","locale":"en-US","prompt":"Quote for the attached purchase order."};type=application/json' \
  -F "files=@purchase-order.pdf"

Error codes

Every workflow run is identified by a threadId, which is returned in the AgentResponsesErrorResponse body on any error raised once the workflow has started. Errors that fail during request parsing, before the workflow starts, don't include it.

For the full list of Intake Agent-specific error codes and their 400 and 500 responses, see Intake Agent errors.

The ProductsNotFound code appears as either a 400 error, when none of the requested Products could be matched to the catalog, or as a warning on a successful 201 response, when only some Products couldn't be matched or are unavailable in the bound Store.

The codes MissingShoppingListName and ShoppingListCreationFailed only occur when outputType is ShoppingList, and MissingCountry and QuoteRequestCreationFailed never do.

Next actions

The created entity is a standard commercetools Cart, Quote Request, or Shopping List, so you can act on it with the regular APIs. For example, you can:

Review and refine a Cart through the standard Cart update actions.
Create a Quote Request from a Cart that was created first.
Refine a Shopping List through the standard Shopping List update actions, then add its Line Items to a Cart.
Delete the entity and start over.

Because each call is stateless, keep the returned id, and the cartId for a Quote Request, to reference the entity in follow-up API calls.

Representations

AgentResponsesRequest

AgentResponsesPayload

AgentResponsesMultipartRequest

AgentResponsesOutputType

AgentResponsesSuccess

AgentResponsesCartSuccess

AgentResponsesQuoteRequestSuccess

AgentResponsesShoppingListSuccess

Warnings

AgentResponsesErrorResponse

AgentResponsesAuthError

AgentResponsesRequest

JSON body for an application/json request. prompt is required.

JSON body for an application/json /responses request to the Intake Agent. prompt is required.

To attach files, send a multipart/form-data request with an AgentResponsesPayload as the payload part.

`outputType` AgentResponsesOutputType	The entity to create.
`locale` String	A valid BCP 47 language tag, for example `en-US`.
`prompt` String	Natural-language description of the entity to create, such as the body of an email or a note. For a Shopping List, it must state the name of the list.
`businessUnit` BusinessUnitResourceIdentifier	BusinessUnit to use for the request. If omitted, the Intake Agent resolves it from `prompt`.
`store` StoreResourceIdentifier	Store to use for the request. If omitted, the Intake Agent resolves it from `prompt`.

{
  "outputType": "Cart",
  "locale": "en-US",
  "prompt": "Please prepare a cart for jane.doe@example.com. We need 12 of SKU ABC-123 shipped to Germany.",
  "businessUnit": {
    "typeId": "business-unit",
    "key": "acme-west"
  },
  "store": {
    "typeId": "store",
    "key": "west-coast"
  }
}

AgentResponsesPayload

JSON payload part of a multipart/form-data request. prompt is optional when files are attached.

Structured fields for the payload part of a multipart/form-data /responses request to the Intake Agent. prompt is optional when files are attached.

For an application/json request, use AgentResponsesRequest instead.

`outputType` AgentResponsesOutputType	The entity to create.
`locale` String	A valid BCP 47 language tag, for example `en-US`.
`prompt` String	Natural-language description of the entity to create, such as the body of an email or a note. Required if no file is attached. For a Shopping List, the name of the list must be stated in either the prompt or an attached file.
`businessUnit` BusinessUnitResourceIdentifier	BusinessUnit to use for the request. If omitted, the Intake Agent resolves it from the input.
`store` StoreResourceIdentifier	Store to use for the request. If omitted, the Intake Agent resolves it from the input.

{
  "outputType": "QuoteRequest",
  "locale": "en-US",
  "prompt": "Quote for the attached purchase order.",
  "businessUnit": {
    "typeId": "business-unit",
    "key": "acme-west"
  },
  "store": {
    "typeId": "store",
    "key": "west-coast"
  }
}

AgentResponsesMultipartRequest

multipart/form-data body when files are attached.

multipart/form-data body for a /responses request when files are attached. The JSON fields go in the payload part; files go in files parts.

`payload` AgentResponsesPayload	JSON document matching AgentResponsesPayload. Must include `outputType` and `locale`. At least one of `prompt` or `files` must be provided.
`files` Array of File	Supporting files. Repeat this part for each file. Maximum of 3 files, 20 MB each. Allowed content types: `application/pdf`, `text/plain`, `text/csv`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`, `message/rfc822`, `text/markdown`, `text/html`. MinItems: `1`MaxItems: `3`

{
  "payload": {
    "outputType": "QuoteRequest",
    "locale": "en-US",
    "prompt": "Quote for the attached purchase order.",
    "businessUnit": {
      "typeId": "business-unit",
      "key": "acme-west"
    },
    "store": {
      "typeId": "store",
      "key": "west-coast"
    }
  }
}

AgentResponsesOutputType

Entity that the Intake Agent creates from a /responses request. Never inferred from the input.

Cart: Create a Cart.
QuoteRequest: Create a QuoteRequest. Requires a verified Customer, identified by email.
ShoppingList: Create a ShoppingList. Requires a verified Customer, identified by email, and a name for the ShoppingList stated in the input.

AgentResponsesSuccess

Successful 201 responses use a discriminated type based on entityType.

Successful 201 response from a /responses request. Returns the created entity in commercetools REST representation, together with any non-fatal warnings.

The concrete type depends on entityType:

AgentResponsesCartSuccess when a Cart was created
AgentResponsesQuoteRequestSuccess when a QuoteRequest was created
AgentResponsesShoppingListSuccess when a ShoppingList was created

`entityType` AgentResponsesOutputType	The entity that was created. Determines the concrete response type.
`threadId` String	Identifier of the workflow run that produced this response.
`warnings` Array of WarningObject	Non-fatal issues encountered while processing the request. Present only when at least one warning is returned. MinItems: `1`

AgentResponsesCartSuccess

Returned when outputType is Cart.

Successful 201 response from a /responses request when outputType is Cart.

`entityType` AgentResponsesOutputType	`Cart` The entity that was created. Determines the concrete response type.
`threadId` String	Identifier of the workflow run that produced this response.
`entity` Cart	The created Cart in full commercetools REST representation.
`warnings` Array of WarningObject	Non-fatal issues encountered while processing the request. Present only when at least one warning is returned. MinItems: `1`

{
  "entityType": "Cart",
  "entity": {
    "id": "27b39077-aa57-48a5-b504-914f68fa44dc",
    "version": 1,
    "createdAt": "2026-06-23T13:06:28.569Z",
    "lastModifiedAt": "2026-06-23T13:06:28.569Z",
    "lastModifiedBy": {
      "isPlatformClient": false
    },
    "createdBy": {
      "isPlatformClient": false
    },
    "customerEmail": "jane.doe@example.com",
    "businessUnit": {
      "key": "acme-west",
      "typeId": "business-unit"
    },
    "store": {
      "typeId": "store",
      "key": "west-coast"
    },
    "lineItems": [
      {
        "id": "b925a817-d5ad-48bb-a407-29ad8e0649b5",
        "productId": "9f10dcfb-5cc9-4a18-843a-c07f7e22d01f",
        "name": {
          "en": "SAPPHIRE"
        },
        "productType": {
          "typeId": "product-type",
          "id": "2543e1d8-4915-4f72-a3c9-1df9b1b0082d",
          "version": 8
        },
        "productSlug": {
          "en": "sapphire1421832124423"
        },
        "variant": {
          "id": 1,
          "sku": "sku_SAPPHIRE_variant1_1421832124423",
          "prices": [
            {
              "value": {
                "type": "centPrecision",
                "fractionDigits": 2,
                "currencyCode": "EUR",
                "centAmount": 2800
              },
              "id": "8da659ef-9e54-447d-9c36-84912db1848f"
            }
          ],
          "images": [],
          "attributes": [],
          "assets": []
        },
        "price": {
          "value": {
            "type": "centPrecision",
            "fractionDigits": 2,
            "currencyCode": "EUR",
            "centAmount": 2800
          },
          "id": "8da659ef-9e54-447d-9c36-84912db1848f"
        },
        "quantity": 2,
        "discountedPricePerQuantity": [],
        "state": [],
        "priceMode": "Platform",
        "lineItemMode": "Standard",
        "totalPrice": {
          "type": "centPrecision",
          "fractionDigits": 2,
          "currencyCode": "EUR",
          "centAmount": 5600
        },
        "perMethodTaxRate": [],
        "taxedPricePortions": []
      }
    ],
    "cartState": "Active",
    "totalPrice": {
      "type": "centPrecision",
      "currencyCode": "EUR",
      "centAmount": 5600,
      "fractionDigits": 2
    },
    "shippingMode": "Single",
    "shipping": [],
    "customLineItems": [],
    "discountCodes": [],
    "directDiscounts": [],
    "inventoryMode": "None",
    "taxMode": "Platform",
    "priceRoundingMode": "HalfEven",
    "taxRoundingMode": "HalfEven",
    "taxCalculationMode": "LineItemLevel",
    "refusedGifts": [],
    "origin": "Customer",
    "itemShippingAddresses": [],
    "totalLineItemQuantity": 2
  },
  "threadId": "run_01j2x8qz6qfz5b3v9c2d4e6f8g"
}

AgentResponsesQuoteRequestSuccess

Returned when outputType is QuoteRequest.

Successful 201 response from a /responses request when outputType is QuoteRequest.

`entityType` AgentResponsesOutputType	`QuoteRequest` The entity that was created. Determines the concrete response type.
`threadId` String	Identifier of the workflow run that produced this response.
`entity` QuoteRequest	The created QuoteRequest in full commercetools REST representation.
`cartId` String	`id` of the underlying Cart.
`warnings` Array of WarningObject	Non-fatal issues encountered while processing the request. Present only when at least one warning is returned. MinItems: `1`

{
  "entityType": "QuoteRequest",
  "entity": {
    "id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
    "version": 1,
    "createdAt": "2026-06-23T13:06:28.569Z",
    "lastModifiedAt": "2026-06-23T13:06:28.569Z",
    "quoteRequestState": "Submitted",
    "comment": "Give me 10% discount",
    "customer": {
      "typeId": "customer",
      "id": "92f5a867-bf19-47ab-982c-6720a03a3921"
    },
    "businessUnit": {
      "key": "acme-west",
      "typeId": "business-unit"
    },
    "store": {
      "typeId": "store",
      "key": "west-coast"
    },
    "lineItems": [
      {
        "id": "b925a817-d5ad-48bb-a407-29ad8e0649b5",
        "productId": "9f10dcfb-5cc9-4a18-843a-c07f7e22d01f",
        "name": {
          "en": "SAPPHIRE"
        },
        "productType": {
          "typeId": "product-type",
          "id": "2543e1d8-4915-4f72-a3c9-1df9b1b0082d",
          "version": 8
        },
        "productSlug": {
          "en": "sapphire1421832124423"
        },
        "variant": {
          "id": 1,
          "sku": "sku_SAPPHIRE_variant1_1421832124423",
          "prices": [
            {
              "value": {
                "type": "centPrecision",
                "fractionDigits": 2,
                "currencyCode": "EUR",
                "centAmount": 2800
              },
              "id": "8da659ef-9e54-447d-9c36-84912db1848f"
            }
          ],
          "images": [],
          "attributes": [],
          "assets": []
        },
        "price": {
          "value": {
            "type": "centPrecision",
            "fractionDigits": 2,
            "currencyCode": "EUR",
            "centAmount": 2800
          },
          "id": "8da659ef-9e54-447d-9c36-84912db1848f"
        },
        "quantity": 2,
        "discountedPricePerQuantity": [],
        "state": [],
        "priceMode": "Platform",
        "lineItemMode": "Standard",
        "totalPrice": {
          "type": "centPrecision",
          "fractionDigits": 2,
          "currencyCode": "EUR",
          "centAmount": 5600
        },
        "perMethodTaxRate": [],
        "taxedPricePortions": []
      }
    ],
    "totalPrice": {
      "type": "centPrecision",
      "fractionDigits": 2,
      "currencyCode": "EUR",
      "centAmount": 5600
    },
    "customLineItems": [],
    "directDiscounts": [],
    "inventoryMode": "None",
    "taxMode": "Platform",
    "priceRoundingMode": "HalfEven",
    "taxRoundingMode": "HalfEven",
    "taxCalculationMode": "LineItemLevel"
  },
  "cartId": "27b39077-aa57-48a5-b504-914f68fa44dc",
  "warnings": [
    {
      "code": "ProductsNotFound",
      "message": "The following requested products could not be matched to the catalog and were omitted: SKU-999.",
      "products": [
        "SKU-999"
      ]
    }
  ],
  "threadId": "run_01j2x8qz6qfz5b3v9c2d4e6f8h"
}

AgentResponsesShoppingListSuccess

Returned when outputType is ShoppingList.

Successful 201 response from a /responses request when outputType is ShoppingList.

`entityType` AgentResponsesOutputType	`ShoppingList` The entity that was created. Determines the concrete response type.
`threadId` String	Identifier of the workflow run that produced this response.
`entity` ShoppingList	The created ShoppingList in full commercetools REST representation.
`warnings` Array of WarningObject	Non-fatal issues encountered while processing the request. Present only when at least one warning is returned. MinItems: `1`

{
  "entityType": "ShoppingList",
  "entity": {
    "id": "8c1a9e34-6d0f-4b2e-9a71-1f5d7c3e0a42",
    "version": 1,
    "name": {
      "en-US": "Q3 restock"
    },
    "description": {
      "en-US": "Items to reorder before the end of the quarter."
    },
    "customer": {
      "typeId": "customer",
      "id": "92f5a867-bf19-47ab-982c-6720a03a3921"
    },
    "businessUnit": {
      "typeId": "business-unit",
      "key": "acme-west"
    },
    "store": {
      "typeId": "store",
      "key": "west-coast"
    },
    "lineItems": [
      {
        "id": "b925a817-d5ad-48bb-a407-29ad8e0649b5",
        "name": {
          "en-US": "SAPPHIRE"
        },
        "productId": "9f10dcfb-5cc9-4a18-843a-c07f7e22d01f",
        "productType": {
          "typeId": "product-type",
          "id": "2543e1d8-4915-4f72-a3c9-1df9b1b0082d"
        },
        "published": true,
        "variantId": 1,
        "quantity": 12,
        "addedAt": "2026-06-23T13:06:28.569Z"
      },
      {
        "id": "3e4c6f18-70a2-4d5b-8c93-2b8d1a7f6c04",
        "name": {
          "en-US": "OPAL"
        },
        "productId": "c0f2b8d4-1e37-4a6b-9d52-8f3a7c1e5b90",
        "productType": {
          "typeId": "product-type",
          "id": "2543e1d8-4915-4f72-a3c9-1df9b1b0082d"
        },
        "published": false,
        "variantId": 1,
        "quantity": 4,
        "addedAt": "2026-06-23T13:06:28.569Z"
      }
    ],
    "textLineItems": [],
    "createdAt": "2026-06-23T13:06:28.569Z",
    "lastModifiedAt": "2026-06-23T13:06:28.569Z"
  },
  "warnings": [
    {
      "code": "ProductsNotFound",
      "message": "The following requested products could not be matched to the catalog and were omitted: SKU-999.",
      "products": [
        "SKU-999"
      ]
    }
  ],
  "threadId": "run_01j2x8qz6qfz5b3v9c2d4e6f8i"
}

Warnings

Warnings use a WarningObject with a machine-readable code. See Warnings for the full list, including ProductsNotFound and FileNotProcessed, which are specific to the Intake Agent.

AgentResponsesErrorResponse

Except for 401 and 403 responses, errors use this envelope: a statusCode, a human-readable message, and one or more errors.

Error response from a /responses request. Extends ErrorResponse with a threadId for support.

`statusCode` Int	HTTP status code corresponding to the error.
`message` String	First error message in the `errors` array.
`errors` Array of ErrorObject	Errors returned for a request. A single error response can contain multiple errors if the errors are related to the same HTTP status code such as `400`. MinItems: `1`
`threadId` String	Identifier of the workflow run that raised the error. Present on errors raised once the workflow has started. Absent on errors raised while parsing the request, before the workflow starts.

{
  "statusCode": 400,
  "message": "No line items could be extracted from the provided input.",
  "errors": [
    {
      "code": "NoLineItemsExtracted",
      "message": "No line items could be extracted from the provided input."
    }
  ],
  "threadId": "run_01j2x8qz6qfz5b3v9c2d4e6f8g"
}

AgentResponsesAuthError

A 401 or 403 response uses the standard AuthErrorResponse shape (statusCode, message, errors, plus OAuth error / error_description) rather than the AgentResponsesErrorResponse envelope. Typical OAuth codes are invalid_token (401) and insufficient_scope (403).

Authentication or authorization failure from a /responses request. Uses the standard AuthErrorResponse shape (statusCode, message, errors, plus OAuth error / error_description) rather than the AgentResponsesErrorResponse envelope used for other errors from this endpoint.

`statusCode` Int	HTTP status code corresponding to the error.
`message` String	First error message in the `errors` array.
`errors` Array of ErrorObject	Authentication and authorization-related errors returned for a request.
`error` String	Error code as per the OAuth 2.0 specification. For example: `"access_denied"`.
`error_description` String	Plain text description of the first error.

{
  "statusCode": 401,
  "message": "Authorization header is required.",
  "errors": [
    {
      "code": "invalid_token",
      "message": "Authorization header is required."
    }
  ],
  "error": "invalid_token",
  "error_description": "Authorization header is required."
}

Intake Agent

When to use the Intake Agent.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Required information.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Shopping List name.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Supported input.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Handling unmatched input.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Unpublished Products in a Shopping List.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Endpoints.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Create a Cart, Quote Request, or Shopping List.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Multipart form data.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Error codes.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Next actions.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Representations.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

AgentResponsesRequest.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

AgentResponsesPayload.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

AgentResponsesMultipartRequest.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

AgentResponsesOutputType.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

AgentResponsesSuccess.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

AgentResponsesCartSuccess.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

AgentResponsesQuoteRequestSuccess.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

AgentResponsesShoppingListSuccess.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Warnings.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

AgentResponsesErrorResponse.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

AgentResponsesAuthError.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

When to use the Intake Agent

Required information

Shopping List name

Supported input

Handling unmatched input

Unpublished Products in a Shopping List

Endpoints

Create a Cart, Quote Request, or Shopping List

Multipart form data

Error codes

Next actions

Representations

AgentResponsesRequest

AgentResponsesPayload

AgentResponsesMultipartRequest

AgentResponsesOutputType

AgentResponsesSuccess

AgentResponsesCartSuccess

AgentResponsesQuoteRequestSuccess

AgentResponsesShoppingListSuccess

Warnings

AgentResponsesErrorResponse

AgentResponsesAuthError