Getting Started

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.

For development and testing, you can use the following
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.
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

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": "5555555555",
      "email": "[email protected]"
    },
    "shippingAddress": {
      "addressLine1": "123 Main St",
      "addressLine2": "Apt 1",
      "city": "New York",
      "province": "NY",
      "postalCode": "10001",
      "country": "US"
    },
    "billingAddress": {
      "addressLine1": "123 Main St",
      "addressLine2": "Apt 1",
      "city": "New York",
      "province": "NY",
      "postalCode": "10001",
      "country": "US"
    },
    "shippingMethod": {
      "strategy": "cheapest"
    },
    "payment": {
      "data": {
          "cvv": "444",
          "name": "Carol Sturka",
          "cardNumber": "4242424242424242",
          "expiryYear": "2034",
          "expiryMonth": "12"
      },
      "provider": "test"
    }
  },
  "tasks": [
    {
      "url": "https://saltiebeauty.com/products/seaweed-hydrating-shampoo",
      "quantity": 1,
      "selectedVariant": {},
      "metadata": {
        "title": "",
        "description": "",
        "primaryImage": "",
        "price": ""
      }
    }
  ],
  "options": {
    "verifyBeforePlacement": false,
    "failTaskIfNotConfirmed": false,
    "allowPartialCheckoutForMultiSku": true
  }
}
'

Example — JavaScript (fetch)

const response = await fetch('https://api.cartai.ai/v1/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

import os
import requests

response = requests.post(
    'https://api.cartai.ai/v1/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:

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

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 — understand how single SKU, multi-SKU, and multi-merchant orders work
• Checkout API — Detail endpoint documentation for Creating a Checkout Task or Placing an order.