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()
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
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
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()
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
<{ paymentUrl
: null
| string
; returnUrl
: createSubscriptionFromCart.returnUrl; subscription
: FirmhouseCart
; }>
Payment details and validation errors if any
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 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()
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()
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?:
null
|string
The time the subscription was activated
Example
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
cancelledAt?:
null
|string
The time the subscription was (fully) cancelled.
Example
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
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
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
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()
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
Returns
Promise
<{ orderedProduct
: FirmhouseOrderedProduct
; subscription
: FirmhouseCart
; }>
Updated cart
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()
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
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()
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