Themes built on the Twig templating engine are now deprecated and require migration to Vitrin to ensure continued support and compatibility with Zid.
Cart
This page documents the new Vitrin cart functions and, under each item, shows the old Zid function it replaces.
window.zid.cart.Fetch Cart
zid.cart.get()Old:
zid.store.cart.fetch()Add Product
zid.cart.addProduct(payload)Old:
zid.store.cart.addProduct({ productId, quantity, ... })Parameters
product_id (required) — Product identifier.quantity (required) — Number of units (> 0).custom_fields (optional) — Array of selected customizations (only send if the product has options like size, color, add-ons, or extra inputs).Custom Fields — Detailed Explanation
custom_fields parameter allows you to send product customizations (e.g., size, color, engraving text, file uploads) to the backend. It is an optional array, and each entry represents one selected option or filled input.Structure of Each Field
{
price_settings: string | null; // unique ID linking the choice to backend pricing/variants
group_name: string | null; // label of the group (e.g., "Color", "Add-ons")
group_id: string | null; // unique group identifier
name: string | null; // field/option label or name
value: string | null; // user’s input or selected option
type: 'CHECKBOX' | 'DROPDOWN' | 'TEXT' | 'NUMBER' | 'FILE' | 'IMAGE' | 'TEXTAREA';
}Note: custom_fieldsare optional. Only include them if the product has custom options.
Option Fields — Checkboxes
{
"price_settings": "5dd00588-2d18-4613-a991-3e23522b1052",
"group_name": "Extras",
"group_id": "4fba4318-e399-4343-ba5f-e70728b419c5",
"name": "Gift Wrap",
"value": "✔",
"type": "CHECKBOX"
}Option Fields — Dropdowns
{
"price_settings": "64c73acb-9d8f-4f1c-afdb-a175bf50ac53",
"group_name": "Color",
"group_id": "bc9b1ba1-3b83-4edd-bb36-1dbf9ca9aaac",
"name": "Red",
"value": "✔",
"type": "DROPDOWN"
}How the Backend Uses custom_fields
1.
price_settings IDs to apply extra charges (e.g., engraving +120 SAR, image upload +150 SAR, color red +234 SAR → total +504 SAR).2.
3.
4.
Key Point: price_settingsis the unique identifier that connects each customization in the cart to backend pricing and inventory logic.
Update Product
zid.cart.updateProduct({ product_id, quantity })Old:
zid.store.cart.updateProduct(cart_product_id, quantity, product_id)id field from cart_response.products[index].id.Remove Product
zid.cart.removeProduct({ product_id })Old:
zid.store.cart.removeProduct(cart_product_id, product_id)cart_response.products[index].id).Apply Coupon
zid.cart.applyCoupon({ coupon_code })Old:
zid.store.cart.redeemCoupon(coupon_code)Remove Coupon
zid.cart.removeCoupons()Old:
zid.store.cart.removeCoupon()Empty / Remove Cart
zid.cart.empty() – remove all items (keep cart session)zid.cart.remove() – delete cart session entirelyzid.store.cart.removeProducts(with_cart_delete)Add Gift Card
zid.cart.addGiftCard(payload)Parameters
receiver_name (required) — Name of the gift card recipient.sender_name (required) — Name of the person sending the gift card.media_link (optional) — URL to an image or media associated with the gift card.gift_message (optional) — Personal message to include with the gift card.card_design (optional) — Design template url from the store settings.Remove Gift Card
zid.cart.removeGiftCard()Get Calculated Points
zid.cart.getCalculatedPoints(cartTotal)Parameters
cartTotal (required) — The cart total amount as a number.Get Redemption Methods
zid.cart.getRedemptionMethods(currency)Parameters
currency (optional) — Currency code (default: 'SAR').Get Wallet Points Info
zid.cart.getWalletPointsInfo()Add Redemption Method
zid.cart.addRedemptionMethod({ id: 'redemption_method_123' })Parameters
id (required) — The redemption method identifier.Remove Redemption Method
zid.cart.removeRedemptionMethod()Get Customer Loyalty Points
zid.cart.getCustomerLoyaltyPoints()Notes & Differences
id (cart product id) replaces cart_product_id for update/remove operations.redeemCoupon → applyCoupon and removeCoupon → removeCoupons.empty() vs remove() for different clearing behaviors.For product/variant selection rules and complex products, see the Products page.
Modified at 2025-10-20 14:36:11