Intake Agent

B2CB2BB2XB2C CORE COMMERCEB2B CORE COMMERCEB2X CORE COMMERCE

Convert unstructured customer input into a Cart or Quote Request 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 or Quote Request 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 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 or a Quote Request.
  • 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 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, such as RequiredField, BusinessUnitUnresolved, or StoreUnresolved.

Supported input

Input typeNotes
Free textA natural-language prompt, such as the body of an email, a message, or a note.
File uploadPDF, 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.

Representations

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 desired Cart or Quote Request, such as the body of an email or a note.

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.
Example: json
{
  "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 desired Cart or Quote Request, such as the body of an email or a note. Required if no file is attached.

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.
Example: json
{
  "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​
Example: json
{
  "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.

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:
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​
Example: json
{
  "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​
Example: json
{
  "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"
}

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.

Example: json
{
  "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.

Example: json
{
  "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."
}

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 currently supported by this endpoint.

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

Create a Cart or Quote Request

POST
https://api.{region}.commercetools.com/{projectKey}/agents/intake/v1/responses
Turns a natural-language prompt, optionally with supporting files, into a created Cart or QuoteRequest, returned in commercetools REST representation.
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.
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
Response:
201

AgentResponsesSuccess

as
application/json
Request Example:cURL
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
201 Response Example: AgentResponsesSuccessjson
{
  "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"
}

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)
Create a Quote Request with an uploaded filebash
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.

Next actions

The created entity is a standard commercetools Cart or Quote Request, 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.
  • 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.