Skip to content

cart ​

购物车

概述 ​

k.commerce.cart 提供购物车相关操作,支持创建购物车、添加商品、更新配送方式、使用优惠券等功能。

Cart 数据结构 ​

ts
interface Cart {
    id: string;              // 购物车ID
    customerId: string;      // 顾客ID
    contact: string;         // 联系邮箱
    country: string;         // 国家
    discountCodes: string[]; // 优惠券代码
    note: string;            // 备注
    lines: CartItem[];       // 购物车商品
    shippingId: string;      // 配送方式ID
    digitalShippingId: string; // 数字配送方式ID
    insuranceAmount: number; // 保险金额
    extensionButton: { text: string; url: string } | null; // 扩展按钮
    redeemPoints: boolean;   // 是否使用积分
    createdAt: Date;         // 创建时间
    updatedAt: Date;         // 更新时间
}

CartDetail 数据结构 ​

ts
interface CartDetail {
    id: string;
    customerId: string;
    contact: string;
    country: string;
    currency: { code: string; symbol: string; rate: number }; // 货币信息
    discountCodes: string[];
    activeDiscountCodes: string[]; // 激活的优惠券代码
    note: string;
    discountAllocations: DiscountAllocation[]; // 自动折扣信息
    shippingAllocations: ShippingAllocation[]; // 配送方式
    shippingAmount: number;       // 配送金额
    insuranceAmount: number;      // 保险金额
    subtotalAmount: number;       // 小计金额
    totalAmount: number;          // 总金额
    taxAmount: number;            // 税额
    totalQuantity: number;        // 总数量
    redeemPoints: number;         // 积分
    pointsDeductionAmount: number; // 积分抵扣金额
    earnPoints: number;          // 获取积分数额
    shipping: Shipping | null;   // 配送方式
    lines: CartItem[];           // 购物车商品
}

CartItem 数据结构 ​

ts
interface CartItem {
    variantId: string;            // 商品规格ID
    productId: string;             // 商品ID
    title: string;                // 商品名称
    options: Option[];            // 商品选项
    sku: string;                  // 商品SKU
    image: string;                // 商品图片
    originalPrice: number;        // 商品原价
    price: number;                // 商品价格
    discountAllocations: DiscountAllocation[]; // 自动折扣信息
    quantity: number;             // 商品数量
    totalQuantity: number;        // 商品总数量
    amount: number;               // 商品小计金额
    taxAmount: number;            // 商品税额
    inventory: number;             // 商品库存
    groupName: string;            // 商品组名
    isMain: boolean;              // 是否为主商品
    note: string;                 // 商品备注
}

ShippingAllocation 数据结构 ​

ts
interface ShippingAllocation {
    cost: number;     // 配送费用
    title: string;    // 配送方式名称
    isAddtional: boolean; // 是否为附加运费
}

create() ​

创建购物车。

ts
k.api.post(() => {
    const cartId = k.commerce.cart.create({
        extensionButton: { text: '测试', url: '/test' },
        insuranceAmount: 100
    })
    return { cartId }
})

参数:

参数类型必填说明
optionsobject否可选参数
options.extensionButton{ text: string, url: string }否扩展按钮
options.insuranceAmountnumber否保险金额

返回: string - 购物车ID

get() ​

获取购物车信息。

ts
k.api.get(() => {
    return k.commerce.cart.get(cartId)
})

参数:

参数类型必填说明
cartIdstring是购物车ID

返回: Cart

getDetail() ​

获取购物车详情(包含金额计算)。

ts
k.api.get(() => {
    return k.commerce.cart.getDetail(cartId, {
        country: '中国',
        province: '广东省',
        city: '广州市'
    })
})

参数:

参数类型必填说明
cartIdstring是购物车ID
optionsobject否可选参数
options.countrystring否国家
options.provincestring否省份
options.citystring否城市

返回: CartDetail

addOrUpdateLine() ​

添加或更新购物车商品。

ts
k.api.post(() => {
    const product = k.commerce.product.get('test-product')
    const variantId = product.variants[0].id

    k.commerce.cart.addOrUpdateLine(cartId, variantId, 2, {
        note: 'test line',
        groupName: '捆绑组1',
        isMain: true
    })
    return 'success'
})

参数:

参数类型必填说明
cartIdstring是购物车ID
variantIdstring是商品变体ID
quantitynumber是数量
optionsobject否可选参数
options.notestring否备注
options.groupNamestring否捆绑产品组名(具有相同 groupName 的 line 将变成捆绑产品)
options.isMainboolean否是否作为捆绑产品中的主产品
options.extensionButton{ text: string, url: string }否扩展按钮

返回: void

removeLine() ​

删除购物车商品。

ts
k.api.post(() => {
    const product = k.commerce.product.get('test-product')
    const variantId = product.variants[0].id

    k.commerce.cart.removeLine(cartId, variantId)
    return 'success'
})

参数:

参数类型必填说明
cartIdstring是购物车ID
variantIdstring是商品变体ID
groupNamestring否捆绑产品组名

返回: void

updateAdditional() ​

更新购物车附加信息。

ts
k.api.post(() => {
    k.commerce.cart.updateAdditional(cartId, {
        redeemPoints: true,
        extensionButton: { text: '测试', url: '/test' },
        insuranceAmount: 100
    })
    return 'success'
})

参数:

参数类型必填说明
cartIdstring是购物车ID
optionsobject是更新内容
options.redeemPointsboolean否是否使用积分
options.extensionButton{ text: string, url: string }否扩展按钮
options.insuranceAmountnumber否保险金额

返回: void

updateContact() ​

更新购物车顾客联系信息。

ts
k.api.post(() => {
    k.commerce.cart.updateContact(cartId, 'test@test.com')
    return 'success'
})

注意

如果 email 在 customer 中存在,会自动绑定 customerId;否则仅填入 email

参数:

参数类型必填说明
cartIdstring是购物车ID
emailstring是联系邮箱

返回: void

updateDigitalShipping() ​

更新数字配送方式。

ts
k.api.post(() => {
    k.commerce.cart.updateDigitalShipping(cartId, shippingId)
    return 'success'
})

参数:

参数类型必填说明
cartIdstring是购物车ID
shippingIdstring是数字配送方式ID

返回: void

updateDiscountCodes() ​

更新购物车优惠券代码。

ts
k.api.post(() => {
    const discount = k.commerce.discount.list()[0]
    k.commerce.cart.updateDiscountCodes(cartId, [discount.code])
    return 'success'
})

参数:

参数类型必填说明
cartIdstring是购物车ID
discountCodesstring[]是优惠券代码数组

返回: void

updateShipping() ​

更新购物车配送方式。

ts
k.api.post(() => {
    k.commerce.cart.updateShipping(cartId, shippingId)
    return 'success'
})

参数:

参数类型必填说明
cartIdstring是购物车ID
shippingIdstring是配送方式ID

返回: void

结构 ​

Cart 属性 ​

属性说明类型
id购物车IDstring
customerId顾客IDstring
contact联系邮箱string
country国家string
discountCodes优惠券代码string[]
note备注string
lines购物车商品CartItem[]
shippingId配送方式IDstring
digitalShippingId数字配送方式IDstring
insuranceAmount保险金额number
extensionButton扩展按钮{ text: string, url: string } | null
redeemPoints是否使用积分boolean
createdAt创建时间Date
updatedAt更新时间Date

CartDetail 属性 ​

属性说明类型
id购物车IDstring
customerId顾客IDstring
contact联系邮箱string
country国家string
currency货币信息{ code: string, symbol: string, rate: number }
discountCodes优惠券代码string[]
activeDiscountCodes激活的优惠券代码string[]
note备注string
discountAllocations自动折扣信息DiscountAllocation[]
shippingAllocations配送方式列表ShippingAllocation[]
shippingAmount配送金额number
insuranceAmount保险金额number
subtotalAmount小计金额number
totalAmount总金额number
taxAmount税额number
totalQuantity总数量number
redeemPoints积分number
pointsDeductionAmount积分抵扣金额number
earnPoints获取积分数额number
shipping配送方式Shipping | null
lines购物车商品CartItem[]

CartItem 属性 ​

属性说明类型
variantId商品规格IDstring
productId商品IDstring
title商品名称string
options商品选项{ name: string, value: string }[]
sku商品SKUstring
image商品图片string
originalPrice商品原价number
price商品价格number
discountAllocations自动折扣信息DiscountAllocation[]
quantity商品数量number
totalQuantity商品总数量number
amount商品小计金额number
taxAmount商品税额number
inventory商品库存number
groupName商品组名string
isMain是否为主商品boolean
note商品备注string

ShippingAllocation 属性 ​

属性说明类型
cost配送费用number
title配送方式名称string
isAdditional是否为附加运费boolean

相关文档 ​