Customer Cart Object Schema

Chi tiết các trường dữ liệu của một object `CustomerCart` (cart + quote).

Customer Cart Object Schema

Đây là cấu trúc dữ liệu chuẩn của một giỏ hàng khách hàng. Tùy API/bối cảnh, object có thể được enrich thêm các trường như details, promotionengine, price_quote, loyalty, ...

Fields (cơ bản)

Trường	Kiểu	Mô tả
`id`	`integer`	ID giỏ hàng.
`uuid`	`string`	UUID giỏ hàng (dùng trong path param).
`company_id`	`integer`	Tenant/company id.
`customer_id`	`integer`	ID khách hàng (0 nếu guest).
`source`	`integer`	Nguồn tạo cart (website/app/mini app...).
`source_name`	`string`	Tên nguồn (nếu có).
`external_id`	`string`	ID ngoài hệ thống (nếu có).
`store_id`	`integer`	Store xử lý đơn hàng.
`pickup_store_id`	`integer`	Store pickup (nếu `shipping_type = pickup`).
`shipping_type`	`string`	Kiểu giao hàng: `delivery` / `pickup` / `instore`.
`shipping_address_id`	`integer`	ID địa chỉ giao hàng (nếu dùng address book).
`shipping_full_name`	`string`	Tên người nhận.
`shipping_phone`	`string`	SĐT người nhận.
`shipping_email`	`string`	Email người nhận.
`shipping_address`	`string`	Địa chỉ giao hàng.
`shipping_region_id`	`integer`	Tỉnh/Thành phố.
`shipping_sub_region_id`	`integer`	Quận/Huyện.
`shipping_sub_sub_region_id`	`integer`	Phường/Xã.
`shipping_address_line_2`	`string`	Địa chỉ dòng 2 (nếu có).
`shipping_instruction`	`string`	Ghi chú giao hàng.
`shipping_legacy_province_name`	`string`	Tên tỉnh (legacy text).
`shipping_legacy_district_name`	`string`	Tên quận/huyện (legacy text).
`shipping_legacy_ward_name`	`string`	Tên phường/xã (legacy text).
`shipping_carrier_id`	`integer`	ID đơn vị vận chuyển (nếu có).
`warehouse_id`	`integer`	ID kho (nếu có).
`billing_full_name`	`string`	Tên người mua (billing).
`billing_phone`	`string`	SĐT người mua (billing).
`billing_email`	`string`	Email người mua (billing).
`billing_address`	`string`	Địa chỉ người mua (billing).
`billing_region_id`	`integer`	Tỉnh/Thành phố (billing).
`billing_sub_region_id`	`integer`	Quận/Huyện (billing).
`billing_sub_sub_region_id`	`integer`	Phường/Xã (billing).
`birthday`	`string`	Ngày sinh (nếu thu thập).
`gender`	`integer`	Giới tính.
`payment_method`	`integer`	Phương thức thanh toán (mapping theo Order).
`payment_status`	`integer`	Trạng thái thanh toán (mapping theo Order).
`note`	`string`	Ghi chú đơn hàng.
`coupon_code`	`string`	Mã coupon (nếu có).
`tax_name`	`string`	Tên xuất hóa đơn.
`tax_is_company`	`integer`	1 nếu là công ty, 0 nếu cá nhân.
`tax_code`	`string`	Mã số thuế.
`tax_address`	`string`	Địa chỉ xuất hóa đơn.
`tax_email`	`string`	Email nhận hóa đơn.
`data`	`array`	Dữ liệu item thô lưu DB (trước khi enrich).
`count_item`	`integer`	Tổng số lượng item (theo cart stats).
`redeem_points`	`integer`	Số điểm yêu cầu quy đổi (loyalty).
`price_sell`	`integer`	Tổng tiền hàng (sau price/promotion engine).
`price_shipping`	`integer`	Phí ship hiện tại.
`price_shipping_original`	`integer`	Phí ship gốc (trước khuyến mãi).
`price_discount_order`	`integer`	Giảm giá cấp đơn hàng.
`price_discount_shipping`	`integer`	Giảm giá phí ship.
`price_discount_coupon`	`integer`	Giảm giá từ coupon.
`price_discount_loyalty`	`integer`	Giảm giá từ quy đổi điểm.
`price_discount_giftcard`	`integer`	Giảm giá từ giftcard (nếu có).
`price_discount`	`integer`	Tổng giảm giá (cộng các loại discount).
`price_final`	`integer`	Tổng thanh toán cuối cùng.
`sale_order_id`	`integer`	ID order tạo ra từ checkout (nếu đã checkout).
`status`	`integer`	Trạng thái cart.
`ip_address`	`string`	IP tạo cart (phục vụ anti-spam).
`date_created`	`integer`	Unix timestamp tạo cart.
`date_modified`	`integer`	Unix timestamp cập nhật.
`date_last_accessed`	`integer`	Unix timestamp truy cập gần nhất.
`date_finished`	`integer`	Unix timestamp hoàn tất (khi checkout).

Fields (enriched in quote/checkout)

Các API như getQuote, getLastQuote thường trả về thêm các field sau (không phải lúc nào cũng có trong DB gốc):

Trường	Kiểu	Mô tả
`details`	`array`	Danh sách item đã enrich (tên, ảnh, option, giá theo policy, promotionengine...).
`total_item`	`integer`	Tổng số item (tính từ details).
`total_weight`	`integer`	Tổng khối lượng (gram) hoặc tổng cân nặng quy đổi.
`active_price_policy_id`	`integer`	Policy giá đang áp dụng (customer/customer type/website).
`website_price_policy_id`	`integer`	Policy giá mặc định website (để so sánh).
`invalid_items`	`array`	Item không hợp lệ bị loại khỏi quote.
`invalid_items_explain`	`object`	Thông tin giải thích item invalid.
`bundles_map`	`object`	Map bundle identifier → snapshot/metadata bundle promotion.
`promotionengine`	`object`	Quyết định khuyến mãi cấp cart (order/shipping/coupon).
`price_quote`	`object`	Thông tin quote (payload/hash/expired) để đối chiếu khi checkout.
`context`	`object`	Context dùng để evaluate (shipping/payment/coupon/source...).
`loyalty`	`object`	Kết quả loyalty redeem evaluate (hoặc `warning`).

Field Value Mappings

`source`

Value	Constant	Mô tả
`1`	`SOURCE_POS`	POS.
`3`	`SOURCE_WEBSITE`	Website.
`5`	`SOURCE_MOBILE_APP`	Mobile app.
`7`	`SOURCE_MINI_APP`	Mini app.
`9`	`SOURCE_ZALO`	Zalo.
`11`	`SOURCE_SHOPEE`	Shopee.
`13`	`SOURCE_LAZADA`	Lazada.
`15`	`SOURCE_TIKTOK`	TikTok.
`17`	`SOURCE_TIKI`	Tiki.
`19`	`SOURCE_FACEBOOK`	Facebook.
`21`	`SOURCE_INSTAGRAM`	Instagram.
`23`	`SOURCE_OFFLINE_EVENT`	Offline event.
`25`	`SOURCE_TELEGRAM`	Telegram.
`27`	`SOURCE_SELF_CHECKOUT`	Self checkout.
`29`	`SOURCE_REFERRAL`	Referral.
`95`	`SOURCE_API`	API.
`97`	`SOURCE_CUSTOM`	Custom.
`99`	`SOURCE_OTHER`	Other.

`shipping_type`

Lưu trong CustomerCart là dạng string. Khi chuyển sang Order, hệ thống map sang numeric shipping type.

Value	Mô tả
`delivery`	Giao hàng tận nơi.
`pickup`	Khách nhận tại cửa hàng.
`instore`	Mua tại cửa hàng (in-store).

`payment_method`

Value	Constant	Mô tả
`1`	`PAYMENT_METHOD_CASH`	Tiền mặt.
`3`	`PAYMENT_METHOD_ONLINE_BANKING`	Chuyển khoản / Online banking.
`5`	`PAYMENT_METHOD_GIFTCARD`	Giftcard.
`7`	`PAYMENT_METHOD_CUSTOMER_POINT`	Điểm khách hàng.
`9`	`PAYMENT_METHOD_CARD`	Thẻ (card).
`11`	`PAYMENT_METHOD_COD`	COD.
`13`	`PAYMENT_METHOD_MOMO`	MoMo.
`14`	`PAYMENT_METHOD_VNPAY_QR`	VNPAY QR.
`15`	`PAYMENT_METHOD_VNPAY`	VNPAY.
`16`	`PAYMENT_METHOD_VNPAY_SMARTPOS`	VNPAY SmartPOS.
`17`	`PAYMENT_METHOD_MEMBERCARD`	Member card.
`19`	`PAYMENT_METHOD_SEPAY`	SePay.
`20`	`PAYMENT_METHOD_SEPAY_GATEWAY`	SePay Gateway.
`21`	`PAYMENT_METHOD_ZALOPAY`	ZaloPay.
`23`	`PAYMENT_METHOD_CASAFLOW_SMARTPOS`	CasaFlow SmartPOS.
`25`	`PAYMENT_METHOD_VIETQR`	VietQR.

`payment_status`

Value	Constant	Mô tả
`1`	`PAYMENT_STATUS_PENDING`	Pending.
`3`	`PAYMENT_STATUS_AWAITING_FROM_CUSTOMER`	Awaiting from customer.
`5`	`PAYMENT_STATUS_AWAITING_FROM_PARTNER`	Awaiting from partner.
`7`	`PAYMENT_STATUS_CHECKING_WITH_PARTNER`	Checking with partner.
`9`	`PAYMENT_STATUS_COMPLETED`	Completed.
`11`	`PAYMENT_STATUS_AWAITING_REFUND_TO_CUSTOMER`	Awaiting refund to customer.
`13`	`PAYMENT_STATUS_AWAITING_REFUND_TO_PARTNER`	Awaiting refund to partner.
`15`	`PAYMENT_STATUS_REFUNDED_TO_CUSTOMER`	Refunded to customer.
`17`	`PAYMENT_STATUS_REFUNDED_TO_PARTNER`	Refunded to partner.
`19`	`PAYMENT_STATUS_CANCELLED`	Cancelled.
`21`	`PAYMENT_STATUS_FAILED`	Failed.
`23`	`PAYMENT_STATUS_EXPIRED`	Expired.

Status Constants

Value	Constant	Mô tả
`1`	`STATUS_ACTIVE`	Giỏ hàng đang hoạt động.
`3`	`STATUS_ABANDON`	Giỏ hàng bị bỏ dở.
`5`	`STATUS_FINISH`	Giỏ hàng đã checkout và kết thúc.

Customer Cart Object Schema

Customer Cart Object SchemaCopy Anchor Link

Fields (cơ bản)Copy Anchor Link

Fields (enriched in quote/checkout)Copy Anchor Link

Field Value MappingsCopy Anchor Link

sourceCopy Anchor Link

shipping_typeCopy Anchor Link

payment_methodCopy Anchor Link

payment_statusCopy Anchor Link

Status ConstantsCopy Anchor Link

On this page

Customer Cart Object Schema

Fields (cơ bản)

Fields (enriched in quote/checkout)

Field Value Mappings

`source`

`shipping_type`

`payment_method`

`payment_status`

Status Constants