Add to Cart

Add a product to the customer's cart. This endpoint adds a product with the specified quantity to the cart associated with the current session or authenticated customer.

Endpoint

POST /v1/cart

Base URL: https://api.storekit.app

Authentication

Info: All API requests require authentication using an API key. Generate your API key from the StoreKit Dashboard under API Key Usage section.

Headers

Name	Type	Required	Description
`x-api-key`	`string`	Yes	Your API key for authentication
`Content-Type`	`string`	Yes	Must be `application/json`

Request Body

Field	Type	Required	Description
`productId`	`string`	Yes	Unique identifier of the product to add
`quantity`	`number`	Yes	Quantity of the product to add (minimum: 1)

Request Example

{
  "productId": "cmc36x85s0007nx0koog2cn0b",
  "quantity": 2
}

Response

Success Response (200 OK)

{
  "success": true,
  "message": "Added to cart"
}

Response Schema

Field	Type	Description
`success`	`boolean`	Indicates if the request was successful
`message`	`string`	Descriptive message about the operation

Error Responses

401 Unauthorized

{
  "error": "API key is required"
}

404 Not Found

{
  "success": false,
  "message": "Invalid combination of productId or customerId"
}

409 Conflict

{
  "success": false,
  "message": "Product already in cart"
}

422 Unprocessable Entity

{
  "success": false,
  "message": "Invalid input data",
  "errors": [
    {
      "code": "invalid_type",
      "expected": "string",
      "received": "undefined",
      "path": ["productId"],
      "message": "Required"
    }
  ]
}

500 Internal Server Error

{
  "success": false,
  "message": "Failed to add item to cart"
}

Code Examples

curl -X POST "https://api.storekit.app/v1/cart" \
  -H "x-api-key: sk_live_be186797384f05ff038e1751e8ff9572cf8a05adfdba79abb7e8bcd165f2c402" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "cmc36x85s0007nx0koog2cn0b",
    "quantity": 2
  }'

const response = await fetch("https://api.storekit.app/v1/cart", {
  method: "POST",
  headers: {
    "x-api-key":
      "sk_live_be186797384f05ff038e1751e8ff9572cf8a05adfdba79abb7e8bcd165f2c402",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    productId: "cmc36x85s0007nx0koog2cn0b",
    quantity: 2,
  }),
});

const data = await response.json();

if (data.success) {
  console.log("Success:", data.message);
} else {
  console.error("Error:", data.message);
}

import axios from "axios";

try {
  const response = await axios.post(
    "https://api.storekit.app/v1/cart",
    {
      productId: "cmc36x85s0007nx0koog2cn0b",
      quantity: 2,
    },
    {
      headers: {
        "x-api-key":
          "sk_live_be186797384f05ff038e1751e8ff9572cf8a05adfdba79abb7e8bcd165f2c402",
        "Content-Type": "application/json",
      },
    }
  );

  const { success, message } = response.data;

  if (success) {
    console.log("Success:", message);
  } else {
    console.error("Error:", message);
  }
} catch (error) {
  console.error("Request failed:", error.response?.data || error.message);
}

const https = require("https");

const postData = JSON.stringify({
  productId: "cmc36x85s0007nx0koog2cn0b",
  quantity: 2,
});

const options = {
  hostname: "api.storekit.app",
  port: 443,
  path: "/v1/cart",
  method: "POST",
  headers: {
    "x-api-key":
      "sk_live_be186797384f05ff038e1751e8ff9572cf8a05adfdba79abb7e8bcd165f2c402",
    "Content-Type": "application/json",
    "Content-Length": Buffer.byteLength(postData),
  },
};

const req = https.request(options, (res) => {
  let data = "";

  res.on("data", (chunk) => {
    data += chunk;
  });

  res.on("end", () => {
    const result = JSON.parse(data);

    if (result.success) {
      console.log("Success:", result.message);
    } else {
      console.error("Error:", result.message);
    }
  });
});

req.on("error", (error) => {
  console.error("Request failed:", error);
});

req.write(postData);
req.end();

import requests
import json

url = "https://api.storekit.app/v1/cart"
headers = {
    "x-api-key": "sk_live_be186797384f05ff038e1751e8ff9572cf8a05adfdba79abb7e8bcd165f2c402",
    "Content-Type": "application/json"
}

payload = {
    "productId": "cmc36x85s0007nx0koog2cn0b",
    "quantity": 2
}

try:
    response = requests.post(url, headers=headers, json=payload)
    response.raise_for_status()

    data = response.json()

    if data['success']:
        print(f"Success: {data['message']}")
    else:
        print(f"Error: {data['message']}")

except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")

<?php
$curl = curl_init();

$payload = json_encode([
    'productId' => 'cmc36x85s0007nx0koog2cn0b',
    'quantity' => 2
]);

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.storekit.app/v1/cart",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => [
        "x-api-key: sk_live_be186797384f05ff038e1751e8ff9572cf8a05adfdba79abb7e8bcd165f2c402",
        "Content-Type: application/json"
    ],
]);

$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

$data = json_decode($response, true);

if ($httpCode === 200 && $data['success']) {
    echo "Success: " . $data['message'] . "\n";
} else {
    echo "Error: " . $data['message'] . "\n";
}
?>

$.ajax({
  url: "https://api.storekit.app/v1/cart",
  method: "POST",
  headers: {
    "x-api-key":
      "sk_live_be186797384f05ff038e1751e8ff9572cf8a05adfdba79abb7e8bcd165f2c402",
    "Content-Type": "application/json",
  },
  data: JSON.stringify({
    productId: "cmc36x85s0007nx0koog2cn0b",
    quantity: 2,
  }),
  success: function (data) {
    if (data.success) {
      console.log("Success:", data.message);
      
      // Example: Show success message
      $("#cart-message").text(data.message).addClass("success");
    } else {
      console.error("Error:", data.message);
    }
  },
  error: function (xhr, status, error) {
    console.error("Request failed:", error);
    
    // Handle different error types
    if (xhr.responseJSON) {
      $("#cart-message").text(xhr.responseJSON.message).addClass("error");
    }
  },
});

Authentication & Session Management

This endpoint automatically handles both authenticated and anonymous users:

Authenticated users: Products are associated with their customer account

Anonymous users: Products are tracked using session cookies that are automatically managed

No manual session management is required - the API handles this automatically through cookies.

Error Handling

The API returns specific error codes for different scenarios:

Missing API Key: Returns 401 with message "API key is required"
Invalid Product ID: Returns 404 with message "Invalid combination of productId or customerId"
Missing Product ID: Returns 404 with message "Invalid combination of productId or customerId"
Invalid Request Data: Returns 422 with validation errors
Server Error: Returns 500 with message "Failed to add item to cart"

Important Notes

The quantity field must be a positive integer (minimum: 1)
Session data is automatically managed through cookies
API key is required for all requests and can be generated in your StoreKit Dashboard
If a product is already in the cart, then its quantity gets incremented to what quantity it will be provided in request body

Customer Context

Info: This endpoint uses customer identification middleware that manages items by:

Authenticated users: Items are associated with their customerId

Guest users: Items are tracked by sessionId for the current browser session automatically

Use Cases

Add products to cart from product detail pages
Bulk add multiple quantities of the same product
Handle both authenticated and guest user shopping experiences
Build shopping cart functionality for e-commerce applications

Quick Start

Step 1: Get your API Key

Navigate to your StoreKit Dashboard and go to the API Key Usage section to generate your API key.

Step 2: Prepare your request

Ensure you have a valid productId and specify the desired quantity.

Step 3: Make the request

Use any of the code examples above to add the product to the cart. The API will automatically identify the customer based on their session.

Step 4: Handle the response

Check the success field and handle any errors appropriately. Display success messages or error notifications to your users based on the response.

Add to Cart

On this page