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

-

subscription

-

Throws


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


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


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


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


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


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


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


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

-

Throws


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


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


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

-

subscription

-

Throws


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


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

Last updated