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()

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

  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

  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; subscription: FirmhouseCart; }>

subscription after adding the product and the ordered product

Member	Type	Value
orderedProduct	FirmhouseOrderedProduct	-
subscription	FirmhouseCart	-

Throws

• ServerError Thrown if the product could not be added to the cart
• ValidationError Thrown if the input is invalid
• NotFoundError Thrown if the product or cart is not found

---

createCartToken()

createCartToken(): Promise<string>

Create a new cart and return the subscription token

Returns

Promise<string>

cart token

Throws

• ServerError Thrown if no token is returned from the API

---

createSubscription()

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; }>

Payment details and validation errors if any

Member	Type	Value
paymentUrl	null | string	-
returnUrl	null | string	createSubscriptionFromCart.returnUrl
subscription	FirmhouseCart	-

Throws

• ValidationError Thrown if required fields is missing from cart
• ServerError Thrown if the subscription could not be created
• NotFoundError Thrown if the cart is not found

---

get()

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>

Cart

Throws

• NotFoundError Thrown if the cart is not found

---

getOrCreate()

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>

Cart if it exists, otherwise a new cart

---

removeProduct()

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; subscription: FirmhouseCart; }>

subscription after removing the product and the removed product

Member	Type	Value
orderedProduct	FirmhouseOrderedProduct	-
subscription	FirmhouseCart	-

Throws

• ServerError Thrown if the product could not be removed from the cart
• NotFoundError Thrown if the product or cart is not found

---

updateAddressDetails()

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

  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

  2024-01-15T00:00:00+01:00

• cancelledAt?: null | string

  The time the subscription was (fully) cancelled.

  Example

  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

  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

  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

  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

  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>

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 Thrown if the input is invalid
• ServerError Thrown if the address details could not be updated
• NotFoundError Thrown if the cart is not found

---

updateOrderedProduct()

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

  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

  2024-01-01

Returns

Promise<{ orderedProduct: FirmhouseOrderedProduct; subscription: FirmhouseCart; }>

Updated cart

Member	Type	Value
orderedProduct	FirmhouseOrderedProduct	-
subscription	FirmhouseCart	-

Throws

• ServerError Thrown if the ordered product could not be updated
• ValidationError Thrown if the input is invalid
• NotFoundError Thrown if the product or cart is not found

---

updateOrderedProductQuantity()

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; subscription: FirmhouseCart; }>

Updated cart

Member	Type	Value
orderedProduct	FirmhouseOrderedProduct	-
subscription	FirmhouseCart	-

Throws

• ServerError Thrown if the product quantity could not be updated
• NotFoundError Thrown if the product or cart is not found
• ValidationError Thrown if the input is invalid

---

updatePlan()

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>

Updated cart

Throws

• ServerError Thrown if the plan could not be changed
• NotFoundError Thrown if the cart or plan is not found