Ctrlk
FirmhouseHelp CenterStatusPortal / Login
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Class: 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?

number | null

A custom price in cents for this ordered product, if left blank the default product price will be used

ensureNewRecord?

boolean | null

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?

number | null

The amount of time in units between shipments of this order

intervalUnitOfMeasureType?

| OrderedProductIntervalUnitOfMeasure | null

The time measure for interval units

metadata?

unknown

Metadata that can be used by developers to store additional information on objects.

productId?

string | null

ID for the related product

quantity?

number | null

The quantity for this ordered product.

shipmentDate?

string | null

The next date on which a new order should get initiated

Example

shopifyVariantId?

string | null

Use this field to look up the associated product based on Shopify Variant ID.

sku?

string | null

Use this field to look up the associated product based on SKU.

slug?

string | null

Use this field to look up the associated product based on slug.

subscriptionId?

string | null

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

Throws

applyDiscountCode()

Apply a discount code to a cart.

Parameters

cartToken

string

Cart token

discountCode

string

Discount code to apply

Returns

Promise<FirmhouseAppliedPromotion>

Applied promotion

Throws

createCartToken()

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

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<{ payment: FirmhousePayment | null; paymentUrl: string | null; returnUrl: string | null; subscription: FirmhouseCart; }>

Payment details and validation errors if any

Remarks

payment is the initial payment to collect. It is null when the checkout has nothing to pay for. Pass its token to client.payments to render the payment step in your own storefront instead of sending the customer to paymentUrl.

Throws

get()

Get a cart by cart token

Parameters

token

string

Cart token

includeRelations?

Relations to include

appliedPromotions?

{ includeRelations?: { discountCode?: boolean; promotion?: boolean; }; }

Include applied promotions

appliedPromotions.includeRelations?

{ discountCode?: boolean; promotion?: boolean; }

Include relations for applied promotions

appliedPromotions.includeRelations.discountCode?

boolean

Include the discountCode relation

appliedPromotions.includeRelations.promotion?

boolean

Include the promotion relation

discountCodes?

{ includeRelations?: { autoSelectPlan?: boolean; promotion?: boolean; }; }

Parameters for including discountCodes Relation

discountCodes.includeRelations?

{ autoSelectPlan?: boolean; promotion?: boolean; }

Include relations for discountCodes

discountCodes.includeRelations.autoSelectPlan?

boolean

Include the autoSelectPlan relation

discountCodes.includeRelations.promotion?

boolean

Include the promotion relation

Returns

Promise<FirmhouseCart>

Cart

Throws

getOrCreate()

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?

{ includeRelations?: { discountCode?: boolean; promotion?: boolean; }; }

Include applied promotions

appliedPromotions.includeRelations?

{ discountCode?: boolean; promotion?: boolean; }

Include relations for applied promotions

appliedPromotions.includeRelations.discountCode?

boolean

Include the discountCode relation

appliedPromotions.includeRelations.promotion?

boolean

Include the promotion relation

discountCodes?

{ includeRelations?: { autoSelectPlan?: boolean; promotion?: boolean; }; }

Parameters for including discountCodes Relation

discountCodes.includeRelations?

{ autoSelectPlan?: boolean; promotion?: boolean; }

Include relations for discountCodes

discountCodes.includeRelations.autoSelectPlan?

boolean

Include the autoSelectPlan relation

discountCodes.includeRelations.promotion?

boolean

Include the promotion relation

Returns

Promise<FirmhouseCart>

Cart if it exists, otherwise a new cart

removeDiscountCode()

Remove the discount code applied to a cart.

Parameters

cartToken

string

Cart token

Returns

Promise<void>

Throws

removeProduct()

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

Throws

  • ServerError Thrown if the product could not be removed from the cart

  • NotFoundError Thrown if the product or cart is not found

updateAddressDetails()

Update the address details of a subscription.

Parameters

cartToken

string

Cart token

input

Address details, address, name, email, etc

activatedAt?

string | null

The time the subscription was activated

Example

address?

string | null

The customer's address line or street.

adyenShopperReference?

string | null

The Adyen shopper reference being used for charges.

billToAddress?

string | null

The customer's billing address address line or street.

billToCity?

string | null

The customer's billing address city or town.

billToCompanyName?

string | null

The company name of the customer's billing address.

billToCountry?

string | null

The customer's billing address country code (ISO3661).

billToDistrict?

string | null

The customer's billing address district.

billToHouseNumber?

string | null

The customer's billing address house, building, or appartment number.

billToLastName?

string | null

The customer's billing address last name.

billToName?

string | null

The customer's billing address first name.

billToPhoneNumber?

string | null

The customer's billing address phone number (international format).

billToSalutation?

string | null

The customer's billing address salutation (mr,ms,mx).

billToState?

string | null

The customer's billing address state or province (ISO3661-2).

billToZipcode?

string | null

The customer's billing address zip code or postal code.

cancellationStartedAt?

string | null

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

Example

cancelledAt?

string | null

The time the subscription was (fully) cancelled.

Example

chargeDayOfTheMonth?

number | null

The day of the month when the customer is charged.

city?

string | null

The customer's city or town.

companyName?

string | null

The company name of the customer.

country?

string | null

The customer's country code (ISO3661).

customerReference?

string | null

The field that can be used for your internal reference. For example, internal customer id.

dateOfBirth?

string | null

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

Example

differentBillingAddress?

boolean | null

Whether billing and shipping addresses are the same. Set this flag to true to store a separate billing address.

district?

string | null

The customer's district.

email?

string | null

The customer's email address.

extraFields?

ExtraFieldInput[] | null

Extra field values for the subscription.

houseNumber?

string | null

The customer's house, building, or appartment number.

importedSubscriptionId?

string | null

Unique ID for an imported subscription.

lastName?

string | null

The customer's last name.

locale?

string | null

The customer's language/locale. Must be enabled on the project.

markedAsNonPayingAt?

string | null

Time time the subscription was marked as non-paying.

Example

marketingOptIn?

boolean | null

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?

string | null

The Mollie Customer ID (cst_XXX)

name?

string | null

The customer's first name.

notes?

string | null

Notes specific for this subscription

phoneNumber?

string | null

The customer's phone number (international format).

pspPaymentProperties?

unknown

Additional payment service provider specific properties used for payment creation.

salutation?

string | null

The customer's salutation (mr,ms,mx).

signupCompletedAt?

string | null

The time when the signup was completed.

Example

skipAutoActivationOnSignup?

boolean | null

Don't automatically activate the subscription on signup.

state?

string | null

The customer's state or province (ISO3661-2).

status?

SubscriptionStatus | null

The current status of the subscription. (default: inactive)

stripeCustomerId?

string | null

The Stripe Customer ID (cus_XXX)

stripePaymentMethodId?

string | null

The Stripe Payment Method ID of the active payment method to charge. (pm_XXX)

termsAccepted?

boolean | null

Whether the customer accepted the terms and conditions.

token?

string | null

The token of the subscription to update, or creates a new one if one doesn't exist.

trialPeriodMonths?

number | null

The number of months before the customer is charged for the first time.

vatNumber?

string | null

The company VAT number.

zipcode?

string | null

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

updateOrderedProduct()

Update an ordered product

Parameters

cartToken

string

Cart token

input

Payload for fields to update

customPriceCents?

number | null

A custom price in cents for this ordered product, if left blank the default product price will be used

id?

string | null

ID of this ordered product.

interval?

number | null

The amount of time in units between shipments of this order

intervalUnitOfMeasureType?

| OrderedProductIntervalUnitOfMeasure | null

The time measure for interval units

metadata?

unknown

Metadata that can be used by developers to store additional information on objects.

productId?

string | null

ID for the related product

quantity?

number | null

The quantity for this ordered product.

shipmentDate?

string | null

The next date on which a new order should get initiated

Example

Returns

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

Updated cart

Throws

updateOrderedProductQuantity()

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

Throws

updatePlan()

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

Last updated

Was this helpful?