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

addProduct(subscriptionToken, input): Promise<{
  orderedProduct: FirmhouseOrderedProduct;
  subscription: FirmhouseSubscription;
}>

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

  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: FirmhouseSubscription; }>

Ordered product and subscription

Member	Type	Value
orderedProduct	FirmhouseOrderedProduct	-
subscription	FirmhouseSubscription	-

Throws

• ServerError - When the request fails
• NotFoundError - When the product or subscription is not found

---

applyPromotion()

applyPromotion(subscriptionId, promotionId): Promise<FirmhouseAppliedOrderDiscountPromotion | FirmhouseBillingCyclePromotion>

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

applyPromotionWithDiscountCode(subscriptionToken, code): Promise<FirmhouseAppliedOrderDiscountPromotion | FirmhouseBillingCyclePromotion>

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(subscriptionId, input?): Promise<FirmhouseSubscription>

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

deactivateAppliedPromotion(appliedPromotionId): Promise<FirmhouseAppliedOrderDiscountPromotion | FirmhouseBillingCyclePromotion>

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(token, includeRelations?): Promise<FirmhouseSubscription>

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

getBySelfServiceCenterLoginToken(token): Promise<FirmhouseSubscription>

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(subscriptionId, input?): Promise<FirmhouseSubscription>

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

  2024-01-15T00:00:00+01:00

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

removeProduct(subscriptionToken, orderedProductId): Promise<{
  subscription: FirmhouseSubscription;
}>

Remove a product from subscription

Parameters

• subscriptionToken: string

Subscription token

• orderedProductId: string

Ordered product id to destroy

Returns

Promise<{ subscription: FirmhouseSubscription; }>

Subscription

Member	Type	Value
subscription	FirmhouseSubscription	-

Throws

• ServerError - When the request fails
• NotFoundError - When the product is not found

---

resume()

resume(subscriptionId, input?): Promise<FirmhouseSubscription>

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

  2024-01-15T00:00:00+01:00

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

updateAppliedPromotion(input): Promise<FirmhouseAppliedOrderDiscountPromotion | FirmhouseBillingCyclePromotion>

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

updateOrderedProduct(subscriptionToken, input): Promise<{
  orderedProduct: FirmhouseOrderedProduct;
  subscription: FirmhouseSubscription;
}>

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

  2024-01-01

Returns

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

Updated subscription and ordered product

Member	Type	Value
orderedProduct	FirmhouseOrderedProduct	-
subscription	FirmhouseSubscription	-

Throws

• ServerError - When the request fails
• NotFoundError - When the product is not found
• ValidationError - When there are invalid fields

---

updatePlan()

updatePlan(subscriptionToken, planSlug): Promise<FirmhouseSubscription>

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

updateSubscription(subscriptionToken, input): Promise<FirmhouseSubscription>

Update a subscription.

Parameters

• subscriptionToken: string

Subscription token

• input

Payload for updating subscription

• 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<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