SubscriptionsResource
You can use subscriptions to manage the subscriptions in your project. It's similar to the carts but the difference is that the subscriptions are carts that are already checked out.
Methods
addProduct()
Add a new product to subscription
Parameters
• subscriptionToken: string
Subscription 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
intervalUnitOfMeasure?:
null
|string
The time measure for interval units. This argument is deprecated. Use intervalUnitOfMeasureType instead. If intervalUnitOfMeasureType passed, this field will be ignored.
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
: FirmhouseSubscription
; }>
Ordered product and subscription
orderedProduct
-
subscription
-
Throws
ServerError - When the request fails
NotFoundError - When the product or subscription is not found
applyPromotion()
Applies a promotion to a subscription.
Parameters
• subscriptionId: string
ID of the subscription to apply the promotion to.
• promotionId: string
ID of the promotion to apply.
Returns
Promise
<FirmhouseAppliedOrderDiscountPromotion
| FirmhouseBillingCyclePromotion
>
Applied promotion
Throws
ServerError - When the request fails
ValidationError - When there are invalid fields
applyPromotionWithDiscountCode()
Beta
Apply a promotion using a discount code to a subscription
Parameters
• subscriptionToken: string
Subscription token
• code: string
Discount code to apply
Returns
Promise
<FirmhouseAppliedOrderDiscountPromotion
| FirmhouseBillingCyclePromotion
>
Applied promotion
Throws
ServerError - When the request fails
ValidationError - When there are invalid fields
NotFoundError - When the subscription is not found
cancel()
Cancel a subscription
Parameters
• subscriptionId: string
ID of the subscription to cancel
• input?
Payload for cancellation
cancellationNotes?:
null
|string
Why did this customer decide to cancel?
skipCancellationConfirmationEmail?:
null
|boolean
Skip sending the standard cancellation confirmation email to the customer.
skipContractTermsEnforcement?:
null
|boolean
If a customer cannot be cancelled due to active commitments, this process can be skipped.
skipTwoStepCancellation?:
null
|boolean
If two-step cancellation is enabled it can be skipped
Returns
Promise
<FirmhouseSubscription
>
Cancelled subscription
Throws
ValidationError - When the request is not in cancellable state
ServerError - When the request fails
NotFoundError - When the subscription is not found
deactivateAppliedPromotion()
Deactivates an applied promotion
Parameters
• appliedPromotionId: string
ID of the applied promotion that needs to be deactivated.
Returns
Promise
<FirmhouseAppliedOrderDiscountPromotion
| FirmhouseBillingCyclePromotion
>
Deactivated applied promotion
Throws
ServerError - When the request fails
get()
Get a subscription by subscription token including relations
Parameters
• token: string
Subscription 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
collectionCases?:
boolean
Include collectionCases relation
discountCodes?: Parameters for including discountCodes Relation
includeRelations?: Include relations for discountCodes
autoSelectPlan?:
boolean
Include the autoSelectPlan relation
promotion?:
boolean
Include the promotion relation
invoices?: Parameters for including invoices relation
includeRelations?: Include collectionCase relation
collectionCase?:
boolean
Include collectionCase relation
invoiceLineItems?:
boolean
Include invoiceLineItems relation
invoiceReminders?:
boolean
Include invoiceReminders relation
originalInvoice?:
boolean
Include originalInvoice relation
payment?:
boolean
Include payment relation
orders?: Parameters for including orders relation
after?:
string
Fetch orders after this cursor
before?:
string
Fetch orders before this cursor
first?:
number
Fetch first n orders
includeRelations?: Include relations for orders
invoice?:
boolean
Include invoice relation
orderLines?:
boolean
Include orderLines relation
payment?:
boolean
Include payment relation
last?:
number
Fetch last n orders
verifiedIdentity?:
boolean
Include verifiedIdentity relation
Returns
Promise
<FirmhouseSubscription
>
Subscription
Throws
NotFoundError - When the subscription is not found
getBySelfServiceCenterLoginToken()
Get a subscription by self service center login token
Parameters
• token: string
Self service center login token
Returns
Promise
<FirmhouseSubscription
>
Subscription
Throws
NotFoundError - When the subscription is not found
pause()
Pause a subscription
Parameters
• subscriptionId: string
ID of the subscription to pause
• input?
Payload for pausing
pauseUntil?:
null
|string
Time from which the subscription automaticaly resumes again.
Example
Returns
Promise
<FirmhouseSubscription
>
Paused subscription
Throws
ValidationError - When the request is not in pausable state
ServerError - When the request fails
NotFoundError - When the subscription is not found
removeProduct()
Remove a product from subscription
Parameters
• subscriptionToken: string
Subscription token
• orderedProductId: string
Ordered product id to destroy
Returns
Promise
<{ subscription
: FirmhouseSubscription
; }>
Subscription
subscription
-
Throws
ServerError - When the request fails
NotFoundError - When the product is not found
resume()
Resume a subscription
Parameters
• subscriptionId: string
ID of the subscription to resume
• input?
Payload for resuming
resumeFrom?:
null
|string
Time to resume the subscription from. If not given the subscription will be immediately resumed.
Example
Returns
Promise
<FirmhouseSubscription
>
Resumed subscription
Throws
ValidationError - When the request is not in resumable state
ServerError - When the request fails
NotFoundError - When the subscription is not found
updateAppliedPromotion()
Updates a promotion applied to a subscription
Parameters
• input
Paramater for updating the applied promotion
active?:
null
|boolean
Whether this promotion should actively be used for this subscription.
deactivateAfterAmountIncludingTaxCents?:
null
|number
The maximum discount amount in cents that this promotion should provide.Only applicable when using the VALUE deactivation strategy.
deactivateAfterTimes?:
null
|number
After how mamy times used this applied promotion should get deactivated.Only applicable when using the TIMES deactivation strategy.
id:
string
ID of the applied promotion that needs to be updated.
Returns
Promise
<FirmhouseAppliedOrderDiscountPromotion
| FirmhouseBillingCyclePromotion
>
Applied promotion
Throws
ServerError - When the request fails
ValidationError - When there are invalid fields
NotFoundError - When the subscription is not found
updateOrderedProduct()
Update a product in the subscription
Parameters
• subscriptionToken: string
Subscription 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 the ordered product to update
interval?:
null
|number
The amount of time in units between shipments of this order
intervalUnitOfMeasure?:
null
|string
The time measure for interval units. This argument is deprecated. Use intervalUnitOfMeasureType instead. If intervalUnitOfMeasureType passed, this field will be ignored.
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
: FirmhouseSubscription
; }>
Updated subscription and ordered product
orderedProduct
-
subscription
-
Throws
ServerError - When the request fails
NotFoundError - When the product is not found
ValidationError - When there are invalid fields
updatePlan()
Update the plan of a subscription
Parameters
• subscriptionToken: string
Subscription token
• planSlug: string
Slug of the plan to update to
Returns
Promise
<FirmhouseSubscription
>
Updated subscription
Throws
ServerError - When the request fails
NotFoundError - When the plan or subscription is not found
updateSubscription()
Update a subscription.
Parameters
• subscriptionToken: string
Subscription token
• input
Payload for updating subscription
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
<FirmhouseSubscription
>
Updated subscription and validation errors
Remarks
Will return validation error messages for invalid fields.
Throws
ServerError - When the request fails
ValidationError - When there are invalid fields
NotFoundError - When the subscription is not found
Last updated