---
updatedAt: 2026-11-20T11:47:08.000Z
agentTools:
  projectIndex: https://docs.cartai.ai/llms.txt
---

# Getting Started

Welcome to the CartAI API. This guide walks you through everything you need to make your first API call — from creating an account to sending a checkout request.

## Step 1 — Create Your Account

CartAI keeps things simple with a single environment for both testing and going live — no separate sandbox or production URLs to manage. You can build and test your integration in one place, with simulated transactions during development.

**Sign up here:** <https://portal.cartai.ai/signup>

Fill in your name, email, and a password. Once your account is created, you will land on the CartAI's portal.

> **Note:**
>
> By default, CartAI operates in a testing mode where credit cards are **not tokenized**. Because of this, you should **not use real credit card details** while testing your integration.<br />
>
> For development and testing, you can use the following <br /> Sample test card:
>
> * **Card Number:** `4242 4242 4242 4242`
> * **Expiry Date:** `12/34`
> * **CVV:** `444`
>
> Once you have completed your checkout testing and are ready to move forward, you can request access to **Tokenization** and **VIC flows** directly from the CartAI Dashboard using the **“Request Go Live”** button.
>
> Our team will review your request and enable the required production features for your account.

***

## Step 2 — Generate Your API Key

Once you are logged in to the portal:

1. Check the left sidebar.
2. Open the **API Keys** section.
3. Click **Generate New Key**.
4. Copy the key and store it somewhere safe.

> **Keep your API key secret.** <br /> Do not commit it to source control, expose it in client-side code, or share it publicly. If a key is ever compromised, return to the portal and revoke it immediately, then generate a new one.

***

## Step 3 — Authenticate Your Requests

CartAI uses a simple API key header for authentication. Every request to the API must include the following header:

```
X-API-Key: <your_api_key>
```

Replace `<your_api_key>` with the key you generated in Step 2.

### Example — curl

```bash
curl --request POST \
     --url https://api.cartai.ai/checkout \
     --header 'accept: application/json' \
     --header 'X-API-Key: <YOUR_API_KEY>' \
     --header 'content-type: application/json' \
     --data '
{
  "customer": {
    "contact": {
      "lastName": "Sturka",
      "firstName": "Carol",
      "phone": "+12144444444",
      "email": "john.doe@example.com"
    },
    "shippingAddress": {
      "addressLine1": "5321 Seascape Ln",
      "addressLine2": "",
      "city": "Plano",
      "province": "TX",
      "postalCode": "75093",
      "country": "US"
    },
    "billingAddress": {
      "addressLine1": "5321 Seascape Ln",
      "addressLine2": "",
      "city": "Plano",
      "province": "TX",
      "postalCode": "75093",
      "country": "US"
    },
    "shippingMethod": {
      "strategy": "cheapest"
    },
    "payment": {
      "data": {
          "cvv": "444",
          "name": "Carol Sturka",
          "cardNumber": "4242424242424242",
          "expiryYear": "2034",
          "expiryMonth": "12"
      },
      "provider": "test"
    }
  },
  "tasks": [
    {
      "url": "https://www.aloyoga.com/products/w1518r-semi-sheer-mock-neck-oasis-tank-ivory",
      "quantity": 1,
      "selectedVariant": {
          "Size": "M",
          "Color": "Ivory"
      },
      "metadata": {
        "title": "",
        "description": "",
        "primaryImage": "",
        "price": ""
      }
    }
  ],
  "options": {
    "verifyBeforePlacement": false,
    "useSavedCredentialToLogin": false,
    "useGuestCheckoutIfLoginFails": false,
    "allowInteraction": false,
    "allowPartialCheckout": true
  }
}
'
```

### Example — JavaScript (fetch)

```javascript
const response = await fetch('https://api.cartai.ai/checkout', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.CARTAI_API_KEY  // store your key in an environment variable
  },
  body: JSON.stringify({
    //Payload for Checkout Request
    "customer": { //... }
  })
});

const data = await response.json();
console.log(data);
```

### Example — Python

```python
import os
import requests

response = requests.post(
    'https://api.cartai.ai/checkout',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': os.environ['CARTAI_API_KEY']  # store your key in an environment variable
    },
    json={
        #Payload for Checkout Request
        "customer": { 
          #... 
        }
    }
)

print(response.json())
```

> **Best practice:** Always load your API key from an environment variable rather than hardcoding it. Use a `.env` file locally (with a library like `dotenv` for Node.js or `python-dotenv` for Python) and inject it via your hosting platform's secrets manager in production.

***

## Authentication Errors

If your API key is missing or invalid, the API will return a `401 Unauthorized` response:

```json
{
  "error": "unauthorized",
  "message": "Missing or invalid API key. Include your key as the X-API-Key header."
}
```

| HTTP status        | Meaning                                                         |
| ------------------ | --------------------------------------------------------------- |
| `401 Unauthorized` | API key is missing, malformed, or has been revoked              |
| `403 Forbidden`    | API key is valid but does not have permission for this resource |

If you receive a `401`, double-check that:

* The header name is exactly `X-API-Key` (case-sensitive)
* The key has not been revoked in the portal

***

## Next steps

Now that you are authenticated, you are ready to start building:

* **[Checkout Scenarios](https://docs.cartai.ai/docs/checkout-scenarios)** — understand how single SKU, multi-SKU, and multi-merchant orders work
* **[Checkout API](https://docs.cartai.ai/reference/create-checkout-task)** — Detail endpoint documentation for Creating a Checkout Task or Placing an order.