# CartsResource

You can use carts for all the necessary operations to manage a customer's cart and implement cart functionality in your application. You can handle everything related to managing items in the cart before checkout such as adding, removing items, updating quantities, accessing payment and checkout urls and more.

## Methods

### addProduct()

```ts
addProduct(cartToken, input): Promise<{
  orderedProduct: FirmhouseOrderedProduct;
  subscription: FirmhouseCart;
}>
```

Add a product to the cart

#### Parameters

• **cartToken**: `string`

Cart token

• **input**

Parameters for the added product

* **customPriceCents?**: `null` | `number`

  A custom price in cents for this ordered product, if left blank the default product price will be used
* **ensureNewRecord?**: `null` | `boolean`

  Create a new record even if the same product already exists in subscription. Without this paramater when you add a new product and if the product already exists in the subscription, the quantity of the product will be updated.
* **interval?**: `null` | `number`

  The amount of time in units between shipments of this order
* **intervalUnitOfMeasureType?**: `null` | [`OrderedProductIntervalUnitOfMeasure`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/enumerations/ordered-product-interval-unit-of-measure)

  The time measure for interval units
* **metadata?**: `unknown`

  Metadata that can be used by developers to store additional information on objects.
* **productId?**: `null` | `string`

  ID for the related product
* **quantity?**: `null` | `number`

  The quantity for this ordered product.
* **shipmentDate?**: `null` | `string`

  The next date on which a new order should get initiated

  **Example**

  ```ts
  2000-01-01
  ```
* **shopifyVariantId?**: `null` | `string`

  Use this field to look up the associated product based on Shopify Variant ID.
* **sku?**: `null` | `string`

  Use this field to look up the associated product based on SKU.
* **slug?**: `null` | `string`

  Use this field to look up the associated product based on slug.
* **subscriptionId?**: `null` | `string`

  ID of the subscription to create this OrderedProduct for. Required if authenticated via a project access token

#### Returns

`Promise`<{ `orderedProduct`: [`FirmhouseOrderedProduct`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-ordered-product); `subscription`: [`FirmhouseCart`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-cart); }>

subscription after adding the product and the ordered product

| Member           | Type                                                                                                                           | Value |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----- |
| `orderedProduct` | [`FirmhouseOrderedProduct`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-ordered-product) | -     |
| `subscription`   | [`FirmhouseCart`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-cart)                      | -     |

#### Throws

* [ServerError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/server) Thrown if the product could not be added to the cart
* [ValidationError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/validation) Thrown if the input is invalid
* [NotFoundError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/not-found) Thrown if the product or cart is not found

***

### createCartToken()

```ts
createCartToken(): Promise<string>
```

Create a new cart and return the subscription token

#### Returns

`Promise`<`string`>

cart token

#### Throws

* [ServerError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/server) Thrown if no token is returned from the API

***

### createSubscription()

```ts
createSubscription(
   cartToken, 
   paymentPageUrl, 
   returnUrl): Promise<{
  paymentUrl: null | string;
  returnUrl: createSubscriptionFromCart.returnUrl;
  subscription: FirmhouseCart;
}>
```

Finalises a subscription and returns payment details based on a cart/draft subscription

#### Parameters

• **cartToken**: `string`

Cart token

• **paymentPageUrl**: `string`

The URL where the user can sign up for a new subscription

• **returnUrl**: `string`

The URL the user gets redirected to after completing payment

#### Returns

`Promise`<{ `paymentUrl`: `null` | `string`; `returnUrl`: createSubscriptionFromCart.returnUrl; `subscription`: [`FirmhouseCart`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-cart); }>

Payment details and validation errors if any

| Member         | Type                                                                                                      | Value                                |
| -------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `paymentUrl`   | `null` \| `string`                                                                                        | -                                    |
| `returnUrl`    | `null` \| `string`                                                                                        | createSubscriptionFromCart.returnUrl |
| `subscription` | [`FirmhouseCart`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-cart) | -                                    |

#### Throws

* [ValidationError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/validation) Thrown if required fields is missing from cart
* [ServerError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/server) Thrown if the subscription could not be created
* [NotFoundError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/not-found) Thrown if the cart is not found

***

### get()

```ts
get(token, includeRelations?): Promise<FirmhouseCart>
```

Get a cart by cart token

#### Parameters

• **token**: `string`

Cart token

• **includeRelations?**

Relations to include

* **appliedPromotions?**: Include applied promotions
  * **includeRelations?**: Include relations for applied promotions
    * **discountCode?**: `boolean`

      Include the discountCode relation
    * **promotion?**: `boolean`

      Include the promotion relation
* **discountCodes?**: Parameters for including discountCodes Relation
  * **includeRelations?**: Include relations for discountCodes
    * **autoSelectPlan?**: `boolean`

      Include the autoSelectPlan relation
    * **promotion?**: `boolean`

      Include the promotion relation

#### Returns

`Promise`<[`FirmhouseCart`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-cart)>

Cart

#### Throws

* [NotFoundError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/not-found) Thrown if the cart is not found

***

### getOrCreate()

```ts
getOrCreate(token?, includeRelations?): Promise<FirmhouseCart>
```

Try to get a cart by token, if it exists and is a subscription in draft status, return it. Otherwise create a new cart.

#### Parameters

• **token?**: `string`

Cart token

• **includeRelations?**

* **appliedPromotions?**: Include applied promotions
  * **includeRelations?**: Include relations for applied promotions
    * **discountCode?**: `boolean`

      Include the discountCode relation
    * **promotion?**: `boolean`

      Include the promotion relation
* **discountCodes?**: Parameters for including discountCodes Relation
  * **includeRelations?**: Include relations for discountCodes
    * **autoSelectPlan?**: `boolean`

      Include the autoSelectPlan relation
    * **promotion?**: `boolean`

      Include the promotion relation

#### Returns

`Promise`<[`FirmhouseCart`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-cart)>

Cart if it exists, otherwise a new cart

***

### removeProduct()

```ts
removeProduct(cartToken, orderedProductId): Promise<{
  orderedProduct: FirmhouseOrderedProduct;
  subscription: FirmhouseCart;
}>
```

Remove a product from the cart

#### Parameters

• **cartToken**: `string`

Cart token

• **orderedProductId**: `string`

Ordered product id to remove from the cart

#### Returns

`Promise`<{ `orderedProduct`: [`FirmhouseOrderedProduct`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-ordered-product); `subscription`: [`FirmhouseCart`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-cart); }>

subscription after removing the product and the removed product

| Member           | Type                                                                                                                           | Value |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----- |
| `orderedProduct` | [`FirmhouseOrderedProduct`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-ordered-product) | -     |
| `subscription`   | [`FirmhouseCart`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-cart)                      | -     |

#### Throws

* [ServerError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/server) Thrown if the product could not be removed from the cart
* [NotFoundError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/not-found) Thrown if the product or cart is not found

***

### updateAddressDetails()

```ts
updateAddressDetails(cartToken, input): Promise<FirmhouseCart>
```

Update the address details of a subscription.

#### Parameters

• **cartToken**: `string`

Cart token

• **input**

Address details, address, name, email, etc

* **activatedAt?**: `null` | `string`

  The time the subscription was activated

  **Example**

  ```ts
  2024-01-15T00:00:00+01:00
  ```
* **address?**: `null` | `string`

  The customer's address line or street.
* **adyenShopperReference?**: `null` | `string`

  The Adyen shopper reference being used for charges.
* **billToAddress?**: `null` | `string`

  The customer's billing address address line or street.
* **billToCity?**: `null` | `string`

  The customer's billing address city or town.
* **billToCompanyName?**: `null` | `string`

  The company name of the customer's billing address.
* **billToCountry?**: `null` | `string`

  The customer's billing address country code (ISO3661).
* **billToDistrict?**: `null` | `string`

  The customer's billing address district.
* **billToHouseNumber?**: `null` | `string`

  The customer's billing address house, building, or appartment number.
* **billToLastName?**: `null` | `string`

  The customer's billing address last name.
* **billToName?**: `null` | `string`

  The customer's billing address first name.
* **billToPhoneNumber?**: `null` | `string`

  The customer's billing address phone number (international format).
* **billToSalutation?**: `null` | `string`

  The customer's billing address salutation (mr,ms,mx).
* **billToState?**: `null` | `string`

  The customer's billing address state or province (ISO3661-2).
* **billToZipcode?**: `null` | `string`

  The customer's billing address zip code or postal code.
* **cancellationStartedAt?**: `null` | `string`

  The time the subscription started the cancellation process (with two-step cancellation)

  **Example**

  ```ts
  2024-01-15T00:00:00+01:00
  ```
* **cancelledAt?**: `null` | `string`

  The time the subscription was (fully) cancelled.

  **Example**

  ```ts
  2024-01-15T00:00:00+01:00
  ```
* **chargeDayOfTheMonth?**: `null` | `number`

  The day of the month when the customer is charged.
* **city?**: `null` | `string`

  The customer's city or town.
* **companyName?**: `null` | `string`

  The company name of the customer.
* **country?**: `null` | `string`

  The customer's country code (ISO3661).
* **customerReference?**: `null` | `string`

  The field that can be used for your internal reference. For example, internal customer id.
* **dateOfBirth?**: `null` | `string`

  The customer's date of birth (yyyy-mm-dd).

  **Example**

  ```ts
  2000-01-01
  ```
* **differentBillingAddress?**: `null` | `boolean`

  Whether billing and shipping addresses are the same. Set this flag to `true` to store a separate billing address.
* **district?**: `null` | `string`

  The customer's district.
* **email?**: `null` | `string`

  The customer's email address.
* **extraFields?**: `null` | `ExtraFieldInput`\[]

  Extra field values for the subscription.
* **houseNumber?**: `null` | `string`

  The customer's house, building, or appartment number.
* **importedSubscriptionId?**: `null` | `string`

  Unique ID for an imported subscription.
* **lastName?**: `null` | `string`

  The customer's last name.
* **locale?**: `null` | `string`

  The customer's language/locale. Must be enabled on the project.
* **markedAsNonPayingAt?**: `null` | `string`

  Time time the subscription was marked as non-paying.

  **Example**

  ```ts
  2024-01-15T00:00:00+01:00
  ```
* **marketingOptIn?**: `null` | `boolean`

  Whether the customer accepted optional marketing communication opt-in.
* **metadata?**: `unknown`

  Metadata that can be used by developers to store additional information on objects.
* **mollieCustomerId?**: `null` | `string`

  The Mollie Customer ID (cst\_XXX)
* **name?**: `null` | `string`

  The customer's first name.
* **notes?**: `null` | `string`

  Notes specific for this subscription
* **phoneNumber?**: `null` | `string`

  The customer's phone number (international format).
* **pspPaymentProperties?**: `unknown`

  Additional payment service provider specific properties used for payment creation.
* **salutation?**: `null` | `string`

  The customer's salutation (mr,ms,mx).
* **signupCompletedAt?**: `null` | `string`

  The time when the signup was completed.

  **Example**

  ```ts
  2024-01-15T00:00:00+01:00
  ```
* **skipAutoActivationOnSignup?**: `null` | `boolean`

  Don't automatically activate the subscription on signup.
* **state?**: `null` | `string`

  The customer's state or province (ISO3661-2).
* **status?**: `null` | [`SubscriptionStatus`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/enumerations/subscription-status)

  The current status of the subscription. (default: inactive)
* **stripeCustomerId?**: `null` | `string`

  The Stripe Customer ID (cus\_XXX)
* **stripePaymentMethodId?**: `null` | `string`

  The Stripe Payment Method ID of the active payment method to charge. (pm\_XXX)
* **termsAccepted?**: `null` | `boolean`

  Whether the customer accepted the terms and conditions.
* **token?**: `null` | `string`

  The token of the subscription to update, or creates a new one if one doesn't exist.
* **trialPeriodMonths?**: `null` | `number`

  The number of months before the customer is charged for the first time.
* **vatNumber?**: `null` | `string`

  The company VAT number.
* **zipcode?**: `null` | `string`

  The customer's zip code or postal code.

#### Returns

`Promise`<[`FirmhouseCart`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-cart)>

Updated cart and validation errors

#### Remarks

Will save changes to certain fields even when other fields given are invalid. Will return validation error messages for invalid fields.

#### Throws

* [ValidationError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/validation) Thrown if the input is invalid
* [ServerError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/server) Thrown if the address details could not be updated
* [NotFoundError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/not-found) Thrown if the cart is not found

***

### updateOrderedProduct()

```ts
updateOrderedProduct(cartToken, input): Promise<{
  orderedProduct: FirmhouseOrderedProduct;
  subscription: FirmhouseCart;
}>
```

Update an ordered product

#### Parameters

• **cartToken**: `string`

Cart token

• **input**

Payload for fields to update

* **customPriceCents?**: `null` | `number`

  A custom price in cents for this ordered product, if left blank the default product price will be used
* **id?**: `null` | `string`

  ID of this ordered product.
* **interval?**: `null` | `number`

  The amount of time in units between shipments of this order
* **intervalUnitOfMeasureType?**: `null` | [`OrderedProductIntervalUnitOfMeasure`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/enumerations/ordered-product-interval-unit-of-measure)

  The time measure for interval units
* **metadata?**: `unknown`

  Metadata that can be used by developers to store additional information on objects.
* **productId?**: `null` | `string`

  ID for the related product
* **quantity?**: `null` | `number`

  The quantity for this ordered product.
* **shipmentDate?**: `null` | `string`

  The next date on which a new order should get initiated

  **Example**

  ```ts
  2024-01-01
  ```

#### Returns

`Promise`<{ `orderedProduct`: [`FirmhouseOrderedProduct`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-ordered-product); `subscription`: [`FirmhouseCart`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-cart); }>

Updated cart

| Member           | Type                                                                                                                           | Value |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----- |
| `orderedProduct` | [`FirmhouseOrderedProduct`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-ordered-product) | -     |
| `subscription`   | [`FirmhouseCart`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-cart)                      | -     |

#### Throws

* [ServerError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/server) Thrown if the ordered product could not be updated
* [ValidationError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/validation) Thrown if the input is invalid
* [NotFoundError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/not-found) Thrown if the product or cart is not found

***

### updateOrderedProductQuantity()

```ts
updateOrderedProductQuantity(
   cartToken, 
   orderedProductId, 
   quantity): Promise<{
  orderedProduct: FirmhouseOrderedProduct;
  subscription: FirmhouseCart;
}>
```

Update a product quantity in the cart

#### Parameters

• **cartToken**: `string`

Cart token

• **orderedProductId**: `string`

Ordered product id to update quantity

• **quantity**: `number`

New quantity

#### Returns

`Promise`<{ `orderedProduct`: [`FirmhouseOrderedProduct`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-ordered-product); `subscription`: [`FirmhouseCart`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-cart); }>

Updated cart

| Member           | Type                                                                                                                           | Value |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----- |
| `orderedProduct` | [`FirmhouseOrderedProduct`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-ordered-product) | -     |
| `subscription`   | [`FirmhouseCart`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-cart)                      | -     |

#### Throws

* [ServerError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/server) Thrown if the product quantity could not be updated
* [NotFoundError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/not-found) Thrown if the product or cart is not found
* [ValidationError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/validation) Thrown if the input is invalid

***

### updatePlan()

```ts
updatePlan(cartToken, planSlug): Promise<FirmhouseCart>
```

Updates the active plan of a subscription

#### Parameters

• **cartToken**: `string`

Cart token

• **planSlug**: `string`

Slug of the plan to update the subscription to

#### Returns

`Promise`<[`FirmhouseCart`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-cart)>

Updated cart

#### Throws

* [ServerError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/server) Thrown if the plan could not be changed
* [NotFoundError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/not-found) Thrown if the cart or plan is not found