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

Last updated 1 year ago

Was this helpful?