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

```ts
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`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/enumerations/ordered-product-interval-unit-of-measure)

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

  ```ts
  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`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-ordered-product); `subscription`: [`FirmhouseSubscription`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-subscription); }>

Ordered product and subscription

| Member           | Type                                                                                                                           | Value |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----- |
| `orderedProduct` | [`FirmhouseOrderedProduct`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-ordered-product) | -     |
| `subscription`   | [`FirmhouseSubscription`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-subscription)      | -     |

#### Throws

* [ServerError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/server) - When the request fails
* [NotFoundError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/not-found) - When the product or subscription is not found

***

### applyPromotion()

```ts
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`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-applied-order-discount-promotion) | [`FirmhouseBillingCyclePromotion`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-billing-cycle-promotion)>

Applied promotion

#### Throws

* [ServerError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/server) - When the request fails
* [ValidationError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/validation) - When there are invalid fields

***

### applyPromotionWithDiscountCode()

`Beta`

```ts
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`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-applied-order-discount-promotion) | [`FirmhouseBillingCyclePromotion`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-billing-cycle-promotion)>

Applied promotion

#### Throws

* [ServerError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/server) - When the request fails
* [ValidationError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/validation) - When there are invalid fields
* [NotFoundError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/not-found) - When the subscription is not found

***

### cancel()

```ts
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`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-subscription)>

Cancelled subscription

#### Throws

* [ValidationError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/validation) - When the request is not in cancellable state
* [ServerError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/server) - When the request fails
* [NotFoundError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/not-found) - When the subscription is not found

***

### deactivateAppliedPromotion()

```ts
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`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-applied-order-discount-promotion) | [`FirmhouseBillingCyclePromotion`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-billing-cycle-promotion)>

Deactivated applied promotion

#### Throws

* [ServerError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/server) - When the request fails

***

### get()

```ts
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`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-subscription)>

Subscription

#### Throws

* [NotFoundError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/not-found) - When the subscription is not found

***

### getBySelfServiceCenterLoginToken()

```ts
getBySelfServiceCenterLoginToken(token): Promise<FirmhouseSubscription>
```

Get a subscription by self service center login token

#### Parameters

• **token**: `string`

Self service center login token

#### Returns

`Promise`<[`FirmhouseSubscription`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-subscription)>

Subscription

#### Throws

* [NotFoundError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/not-found) - When the subscription is not found

***

### pause()

```ts
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**

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

#### Returns

`Promise`<[`FirmhouseSubscription`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-subscription)>

Paused subscription

#### Throws

* [ValidationError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/validation) - When the request is not in pausable state
* [ServerError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/server) - When the request fails
* [NotFoundError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/not-found) - When the subscription is not found

***

### removeProduct()

```ts
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`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-subscription); }>

Subscription

| Member         | Type                                                                                                                      | Value |
| -------------- | ------------------------------------------------------------------------------------------------------------------------- | ----- |
| `subscription` | [`FirmhouseSubscription`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-subscription) | -     |

#### Throws

* [ServerError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/server) - When the request fails
* [NotFoundError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/not-found) - When the product is not found

***

### resume()

```ts
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**

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

#### Returns

`Promise`<[`FirmhouseSubscription`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-subscription)>

Resumed subscription

#### Throws

* [ValidationError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/validation) - When the request is not in resumable state
* [ServerError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/server) - When the request fails
* [NotFoundError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/not-found) - When the subscription is not found

***

### updateAppliedPromotion()

```ts
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`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-applied-order-discount-promotion) | [`FirmhouseBillingCyclePromotion`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-billing-cycle-promotion)>

Applied promotion

#### Throws

* [ServerError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/server) - When the request fails
* [ValidationError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/validation) - When there are invalid fields
* [NotFoundError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/not-found) - When the subscription is not found

***

### updateOrderedProduct()

```ts
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`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/enumerations/ordered-product-interval-unit-of-measure)

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

  ```ts
  2024-01-01
  ```

#### Returns

`Promise`<{ `orderedProduct`: [`FirmhouseOrderedProduct`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-ordered-product); `subscription`: [`FirmhouseSubscription`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-subscription); }>

Updated subscription and ordered product

| Member           | Type                                                                                                                           | Value |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----- |
| `orderedProduct` | [`FirmhouseOrderedProduct`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-ordered-product) | -     |
| `subscription`   | [`FirmhouseSubscription`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-subscription)      | -     |

#### Throws

* [ServerError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/server) - When the request fails
* [NotFoundError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/not-found) - When the product is not found
* [ValidationError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/validation) - When there are invalid fields

***

### updatePlan()

```ts
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`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-subscription)>

Updated subscription

#### Throws

* [ServerError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/server) - When the request fails
* [NotFoundError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/not-found) - When the plan or subscription is not found

***

### updateSubscription()

```ts
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**

  ```ts
  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**

  ```ts
  2024-01-15T00:00:00+01:00
  ```
* **cancelledAt?**: `null` | `string`

  The time the subscription was (fully) cancelled.

  **Example**

  ```ts
  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**

  ```ts
  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**

  ```ts
  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**

  ```ts
  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`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/enumerations/subscription-status)

  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`](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/interfaces/firmhouse-subscription)>

Updated subscription and validation errors

#### Remarks

Will return validation error messages for invalid fields.

#### Throws

* [ServerError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/server) - When the request fails
* [ValidationError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/validation) - When there are invalid fields
* [NotFoundError](https://developer.firmhouse.com/sdks/firmhouse-sdk/reference/errors/not-found) - When the subscription is not found