Overview The Carts API allows you to create and manage shopping carts for point-of-sale transactions. Carts track items being purchased, calculate totals, apply discounts, and record payment information. Each cart can be associated with a user (client) or remain anonymous for walk-in customers.
Cart Lifecycle Carts progress through the following statuses:
pending - Cart is active and items can be added/modifiedcompleted - Transaction has been finalized and payment receivedcancelled - Cart was abandoned or transaction cancelled
Endpoints List Carts Retrieve all carts with optional filtering by status.
Query Parameters Filter carts by status: pending, completed, or cancelled
Response Returns an array of cart objects ordered by creation date (newest first).
Unique identifier for the cart (UUID)
ID of the associated user/client. Null for anonymous carts
User information if cart is associated with a client Current cart status: pending, completed, or cancelled
Sum of all item prices before discounts
Total discount amount applied to the cart
Final amount after discounts (subtotal - discount)
Payment method used: cash, card, transfer, or mixed
Additional notes or comments about the transaction
Coupon code applied during checkout
Gift card code used for payment
Array of cart items (see CartItem schema)
Associated debt records if payment is incomplete
ISO 8601 timestamp when cart was created
ISO 8601 timestamp when cart was last updated
Example Request curl -X GET 'https://api.beils.com/api/sales/carts?status=pending' \ -H 'Authorization: Bearer YOUR_TOKEN'
Example Response [ { "cart_id" : "550e8400-e29b-41d4-a716-446655440000" , "user_id" : "123e4567-e89b-12d3-a456-426614174000" , "user" : { "name" : "Maria" , "surname" : "Garcia" , "email" : "[email protected] " }, "status" : "pending" , "subtotal" : 150.00 , "discount" : 15.00 , "total" : 135.00 , "payment_method" : "card" , "notes" : null , "applied_coupon" : "SUMMER10" , "applied_giftcard" : null , "items" : [ { "cart_item_id" : "660e8400-e29b-41d4-a716-446655440001" , "item_type" : "service" , "item_id" : "770e8400-e29b-41d4-a716-446655440002" , "name" : "Facial Treatment" , "quantity" : 1 , "unit_price" : 80.00 , "tax_rate" : 21.0 , "subtotal" : 80.00 , "total" : 80.00 }, { "cart_item_id" : "660e8400-e29b-41d4-a716-446655440003" , "item_type" : "product" , "item_id" : "770e8400-e29b-41d4-a716-446655440004" , "name" : "Moisturizing Cream" , "quantity" : 1 , "unit_price" : 70.00 , "tax_rate" : 21.0 , "subtotal" : 70.00 , "total" : 70.00 } ], "debts" : [], "created_at" : "2026-03-05T10:30:00Z" , "updated_at" : "2026-03-05T10:30:00Z" } ]
Create Cart Create a new shopping cart with items.
Request Body ID of the client. Omit for anonymous walk-in customers
Initial cart status: pending, completed, or cancelled
Payment method: cash, card, transfer, or mixed
Manual discount amount to apply
Additional notes about the transaction
Coupon code to apply (stores code for history)
Gift card code used (stores code for history)
Array of items to add to the cart Type of item: product, service, pack, bonus, or giftcard
ID of the item being sold
Name of the item (snapshot at time of sale)
Transaction Safety : Cart creation uses database transactions to ensure data consistency. The subtotal and total are automatically calculated from items to prevent client-side tampering.
Example Request curl -X POST 'https://api.beils.com/api/sales/carts' \ -H 'Authorization: Bearer YOUR_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "user_id": "123e4567-e89b-12d3-a456-426614174000", "status": "pending", "payment_method": "card", "discount": 10.00, "applied_coupon": "WELCOME10", "items": [ { "item_type": "service", "item_id": "770e8400-e29b-41d4-a716-446655440002", "name": "Manicure", "quantity": 1, "unit_price": 35.00, "tax_rate": 21.0 }, { "item_type": "product", "item_id": "770e8400-e29b-41d4-a716-446655440005", "name": "Nail Polish", "quantity": 2, "unit_price": 12.00, "tax_rate": 21.0 } ] }'
Example Response { "cart_id" : "550e8400-e29b-41d4-a716-446655440000" , "user_id" : "123e4567-e89b-12d3-a456-426614174000" , "status" : "pending" , "subtotal" : 59.00 , "discount" : 10.00 , "total" : 49.00 , "payment_method" : "card" , "notes" : null , "applied_coupon" : "WELCOME10" , "applied_giftcard" : null , "items" : [ { "cart_item_id" : "660e8400-e29b-41d4-a716-446655440001" , "cart_id" : "550e8400-e29b-41d4-a716-446655440000" , "item_type" : "service" , "item_id" : "770e8400-e29b-41d4-a716-446655440002" , "name" : "Manicure" , "quantity" : 1 , "unit_price" : 35.00 , "tax_rate" : 21.0 , "subtotal" : 35.00 , "total" : 35.00 , "created_at" : "2026-03-05T11:00:00Z" , "updated_at" : "2026-03-05T11:00:00Z" }, { "cart_item_id" : "660e8400-e29b-41d4-a716-446655440003" , "cart_id" : "550e8400-e29b-41d4-a716-446655440000" , "item_type" : "product" , "item_id" : "770e8400-e29b-41d4-a716-446655440005" , "name" : "Nail Polish" , "quantity" : 2 , "unit_price" : 12.00 , "tax_rate" : 21.0 , "subtotal" : 24.00 , "total" : 24.00 , "created_at" : "2026-03-05T11:00:00Z" , "updated_at" : "2026-03-05T11:00:00Z" } ], "user" : { "name" : "Maria" , "surname" : "Garcia" }, "created_at" : "2026-03-05T11:00:00Z" , "updated_at" : "2026-03-05T11:00:00Z" }
Get Cart Retrieve a specific cart by ID with full details.
GET /api/sales/carts/{cart_id}
Path Parameters The unique identifier of the cart
Response Returns a cart object with complete user and item information.
Example Request curl -X GET 'https://api.beils.com/api/sales/carts/550e8400-e29b-41d4-a716-446655440000' \ -H 'Authorization: Bearer YOUR_TOKEN'
Example Response { "cart_id" : "550e8400-e29b-41d4-a716-446655440000" , "user_id" : "123e4567-e89b-12d3-a456-426614174000" , "user" : { "name" : "Maria" , "surname" : "Garcia" , "email" : "[email protected] " , "phone" : "+34612345678" }, "status" : "completed" , "subtotal" : 120.00 , "discount" : 12.00 , "total" : 108.00 , "payment_method" : "card" , "notes" : "Client requested receipt" , "applied_coupon" : "LOYAL10" , "applied_giftcard" : null , "items" : [ { "cart_item_id" : "660e8400-e29b-41d4-a716-446655440001" , "item_type" : "service" , "item_id" : "770e8400-e29b-41d4-a716-446655440002" , "name" : "Hair Cut" , "quantity" : 1 , "unit_price" : 45.00 , "tax_rate" : 21.0 , "subtotal" : 45.00 , "total" : 45.00 }, { "cart_item_id" : "660e8400-e29b-41d4-a716-446655440002" , "item_type" : "service" , "item_id" : "770e8400-e29b-41d4-a716-446655440003" , "name" : "Hair Coloring" , "quantity" : 1 , "unit_price" : 75.00 , "tax_rate" : 21.0 , "subtotal" : 75.00 , "total" : 75.00 } ], "debts" : [], "created_at" : "2026-03-05T09:00:00Z" , "updated_at" : "2026-03-05T11:30:00Z" }
Update Cart Update cart status, payment method, or notes. The cart itself is immutable after creation, but these metadata fields can be updated.
PUT /api/sales/carts/{cart_id}
Path Parameters The unique identifier of the cart
Request Body Update cart status: pending, completed, or cancelled
Update payment method: cash, card, transfer, or mixed
Once a cart is created, items cannot be modified through this endpoint. To change items, create a new cart. This ensures transaction integrity.
Example Request curl -X PUT 'https://api.beils.com/api/sales/carts/550e8400-e29b-41d4-a716-446655440000' \ -H 'Authorization: Bearer YOUR_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "status": "completed", "payment_method": "card", "notes": "Payment confirmed" }'
Example Response { "cart_id" : "550e8400-e29b-41d4-a716-446655440000" , "user_id" : "123e4567-e89b-12d3-a456-426614174000" , "status" : "completed" , "subtotal" : 120.00 , "discount" : 12.00 , "total" : 108.00 , "payment_method" : "card" , "notes" : "Payment confirmed" , "applied_coupon" : "LOYAL10" , "applied_giftcard" : null , "created_at" : "2026-03-05T09:00:00Z" , "updated_at" : "2026-03-05T11:35:00Z" }
Delete Cart Delete a cart permanently. This will cascade delete all cart items.
DELETE /api/sales/carts/{cart_id}
Path Parameters The unique identifier of the cart
Deleting a cart removes all associated cart items due to cascade delete. Associated debts will have their cart reference set to null rather than being deleted.
Example Request curl -X DELETE 'https://api.beils.com/api/sales/carts/550e8400-e29b-41d4-a716-446655440000' \ -H 'Authorization: Bearer YOUR_TOKEN'
Example Response Common Use Cases Processing a Walk-in Sale For customers without an account:
curl -X POST 'https://api.beils.com/api/sales/carts' \ -H 'Authorization: Bearer YOUR_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "status": "completed", "payment_method": "cash", "items": [ { "item_type": "product", "item_id": "prod-123", "name": "Shampoo", "quantity": 1, "unit_price": 15.00, "tax_rate": 21.0 } ] }'
Applying Multiple Discounts Combine coupon codes and manual discounts:
curl -X POST 'https://api.beils.com/api/sales/carts' \ -H 'Authorization: Bearer YOUR_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "user_id": "user-123", "discount": 25.00, "applied_coupon": "VIP20", "applied_giftcard": "GIFT50", "payment_method": "mixed", "items": [...] }'
Tracking Daily Sales Filter completed carts for reporting:
curl -X GET 'https://api.beils.com/api/sales/carts?status=completed' \ -H 'Authorization: Bearer YOUR_TOKEN'
Error Responses Cart Not Found { "statusCode" : 404 , "statusMessage" : "Cart not found" }
Missing Cart ID { "statusCode" : 400 , "statusMessage" : "Cart ID is required" }
Debts Manage customer payment debts and installments
Coupons Create and manage discount coupons
Gift Cards Issue and redeem gift cards
Clients Manage customer information
