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

Last updated 5 months ago