# Cart Object

## Overview

The Cart object provides advanced control over the checkout process, allowing you to dynamically manage customer details, product information, and billing data before proceeding to checkout.

## Tutorials

For a step-by-step integration, see [Drop-in Checkout with Chargebee.js](https://www.chargebee.com/tutorials/drop-in-checkout/).

## Prerequisites

Before using the Cart object, ensure you have:

- [Initialized Chargebee.js](https://www.chargebee.com/docs/js/settingup-api-ref) in your application.
- [Created a product object](https://www.chargebee.com/docs/js/product-api-ref) to add to the cart.

## Create the Cart Object

To retrieve the Cart object, use the [`getCart()`](https://www.chargebee.com/docs/js/cbinstanceobj-api-ref#getcart) method:

```js
const chargebee = Chargebee.getInstance();
const cart = chargebee.getCart();
``` 

## `setCustomer(customer)`

Pre-fills customer information and billing address in the checkout form, or passes hidden fields when creating a subscription. You can also use this method to set customer-level custom fields.

### Syntax

```js
cart.setCustomer(customer)
```

### Parameters

**Parameters**

- `customer` (Object) Customer details.
  - `first_name` (String) Customer first name.
  - `last_name` (String) Customer last name.
  - `locale` (String) Locale code in ISO 639-1 format (en, fr). By default, `en` will be used. Learn more about supported locales by Chargebee.
  - `company` (String) Company name.
  - `phone` (String) Customer phone number.
  - `email` (String) Customer mail ID.
  - `billingAddress` (Object)
    - `first_name` (String) First name
    - `last_name` (String) Last name
    - `company` (String) Company name
    - `phone` (String) Phone number.
    - `email` (String) Email ID
    - `line1` (String) Address line 1
    - `line2` (String) Address line 2
    - `city` (String) City
    - `state` (String) State name
    - `state_code` (String) State code
    - `country` (String) Country code
    - `zip` (String) Zip/Postal code

### Return value

Returns the Cart object for method chaining, allowing you to call additional cart methods.

### Example

```js
const chargebee = Chargebee.getInstance();
const cart = chargebee.getCart();

// Create customer object with basic information.
const customer = {
    first_name: "John",
    last_name: "Smith",
    locale: "it",
    billing_address: {
        first_name: "John",
        last_name: "Smith",
        line1: "132, My Street",
        line2: "Kingston, New York",
        state_code: "NY",
        country: "US",
        zip: "12401"
    }
};

// Add custom fields.
customer["cf_about_myself"] = "This is a short bio.";

// Set customer information in cart.
cart.setCustomer(customer);
```

## `setBusinessEntity(businessEntityId)`

Sets the [business entity](https://apidocs.chargebee.com/docs/api/business_entities) to use for creating or updating customer and subscription records in Chargebee Billing. If a business entity was set when [creating](https://www.chargebee.com/docs/js/cb-library-api-ref#init) the Chargebee object, this method overrides it.

### Syntax

```js
cart.setBusinessEntity(businessEntityId)
```

### Parameters

- `entityId` (String, required) Id of business entity.

### Return value

This function returns a promise that resolves when the business entity is set.

### Example

```js
const chargebee = Chargebee.getInstance();
const cart = chargebee.getCart();

// Set business entity for checkout.
cart.setBusinessEntity("acme-inc-us");

// Add product and proceed to checkout.
const product = chargebee.initializeProduct("premium-monthly");
cart.replaceProduct(product);
cart.proceedToCheckout();
```

## `setShippingAddress(shippingAddress)`

Pre-fills shipping address information in the checkout form.

### Syntax

```js
cart.setShippingAddress(shippingAddress)
```

### Parameters

**Parameters**

- `shippingAddress` (Object)
  - `first_name` (String) First name
  - `last_name` (String) Last name
  - `company` (String) Company name
  - `phone` (String) Phone number.
  - `email` (String) Email ID
  - `line1` (String) Address line 1
  - `line2` (String) Address line 2
  - `city` (String) City
  - `state` (String) State name
  - `state_code` (String) State code
  - `country` (String) Country code
  - `zip` (String) Zip/Postal code

### Return value

Returns the Cart object for method chaining, allowing you to call additional cart methods.

### Example

```js
const chargebee = Chargebee.getInstance();
const cart = chargebee.getCart();

// Create shipping address object.
const shippingAddress = {
    first_name: "John",
    last_name: "Smith",
    line1: "132, My Street",
    line2: "Kingston, New York",
    state_code: "NY",
    country: "US",
    zip: "12401"
};

// Set shipping address in cart.
cart.setShippingAddress(shippingAddress);
```

## `replaceProduct(product)`

Adds a product to your cart, replacing any existing products. Use this method to set up the items that will be included in the checkout process.

### Syntax

```js
cart.replaceProduct(product);
```

### Parameters

- `product` Product object created using `initializeProduct()` or `getProduct()`.

### Return value

Returns the Cart object for function chaining, allowing you to call additional cart methods.

### Example

```js
function onClickSubscribe(planId) {
    const chargebee = Chargebee.getInstance();
    const cart = chargebee.getCart();
    
    // Create a product object.
    const product = chargebee.initializeProduct(planId);
    
    // Add the product to the cart.
    cart.replaceProduct(product);
    
    // Proceed to checkout.
    cart.proceedToCheckout();
}
```

## `setAffiliateToken(token)`

Sets a [subscription affiliate token](https://apidocs.chargebee.com/docs/api/subscriptions#subscription_affiliate_token) for tracking affiliate referrals during checkout.

### Syntax

```js
cart.setAffiliateToken(token)
```

### Parameters

- `token` (String) Affiliate token to be recorded against the subscription.

### Return value

Returns the Cart object for function chaining, allowing you to call additional cart methods.

### Example

```js
const chargebee = Chargebee.getInstance();
const cart = chargebee.getCart();

// Set affiliate token for tracking.
cart.setAffiliateToken("affiliate_12345");

// Add product and proceed to checkout.
const product = chargebee.initializeProduct("premium-monthly");
cart.replaceProduct(product);
cart.proceedToCheckout();
```

## `proceedToCheckout()`

Opens the Chargebee Checkout page with the items and customer information currently in the cart. This method initiates the complete checkout flow, including payment processing.

### Syntax

```js
cart.proceedToCheckout();
```

### Return value

This function does not return a value.

### Example

```js
function onClickSubscribe(planId) {
    const chargebee = Chargebee.getInstance();
    const cart = chargebee.getCart();
    
    // Create and add product to cart.
    const product = chargebee.initializeProduct(planId);
    cart.replaceProduct(product);
    
    // Open checkout.
    cart.proceedToCheckout();
}
```