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

MemberTypeValue

orderedProduct

-

subscription

-

Throws


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

MemberTypeValue

paymentUrl

null | string

-

returnUrl

null | string

createSubscriptionFromCart.returnUrl

subscription

-

Throws


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


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

MemberTypeValue

orderedProduct

-

subscription

-

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


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

MemberTypeValue

orderedProduct

-

subscription

-

Throws


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

MemberTypeValue

orderedProduct

-

subscription

-

Throws


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

Last updated