curl --location --request POST 'https://api.stateset.com/api/v1/carts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
"customer_id": "cust_abc123",
"channel": "web",
"currency": "USD",
"locale": "en-US",
"items": [
{
"product_id": "prod_123",
"variant_id": "var_blue_large",
"quantity": 2
}
],
"shipping_address": {
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
}
}'
const cart = await stateset.carts.create({
customer_id: "cust_abc123",
channel: "web",
currency: "USD",
locale: "en-US",
items: [
{
product_id: "prod_123",
variant_id: "var_blue_large",
quantity: 2
}
],
shipping_address: {
city: "San Francisco",
state: "CA",
postal_code: "94105",
country: "US"
}
});
cart = stateset.carts.create(
customer_id="cust_abc123",
channel="web",
currency="USD",
locale="en-US",
items=[
{
"product_id": "prod_123",
"variant_id": "var_blue_large",
"quantity": 2
}
],
shipping_address={
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
}
)
{
"id": "cart_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
"object": "cart",
"customer_id": "cust_abc123",
"session_id": "sess_xyz789",
"channel": "web",
"currency": "USD",
"locale": "en-US",
"status": "active",
"items": [
{
"id": "ci_abc123",
"product_id": "prod_123",
"variant_id": "var_blue_large",
"product_name": "Wireless Headphones",
"variant_name": "Blue - Large",
"sku": "WH-BL-L",
"quantity": 2,
"unit_price": 9999,
"list_price": 9999,
"subtotal": 19998,
"discounts": [],
"image_url": "https://images.stateset.com/products/wh-blue-large.jpg",
"metadata": {}
}
],
"item_count": 2,
"unique_item_count": 1,
"subtotal": 19998,
"tax_amount": 0,
"shipping_amount": 0,
"discount_amount": 0,
"total": 19998,
"shipping_address": {
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
},
"available_shipping_methods": [],
"applied_coupons": [],
"applied_promotions": [],
"expires_at": "2024-07-20T10:00:00Z",
"created_at": "2024-06-20T10:00:00Z",
"updated_at": "2024-06-20T10:00:00Z",
"metadata": {}
}
Create Cart
Create a new shopping cart for a customer or guest session
POST
/
api
/
v1
/
carts
curl --location --request POST 'https://api.stateset.com/api/v1/carts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
"customer_id": "cust_abc123",
"channel": "web",
"currency": "USD",
"locale": "en-US",
"items": [
{
"product_id": "prod_123",
"variant_id": "var_blue_large",
"quantity": 2
}
],
"shipping_address": {
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
}
}'
const cart = await stateset.carts.create({
customer_id: "cust_abc123",
channel: "web",
currency: "USD",
locale: "en-US",
items: [
{
product_id: "prod_123",
variant_id: "var_blue_large",
quantity: 2
}
],
shipping_address: {
city: "San Francisco",
state: "CA",
postal_code: "94105",
country: "US"
}
});
cart = stateset.carts.create(
customer_id="cust_abc123",
channel="web",
currency="USD",
locale="en-US",
items=[
{
"product_id": "prod_123",
"variant_id": "var_blue_large",
"quantity": 2
}
],
shipping_address={
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
}
)
{
"id": "cart_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
"object": "cart",
"customer_id": "cust_abc123",
"session_id": "sess_xyz789",
"channel": "web",
"currency": "USD",
"locale": "en-US",
"status": "active",
"items": [
{
"id": "ci_abc123",
"product_id": "prod_123",
"variant_id": "var_blue_large",
"product_name": "Wireless Headphones",
"variant_name": "Blue - Large",
"sku": "WH-BL-L",
"quantity": 2,
"unit_price": 9999,
"list_price": 9999,
"subtotal": 19998,
"discounts": [],
"image_url": "https://images.stateset.com/products/wh-blue-large.jpg",
"metadata": {}
}
],
"item_count": 2,
"unique_item_count": 1,
"subtotal": 19998,
"tax_amount": 0,
"shipping_amount": 0,
"discount_amount": 0,
"total": 19998,
"shipping_address": {
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
},
"available_shipping_methods": [],
"applied_coupons": [],
"applied_promotions": [],
"expires_at": "2024-07-20T10:00:00Z",
"created_at": "2024-06-20T10:00:00Z",
"updated_at": "2024-06-20T10:00:00Z",
"metadata": {}
}
This endpoint creates a new shopping cart that persists across sessions. Carts can be associated with authenticated customers or anonymous sessions.
Authentication
This endpoint requires a valid API key withcarts:write permissions.
Authorization: Bearer YOUR_API_KEY
Request Body
string
Customer ID to associate with the cart (for authenticated users)
string
Session ID for guest carts (auto-generated if not provided)
string
Sales channel: “web”, “mobile”, “pos”, “api”
string
required
ISO 4217 currency code
string
Locale for the cart (e.g., “en-US”)
array
object
string
Email for guest checkout and abandoned cart recovery
string
Custom expiration date (ISO 8601, default: 30 days)
object
Additional custom fields
Response
Returns the created cart object.curl --location --request POST 'https://api.stateset.com/api/v1/carts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
"customer_id": "cust_abc123",
"channel": "web",
"currency": "USD",
"locale": "en-US",
"items": [
{
"product_id": "prod_123",
"variant_id": "var_blue_large",
"quantity": 2
}
],
"shipping_address": {
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
}
}'
const cart = await stateset.carts.create({
customer_id: "cust_abc123",
channel: "web",
currency: "USD",
locale: "en-US",
items: [
{
product_id: "prod_123",
variant_id: "var_blue_large",
quantity: 2
}
],
shipping_address: {
city: "San Francisco",
state: "CA",
postal_code: "94105",
country: "US"
}
});
cart = stateset.carts.create(
customer_id="cust_abc123",
channel="web",
currency="USD",
locale="en-US",
items=[
{
"product_id": "prod_123",
"variant_id": "var_blue_large",
"quantity": 2
}
],
shipping_address={
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
}
)
{
"id": "cart_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
"object": "cart",
"customer_id": "cust_abc123",
"session_id": "sess_xyz789",
"channel": "web",
"currency": "USD",
"locale": "en-US",
"status": "active",
"items": [
{
"id": "ci_abc123",
"product_id": "prod_123",
"variant_id": "var_blue_large",
"product_name": "Wireless Headphones",
"variant_name": "Blue - Large",
"sku": "WH-BL-L",
"quantity": 2,
"unit_price": 9999,
"list_price": 9999,
"subtotal": 19998,
"discounts": [],
"image_url": "https://images.stateset.com/products/wh-blue-large.jpg",
"metadata": {}
}
],
"item_count": 2,
"unique_item_count": 1,
"subtotal": 19998,
"tax_amount": 0,
"shipping_amount": 0,
"discount_amount": 0,
"total": 19998,
"shipping_address": {
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
},
"available_shipping_methods": [],
"applied_coupons": [],
"applied_promotions": [],
"expires_at": "2024-07-20T10:00:00Z",
"created_at": "2024-06-20T10:00:00Z",
"updated_at": "2024-06-20T10:00:00Z",
"metadata": {}
}
⌘I