curl -X POST https://api.stateset.com/v1/orders \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"customer": {
"email": "john.doe@example.com",
"first_name": "John",
"last_name": "Doe",
"phone": "+1234567890"
},
"items": [
{
"sku": "TSHIRT-BLUE-L",
"quantity": 2,
"price": 1999,
"name": "Blue T-Shirt (Large)"
},
{
"sku": "HAT-RED",
"quantity": 1,
"price": 1499,
"name": "Red Baseball Cap"
}
],
"shipping_address": {
"line1": "123 Main Street",
"line2": "Apt 4B",
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
},
"payment": {
"method": "card",
"payment_intent_id": "pi_1234567890"
},
"shipping": {
"method": "standard",
"carrier": "ups"
},
"metadata": {
"source": "web",
"campaign": "summer-sale"
}
}'
mutation CreateOrder($input: OrderCreateInput!) {
orderCreate(input: $input) {
order {
id
orderNumber
status
customer {
email
firstName
lastName
}
items {
sku
quantity
price
total
}
totals {
subtotal
tax
shipping
total
}
createdAt
}
userErrors {
field
message
}
}
}
const order = await stateset.orders.create({
customer: {
email: 'john.doe@example.com',
first_name: 'John',
last_name: 'Doe',
phone: '+1234567890'
},
items: [
{
sku: 'TSHIRT-BLUE-L',
quantity: 2,
price: 1999,
name: 'Blue T-Shirt (Large)'
}
],
shipping_address: {
line1: '123 Main Street',
city: 'San Francisco',
state: 'CA',
postal_code: '94105',
country: 'US'
},
payment: {
method: 'card',
payment_intent_id: 'pi_1234567890'
}
});
order = stateset.orders.create(
customer={
'email': 'john.doe@example.com',
'first_name': 'John',
'last_name': 'Doe',
'phone': '+1234567890'
},
items=[
{
'sku': 'TSHIRT-BLUE-L',
'quantity': 2,
'price': 1999,
'name': 'Blue T-Shirt (Large)'
}
],
shipping_address={
'line1': '123 Main Street',
'city': 'San Francisco',
'state': 'CA',
'postal_code': '94105',
'country': 'US'
},
payment={
'method': 'card',
'payment_intent_id': 'pi_1234567890'
}
)
order = Stateset::Order.create({
customer: {
email: 'john.doe@example.com',
first_name: 'John',
last_name: 'Doe',
phone: '+1234567890'
},
items: [
{
sku: 'TSHIRT-BLUE-L',
quantity: 2,
price: 1999,
name: 'Blue T-Shirt (Large)'
}
],
shipping_address: {
line1: '123 Main Street',
city: 'San Francisco',
state: 'CA',
postal_code: '94105',
country: 'US'
},
payment: {
method: 'card',
payment_intent_id: 'pi_1234567890'
}
})
order, err := stateset.Orders.Create(&stateset.OrderParams{
Customer: &stateset.CustomerParams{
Email: "john.doe@example.com",
FirstName: "John",
LastName: "Doe",
Phone: "+1234567890",
},
Items: []*stateset.OrderItemParams{
{
SKU: "TSHIRT-BLUE-L",
Quantity: 2,
Price: 1999,
Name: "Blue T-Shirt (Large)",
},
},
ShippingAddress: &stateset.AddressParams{
Line1: "123 Main Street",
City: "San Francisco",
State: "CA",
PostalCode: "94105",
Country: "US",
},
Payment: &stateset.PaymentParams{
Method: "card",
PaymentIntentID: "pi_1234567890",
},
})
Map<String, Object> params = new HashMap<>();
params.put("customer", Map.of(
"email", "john.doe@example.com",
"first_name", "John",
"last_name", "Doe",
"phone", "+1234567890"
));
params.put("items", List.of(Map.of(
"sku", "TSHIRT-BLUE-L",
"quantity", 2,
"price", 1999,
"name", "Blue T-Shirt (Large)"
)));
params.put("shipping_address", Map.of(
"line1", "123 Main Street",
"city", "San Francisco",
"state", "CA",
"postal_code", "94105",
"country", "US"
));
params.put("payment", Map.of(
"method", "card",
"payment_intent_id", "pi_1234567890"
));
Order order = stateset.orders().create(params);
$order = $stateset->orders->create([
'customer' => [
'email' => 'john.doe@example.com',
'first_name' => 'John',
'last_name' => 'Doe',
'phone' => '+1234567890',
],
'items' => [
[
'sku' => 'TSHIRT-BLUE-L',
'quantity' => 2,
'price' => 1999,
'name' => 'Blue T-Shirt (Large)',
],
],
'shipping_address' => [
'line1' => '123 Main Street',
'city' => 'San Francisco',
'state' => 'CA',
'postal_code' => '94105',
'country' => 'US',
],
'payment' => [
'method' => 'card',
'payment_intent_id' => 'pi_1234567890',
],
]);
var order = await stateset.Orders.CreateAsync(new OrderCreateParams
{
Customer = new CustomerParams
{
Email = "john.doe@example.com",
FirstName = "John",
LastName = "Doe",
Phone = "+1234567890"
},
Items = new List<OrderItemParams>
{
new OrderItemParams
{
Sku = "TSHIRT-BLUE-L",
Quantity = 2,
Price = 1999,
Name = "Blue T-Shirt (Large)"
}
},
ShippingAddress = new AddressParams
{
Line1 = "123 Main Street",
City = "San Francisco",
State = "CA",
PostalCode = "94105",
Country = "US"
},
Payment = new PaymentParams
{
Method = "card",
PaymentIntentId = "pi_1234567890"
}
});
{
"id": "ord_1a2b3c4d5e6f",
"object": "order",
"order_number": "ORD-2024-001234",
"status": "processing",
"customer": {
"id": "cus_9z8y7x6w5v4u",
"email": "john.doe@example.com",
"first_name": "John",
"last_name": "Doe",
"phone": "+1234567890"
},
"items": [
{
"id": "item_abc123",
"sku": "TSHIRT-BLUE-L",
"quantity": 2,
"price": 1999,
"name": "Blue T-Shirt (Large)",
"total": 3998
},
{
"id": "item_def456",
"sku": "HAT-RED",
"quantity": 1,
"price": 1499,
"name": "Red Baseball Cap",
"total": 1499
}
],
"shipping_address": {
"line1": "123 Main Street",
"line2": "Apt 4B",
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
},
"billing_address": {
"line1": "123 Main Street",
"line2": "Apt 4B",
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
},
"payment": {
"method": "card",
"payment_intent_id": "pi_1234567890",
"status": "paid"
},
"shipping": {
"method": "standard",
"carrier": "ups",
"tracking_number": null,
"estimated_delivery": "2024-01-22T00:00:00Z"
},
"totals": {
"subtotal": 5497,
"tax": 482,
"shipping": 799,
"discount": 0,
"total": 6778
},
"metadata": {
"source": "web",
"campaign": "summer-sale"
},
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"details": {
"items[0].quantity": "Quantity must be a positive integer",
"customer.email": "Invalid email format"
}
}
}
{
"success": false,
"error": {
"code": "INVENTORY_UNAVAILABLE",
"message": "Insufficient inventory for requested items",
"details": {
"unavailable_items": [
{
"sku": "TSHIRT-BLUE-L",
"requested": 2,
"available": 1
}
]
}
}
}
Create Order
Create a new order with automatic inventory allocation and fulfillment workflow initiation
POST
/
v1
/
orders
curl -X POST https://api.stateset.com/v1/orders \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"customer": {
"email": "john.doe@example.com",
"first_name": "John",
"last_name": "Doe",
"phone": "+1234567890"
},
"items": [
{
"sku": "TSHIRT-BLUE-L",
"quantity": 2,
"price": 1999,
"name": "Blue T-Shirt (Large)"
},
{
"sku": "HAT-RED",
"quantity": 1,
"price": 1499,
"name": "Red Baseball Cap"
}
],
"shipping_address": {
"line1": "123 Main Street",
"line2": "Apt 4B",
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
},
"payment": {
"method": "card",
"payment_intent_id": "pi_1234567890"
},
"shipping": {
"method": "standard",
"carrier": "ups"
},
"metadata": {
"source": "web",
"campaign": "summer-sale"
}
}'
mutation CreateOrder($input: OrderCreateInput!) {
orderCreate(input: $input) {
order {
id
orderNumber
status
customer {
email
firstName
lastName
}
items {
sku
quantity
price
total
}
totals {
subtotal
tax
shipping
total
}
createdAt
}
userErrors {
field
message
}
}
}
const order = await stateset.orders.create({
customer: {
email: 'john.doe@example.com',
first_name: 'John',
last_name: 'Doe',
phone: '+1234567890'
},
items: [
{
sku: 'TSHIRT-BLUE-L',
quantity: 2,
price: 1999,
name: 'Blue T-Shirt (Large)'
}
],
shipping_address: {
line1: '123 Main Street',
city: 'San Francisco',
state: 'CA',
postal_code: '94105',
country: 'US'
},
payment: {
method: 'card',
payment_intent_id: 'pi_1234567890'
}
});
order = stateset.orders.create(
customer={
'email': 'john.doe@example.com',
'first_name': 'John',
'last_name': 'Doe',
'phone': '+1234567890'
},
items=[
{
'sku': 'TSHIRT-BLUE-L',
'quantity': 2,
'price': 1999,
'name': 'Blue T-Shirt (Large)'
}
],
shipping_address={
'line1': '123 Main Street',
'city': 'San Francisco',
'state': 'CA',
'postal_code': '94105',
'country': 'US'
},
payment={
'method': 'card',
'payment_intent_id': 'pi_1234567890'
}
)
order = Stateset::Order.create({
customer: {
email: 'john.doe@example.com',
first_name: 'John',
last_name: 'Doe',
phone: '+1234567890'
},
items: [
{
sku: 'TSHIRT-BLUE-L',
quantity: 2,
price: 1999,
name: 'Blue T-Shirt (Large)'
}
],
shipping_address: {
line1: '123 Main Street',
city: 'San Francisco',
state: 'CA',
postal_code: '94105',
country: 'US'
},
payment: {
method: 'card',
payment_intent_id: 'pi_1234567890'
}
})
order, err := stateset.Orders.Create(&stateset.OrderParams{
Customer: &stateset.CustomerParams{
Email: "john.doe@example.com",
FirstName: "John",
LastName: "Doe",
Phone: "+1234567890",
},
Items: []*stateset.OrderItemParams{
{
SKU: "TSHIRT-BLUE-L",
Quantity: 2,
Price: 1999,
Name: "Blue T-Shirt (Large)",
},
},
ShippingAddress: &stateset.AddressParams{
Line1: "123 Main Street",
City: "San Francisco",
State: "CA",
PostalCode: "94105",
Country: "US",
},
Payment: &stateset.PaymentParams{
Method: "card",
PaymentIntentID: "pi_1234567890",
},
})
Map<String, Object> params = new HashMap<>();
params.put("customer", Map.of(
"email", "john.doe@example.com",
"first_name", "John",
"last_name", "Doe",
"phone", "+1234567890"
));
params.put("items", List.of(Map.of(
"sku", "TSHIRT-BLUE-L",
"quantity", 2,
"price", 1999,
"name", "Blue T-Shirt (Large)"
)));
params.put("shipping_address", Map.of(
"line1", "123 Main Street",
"city", "San Francisco",
"state", "CA",
"postal_code", "94105",
"country", "US"
));
params.put("payment", Map.of(
"method", "card",
"payment_intent_id", "pi_1234567890"
));
Order order = stateset.orders().create(params);
$order = $stateset->orders->create([
'customer' => [
'email' => 'john.doe@example.com',
'first_name' => 'John',
'last_name' => 'Doe',
'phone' => '+1234567890',
],
'items' => [
[
'sku' => 'TSHIRT-BLUE-L',
'quantity' => 2,
'price' => 1999,
'name' => 'Blue T-Shirt (Large)',
],
],
'shipping_address' => [
'line1' => '123 Main Street',
'city' => 'San Francisco',
'state' => 'CA',
'postal_code' => '94105',
'country' => 'US',
],
'payment' => [
'method' => 'card',
'payment_intent_id' => 'pi_1234567890',
],
]);
var order = await stateset.Orders.CreateAsync(new OrderCreateParams
{
Customer = new CustomerParams
{
Email = "john.doe@example.com",
FirstName = "John",
LastName = "Doe",
Phone = "+1234567890"
},
Items = new List<OrderItemParams>
{
new OrderItemParams
{
Sku = "TSHIRT-BLUE-L",
Quantity = 2,
Price = 1999,
Name = "Blue T-Shirt (Large)"
}
},
ShippingAddress = new AddressParams
{
Line1 = "123 Main Street",
City = "San Francisco",
State = "CA",
PostalCode = "94105",
Country = "US"
},
Payment = new PaymentParams
{
Method = "card",
PaymentIntentId = "pi_1234567890"
}
});
{
"id": "ord_1a2b3c4d5e6f",
"object": "order",
"order_number": "ORD-2024-001234",
"status": "processing",
"customer": {
"id": "cus_9z8y7x6w5v4u",
"email": "john.doe@example.com",
"first_name": "John",
"last_name": "Doe",
"phone": "+1234567890"
},
"items": [
{
"id": "item_abc123",
"sku": "TSHIRT-BLUE-L",
"quantity": 2,
"price": 1999,
"name": "Blue T-Shirt (Large)",
"total": 3998
},
{
"id": "item_def456",
"sku": "HAT-RED",
"quantity": 1,
"price": 1499,
"name": "Red Baseball Cap",
"total": 1499
}
],
"shipping_address": {
"line1": "123 Main Street",
"line2": "Apt 4B",
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
},
"billing_address": {
"line1": "123 Main Street",
"line2": "Apt 4B",
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
},
"payment": {
"method": "card",
"payment_intent_id": "pi_1234567890",
"status": "paid"
},
"shipping": {
"method": "standard",
"carrier": "ups",
"tracking_number": null,
"estimated_delivery": "2024-01-22T00:00:00Z"
},
"totals": {
"subtotal": 5497,
"tax": 482,
"shipping": 799,
"discount": 0,
"total": 6778
},
"metadata": {
"source": "web",
"campaign": "summer-sale"
},
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"details": {
"items[0].quantity": "Quantity must be a positive integer",
"customer.email": "Invalid email format"
}
}
}
{
"success": false,
"error": {
"code": "INVENTORY_UNAVAILABLE",
"message": "Insufficient inventory for requested items",
"details": {
"unavailable_items": [
{
"sku": "TSHIRT-BLUE-L",
"requested": 2,
"available": 1
}
]
}
}
}
This endpoint creates a new order and automatically triggers order processing workflows, including inventory allocation, payment processing, and fulfillment initiation.
Authentication
This endpoint requires a valid API key withorders:write permissions.
Authorization: Bearer YOUR_API_KEY
Request Body
Customer information for the order
Array of items in the order
Show Item object properties
Show Item object properties
Shipping address for the order
Billing address if different from shipping. If not provided, shipping address will be used.
Show Address properties
Show Address properties
Same structure as shipping_address
Additional custom metadata to store with the order
Unique key to ensure idempotent order creation
Response
Unique identifier for the created order
Always “order” for this object type
Human-readable order number (e.g., “ORD-2024-001234”)
Order status:
pending, processing, shipped, delivered, cancelledCustomer information associated with the order
Array of order items with calculated totals
ISO 8601 timestamp of order creation
ISO 8601 timestamp of last update
curl -X POST https://api.stateset.com/v1/orders \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"customer": {
"email": "john.doe@example.com",
"first_name": "John",
"last_name": "Doe",
"phone": "+1234567890"
},
"items": [
{
"sku": "TSHIRT-BLUE-L",
"quantity": 2,
"price": 1999,
"name": "Blue T-Shirt (Large)"
},
{
"sku": "HAT-RED",
"quantity": 1,
"price": 1499,
"name": "Red Baseball Cap"
}
],
"shipping_address": {
"line1": "123 Main Street",
"line2": "Apt 4B",
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
},
"payment": {
"method": "card",
"payment_intent_id": "pi_1234567890"
},
"shipping": {
"method": "standard",
"carrier": "ups"
},
"metadata": {
"source": "web",
"campaign": "summer-sale"
}
}'
mutation CreateOrder($input: OrderCreateInput!) {
orderCreate(input: $input) {
order {
id
orderNumber
status
customer {
email
firstName
lastName
}
items {
sku
quantity
price
total
}
totals {
subtotal
tax
shipping
total
}
createdAt
}
userErrors {
field
message
}
}
}
const order = await stateset.orders.create({
customer: {
email: 'john.doe@example.com',
first_name: 'John',
last_name: 'Doe',
phone: '+1234567890'
},
items: [
{
sku: 'TSHIRT-BLUE-L',
quantity: 2,
price: 1999,
name: 'Blue T-Shirt (Large)'
}
],
shipping_address: {
line1: '123 Main Street',
city: 'San Francisco',
state: 'CA',
postal_code: '94105',
country: 'US'
},
payment: {
method: 'card',
payment_intent_id: 'pi_1234567890'
}
});
order = stateset.orders.create(
customer={
'email': 'john.doe@example.com',
'first_name': 'John',
'last_name': 'Doe',
'phone': '+1234567890'
},
items=[
{
'sku': 'TSHIRT-BLUE-L',
'quantity': 2,
'price': 1999,
'name': 'Blue T-Shirt (Large)'
}
],
shipping_address={
'line1': '123 Main Street',
'city': 'San Francisco',
'state': 'CA',
'postal_code': '94105',
'country': 'US'
},
payment={
'method': 'card',
'payment_intent_id': 'pi_1234567890'
}
)
order = Stateset::Order.create({
customer: {
email: 'john.doe@example.com',
first_name: 'John',
last_name: 'Doe',
phone: '+1234567890'
},
items: [
{
sku: 'TSHIRT-BLUE-L',
quantity: 2,
price: 1999,
name: 'Blue T-Shirt (Large)'
}
],
shipping_address: {
line1: '123 Main Street',
city: 'San Francisco',
state: 'CA',
postal_code: '94105',
country: 'US'
},
payment: {
method: 'card',
payment_intent_id: 'pi_1234567890'
}
})
order, err := stateset.Orders.Create(&stateset.OrderParams{
Customer: &stateset.CustomerParams{
Email: "john.doe@example.com",
FirstName: "John",
LastName: "Doe",
Phone: "+1234567890",
},
Items: []*stateset.OrderItemParams{
{
SKU: "TSHIRT-BLUE-L",
Quantity: 2,
Price: 1999,
Name: "Blue T-Shirt (Large)",
},
},
ShippingAddress: &stateset.AddressParams{
Line1: "123 Main Street",
City: "San Francisco",
State: "CA",
PostalCode: "94105",
Country: "US",
},
Payment: &stateset.PaymentParams{
Method: "card",
PaymentIntentID: "pi_1234567890",
},
})
Map<String, Object> params = new HashMap<>();
params.put("customer", Map.of(
"email", "john.doe@example.com",
"first_name", "John",
"last_name", "Doe",
"phone", "+1234567890"
));
params.put("items", List.of(Map.of(
"sku", "TSHIRT-BLUE-L",
"quantity", 2,
"price", 1999,
"name", "Blue T-Shirt (Large)"
)));
params.put("shipping_address", Map.of(
"line1", "123 Main Street",
"city", "San Francisco",
"state", "CA",
"postal_code", "94105",
"country", "US"
));
params.put("payment", Map.of(
"method", "card",
"payment_intent_id", "pi_1234567890"
));
Order order = stateset.orders().create(params);
$order = $stateset->orders->create([
'customer' => [
'email' => 'john.doe@example.com',
'first_name' => 'John',
'last_name' => 'Doe',
'phone' => '+1234567890',
],
'items' => [
[
'sku' => 'TSHIRT-BLUE-L',
'quantity' => 2,
'price' => 1999,
'name' => 'Blue T-Shirt (Large)',
],
],
'shipping_address' => [
'line1' => '123 Main Street',
'city' => 'San Francisco',
'state' => 'CA',
'postal_code' => '94105',
'country' => 'US',
],
'payment' => [
'method' => 'card',
'payment_intent_id' => 'pi_1234567890',
],
]);
var order = await stateset.Orders.CreateAsync(new OrderCreateParams
{
Customer = new CustomerParams
{
Email = "john.doe@example.com",
FirstName = "John",
LastName = "Doe",
Phone = "+1234567890"
},
Items = new List<OrderItemParams>
{
new OrderItemParams
{
Sku = "TSHIRT-BLUE-L",
Quantity = 2,
Price = 1999,
Name = "Blue T-Shirt (Large)"
}
},
ShippingAddress = new AddressParams
{
Line1 = "123 Main Street",
City = "San Francisco",
State = "CA",
PostalCode = "94105",
Country = "US"
},
Payment = new PaymentParams
{
Method = "card",
PaymentIntentId = "pi_1234567890"
}
});
{
"id": "ord_1a2b3c4d5e6f",
"object": "order",
"order_number": "ORD-2024-001234",
"status": "processing",
"customer": {
"id": "cus_9z8y7x6w5v4u",
"email": "john.doe@example.com",
"first_name": "John",
"last_name": "Doe",
"phone": "+1234567890"
},
"items": [
{
"id": "item_abc123",
"sku": "TSHIRT-BLUE-L",
"quantity": 2,
"price": 1999,
"name": "Blue T-Shirt (Large)",
"total": 3998
},
{
"id": "item_def456",
"sku": "HAT-RED",
"quantity": 1,
"price": 1499,
"name": "Red Baseball Cap",
"total": 1499
}
],
"shipping_address": {
"line1": "123 Main Street",
"line2": "Apt 4B",
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
},
"billing_address": {
"line1": "123 Main Street",
"line2": "Apt 4B",
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
},
"payment": {
"method": "card",
"payment_intent_id": "pi_1234567890",
"status": "paid"
},
"shipping": {
"method": "standard",
"carrier": "ups",
"tracking_number": null,
"estimated_delivery": "2024-01-22T00:00:00Z"
},
"totals": {
"subtotal": 5497,
"tax": 482,
"shipping": 799,
"discount": 0,
"total": 6778
},
"metadata": {
"source": "web",
"campaign": "summer-sale"
},
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"details": {
"items[0].quantity": "Quantity must be a positive integer",
"customer.email": "Invalid email format"
}
}
}
{
"success": false,
"error": {
"code": "INVENTORY_UNAVAILABLE",
"message": "Insufficient inventory for requested items",
"details": {
"unavailable_items": [
{
"sku": "TSHIRT-BLUE-L",
"requested": 2,
"available": 1
}
]
}
}
}
⌘I