When to Use This Endpoint

The Cancel Checkout Task endpoint gives you programmatic control to abort a checkout before it completes. Common scenarios where you would call this:

⚠️

This action is irreversible. Once a task is cancelled, it cannot be resumed. If you need to proceed with the same order, create a new checkout task via POST /checkout.

Key Behaviours to Understand

This is an asynchronous API. A 200 OK response means CartAI has accepted your cancellation request — not that the task has stopped yet. The AI agent winds down its current execution in the background. Treat the CANCELLED webhook event as the definitive signal that the task has fully stopped.

The CANCELLED webhook is the source of truth. After a successful 200 response, CartAI will emit a CANCELLED status event to your configured webhook endpoint. Do not update your UI or internal order state until this event is received.

Cancelling an already-terminal task. If the task has already reached COMPLETED, FAILED, or CANCELLED, the cancellation request will return a 400 Bad Request. You cannot cancel a task that has already ended.

Cancellation does not trigger a refund. If the AI agent had already reached the payment step and a charge was initiated before the cancellation was processed, you are responsible for handling any refund through your payment provider.

Authentication

Every request must include your API key in the request header.

x-api-key: YOUR_API_KEY_HERE

• Always call this endpoint from your backend — never expose your API key in client-side code.

Request

No request body is required. Pass the taskId as a path parameter.

Full Request Example

curl --location --request DELETE 'https://api.cartai.ai/checkout/019bd5c5-2824-76d1-aa7a-01db5c4d7065' \
  --header 'x-api-key: YOUR_API_KEY_HERE'

Multi-Merchant Orders and Cancellation

When a checkout task spans multiple merchants (multiple product URLs from different domains in the tasks array), CartAI spawns a separate agent per merchant. Each agent has its own taskId, but they share a groupId.

To cancel a multi-merchant order, you must cancel each merchant's task individually. There is no single group-level cancel endpoint.

// Cancel all tasks in a group
async function cancelGroup(taskIds, apiKey) {
  const results = await Promise.allSettled(
    taskIds.map(async (taskId) => {
      // Get the current status for each task
      const res  = await fetch(`https://api.cartai.ai/checkout/${taskId}`, {
        headers: { "x-api-key": apiKey }
      });
      const task = await res.json();

      // Skip tasks already in a terminal state
      if (["COMPLETED", "FAILED", "CANCELLED"].includes(task.status)) {
        return { taskId, skipped: true, reason: task.status };
      }

      // Cancel each task
      const cancelRes = await fetch(`https://api.cartai.ai/checkout/${taskId}`, {
        method:  "DELETE",
        headers: { "x-api-key": apiKey }
      });

      return { taskId, cancelled: cancelRes.ok, status: cancelRes.status };
    })
  );

  results.forEach(({ value, reason }) => {
    if (reason) console.error("Unexpected error:", reason);
    else console.log(value);
  });
}

Error reference table