> For the complete documentation index, see [llms.txt](https://developer.firmhouse.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.firmhouse.com/graphql-api/api-reference/objects/subscription.md).

# Subscription

A subscription contains things like name, address, and company details. A subscription is subscribed to a plan via SubscribedPlan or multiple products via the OrderedProduct object.

### Fields

#### activatedAt ([String](/graphql-api/api-reference/objects/string.md))

The date and time when the subscription was activated and billing started.

#### activePlan ([Plan](/graphql-api/api-reference/objects/plan.md))

Returns the plan the subscription is currently subscribed to.

#### address ([String](/graphql-api/api-reference/objects/string.md))

The customer's full address line or just street. Can include houseNumber if not separately stored in houseNumber field.

#### address2 ([String](/graphql-api/api-reference/objects/string.md))

The customer's additional address information.

#### amountForStartingSubscriptionCents ([Int](/graphql-api/api-reference/objects/int.md))

The amount that is due on checkout (in cents).

#### appliedBillingCyclePromotions (\[[AppliedBillingCyclePromotion](/graphql-api/api-reference/objects/applied-billing-cycle-promotion.md)!])

List of billing cycle promotions applied for this customer.

#### appliedOrderDiscountPromotions (\[[AppliedOrderDiscountPromotion](/graphql-api/api-reference/objects/applied-order-discount-promotion.md)!])

List of order discount promotions applied for this customer.

#### appliedPromotions (\[[AppliedPromotion](/graphql-api/api-reference/objects/applied-promotion.md)!])

List of all applied promotions for this customer.

#### billToAddress ([String](/graphql-api/api-reference/objects/string.md))

The customer's billing address address line or street.

#### billToAddress2 ([String](/graphql-api/api-reference/objects/string.md))

The customer's billing address additional address information.

#### billToCity ([String](/graphql-api/api-reference/objects/string.md))

The customer's billing address city or town.

#### billToCompanyName ([String](/graphql-api/api-reference/objects/string.md))

The company name of the customer's billing address.

#### billToCountry ([String](/graphql-api/api-reference/objects/string.md))

The customer's billing address country code (ISO3661).

#### billToDistrict ([String](/graphql-api/api-reference/objects/string.md))

The customer's billing address district.

#### billToFullAddress ([String](/graphql-api/api-reference/objects/string.md))

The customer's billing address full address by combining address and house number.

#### billToFullName ([String](/graphql-api/api-reference/objects/string.md))

The customer's billing address full name.

#### billToHouseNumber ([String](/graphql-api/api-reference/objects/string.md))

The customer's billing address house, building, or appartment number.

#### billToHouseNumberAddition ([String](/graphql-api/api-reference/objects/string.md))

The customer's billing address house, building, or appartment number addition.

#### billToLastName ([String](/graphql-api/api-reference/objects/string.md))

The customer's billing address last name.

#### billToName ([String](/graphql-api/api-reference/objects/string.md))

The customer' billing address first name.

#### billToPhoneNumber ([String](/graphql-api/api-reference/objects/string.md))

The customer's billing address phone number (international format).

#### billToSalutation ([String](/graphql-api/api-reference/objects/string.md))

The customer's billing address salutation (mr,ms,mx).

#### billToState ([String](/graphql-api/api-reference/objects/string.md))

The customer's billing address state or province (ISO3661-2).

#### billToZipcode ([String](/graphql-api/api-reference/objects/string.md))

The customer's billing address zip code or postal code.

#### cancellationStartedAt ([String](/graphql-api/api-reference/objects/string.md))

The date and time when cancellation was initiated for the subscription (in case of two-step cancellation).

#### cancelledAt ([String](/graphql-api/api-reference/objects/string.md))

The date and time when the subscription was cancelled.

#### chargeDayOfTheMonth ([Int](/graphql-api/api-reference/objects/int.md))

The day of the month when the customer is charged.

#### checkoutUrl ([String](/graphql-api/api-reference/objects/string.md))

URL for the customers to complete their draft subscription.

#### churnRequests ([ChurnRequestConnection](/graphql-api/api-reference/objects/churn-request-connection.md))

List of churn requests for this customer.

| Argument                                                                                   | Description                                                             |
| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
| createdSince ([ISO8601DateTime](/graphql-api/api-reference/objects/iso-8601-date-time.md)) | Filter churn requests to those created since the given datetime.        |
| createdUntil ([ISO8601DateTime](/graphql-api/api-reference/objects/iso-8601-date-time.md)) | Filter churn requests to those created until the given datetime.        |
| status ([ChurnRequestStatus](/graphql-api/api-reference/objects/churn-request-status.md))  | Filter churn requests by status. Lists all if none given.               |
| subscriptionId ([ID](/graphql-api/api-reference/objects/id.md))                            | Filter churn requests to a specific subscription.                       |
| after ([String](/graphql-api/api-reference/objects/string.md))                             | Returns the elements in the list that come after the specified cursor.  |
| before ([String](/graphql-api/api-reference/objects/string.md))                            | Returns the elements in the list that come before the specified cursor. |
| first ([Int](/graphql-api/api-reference/objects/int.md))                                   | Returns the first *n* elements from the list.                           |
| last ([Int](/graphql-api/api-reference/objects/int.md))                                    | Returns the last *n* elements from the list.                            |

#### city ([String](/graphql-api/api-reference/objects/string.md))

The customer's city or town.

#### collectionCases ([CollectionCaseConnection](/graphql-api/api-reference/objects/collection-case-connection.md))

List of collection cases for this customer.

| Argument                                                        | Description                                                             |
| --------------------------------------------------------------- | ----------------------------------------------------------------------- |
| after ([String](/graphql-api/api-reference/objects/string.md))  | Returns the elements in the list that come after the specified cursor.  |
| before ([String](/graphql-api/api-reference/objects/string.md)) | Returns the elements in the list that come before the specified cursor. |
| first ([Int](/graphql-api/api-reference/objects/int.md))        | Returns the first *n* elements from the list.                           |
| last ([Int](/graphql-api/api-reference/objects/int.md))         | Returns the last *n* elements from the list.                            |

#### companyName ([String](/graphql-api/api-reference/objects/string.md))

The customer's company name.

#### country ([String](/graphql-api/api-reference/objects/string.md))

The customer's country code (ISO 3116)

#### createdAt ([String](/graphql-api/api-reference/objects/string.md))

The date and time when the subscription record was first created.

#### currency ([String](/graphql-api/api-reference/objects/string.md))

The currency used for this subscription

#### customerFeedbacks (\[[CustomerFeedback](/graphql-api/api-reference/objects/customer-feedback.md)!])

List of customer feedback for this customer.

#### customerId ([String](/graphql-api/api-reference/objects/string.md))

The customer ID given by the selected payment provider

#### customerReference ([String](/graphql-api/api-reference/objects/string.md))

The field that can be used for your internal reference. For example, internal customer id.

#### dateOfBirth ([ISO8601Date](/graphql-api/api-reference/objects/iso-8601-date.md))

The customer's date of birth

#### deliveryMethod ([DeliveryMethod](/graphql-api/api-reference/objects/delivery-method.md)!)

The delivery method for this subscription.

#### differentBillingAddress ([Boolean](/graphql-api/api-reference/objects/boolean.md))

Whether billing and shipping addresses are the same. Set this flag to \`true\` to store a separate billing address.

#### discountCodes (\[[DiscountCode](/graphql-api/api-reference/objects/discount-code.md)!])

The assigned discount codes.

#### district ([String](/graphql-api/api-reference/objects/string.md))

The customer's district

#### email ([String](/graphql-api/api-reference/objects/string.md))

The customer's email address

#### exemptFromShippingCosts ([Boolean](/graphql-api/api-reference/objects/boolean.md))

Will never add any shipping costs to any order

#### extraFields (\[[ExtraFieldAnswer](/graphql-api/api-reference/objects/extra-field-answer.md)!]!)

List of extra fields and values.

#### fullAddress ([String](/graphql-api/api-reference/objects/string.md))

The customer's full address by combining address and house number.

#### fullName ([String](/graphql-api/api-reference/objects/string.md))

The customer's full name.

#### houseNumber ([String](/graphql-api/api-reference/objects/string.md))

The customer's house number.

#### houseNumberAddition ([String](/graphql-api/api-reference/objects/string.md))

The customer's house number addition.

#### id ([String](/graphql-api/api-reference/objects/string.md))

The id of the subscription.

#### identityVerificationUrl ([String](/graphql-api/api-reference/objects/string.md))

Identity verification URL that automatically uses the configured provider. Append ?return\_url=<https://your-url> to send the customer back after a successful identification.

#### inTrialPeriod ([Boolean](/graphql-api/api-reference/objects/boolean.md)!)

Whether this subscription is currently in its trial period.

#### invoices (\[[Invoice](/graphql-api/api-reference/objects/invoice.md)!])

List of invoices of this customer.

#### lastName ([String](/graphql-api/api-reference/objects/string.md))

The customer's last name.

#### locale ([String](/graphql-api/api-reference/objects/string.md))

The customer's locale/language.

#### markedAsNonPayingAt ([String](/graphql-api/api-reference/objects/string.md))

The date and time when the subscription was last marked as non-paying.

#### marketingOptIn ([Boolean](/graphql-api/api-reference/objects/boolean.md))

Whether the customer accepted the optional marketing opt-in.

#### metadata ([JSON](/graphql-api/api-reference/objects/json.md))

Metadata makes it possible to store additional information on objects.

#### ~~monthlyAmount (~~[~~Float~~](/graphql-api/api-reference/objects/float.md)~~)~~

*`Deprecated: Use monthlyAmountCents instead.`*

The monthly amount that is charged.

#### monthlyAmountCents ([Int](/graphql-api/api-reference/objects/int.md))

The monthly amount that is charged (in cents)

#### name ([String](/graphql-api/api-reference/objects/string.md))

The customer's first name.

#### notes ([String](/graphql-api/api-reference/objects/string.md))

Notes about the customer that can be set in the portal

#### ~~orderCalculation (~~[~~OrderCalculation~~](/graphql-api/api-reference/objects/order-calculation.md)~~)~~

*`Deprecated: Will be removed.`*

Calculate order prices

| Argument                                                                                                 | Description                                     |
| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| orderedProducts (\[[OrderedProductInput](/graphql-api/api-reference/objects/ordered-product-input.md)!]) | The ordered products that are part of the order |
| discountCode ([String](/graphql-api/api-reference/objects/string.md))                                    |                                                 |

#### orderedProducts (\[[OrderedProduct](/graphql-api/api-reference/objects/ordered-product.md)!])

List of products the subscription is on.

#### ~~orders (\[~~[~~Order~~](/graphql-api/api-reference/objects/order.md)~~!])~~

*`Deprecated: Use 'ordersV2' instead.`*

List of orders of this subscription

#### ordersV2 ([OrderConnection](/graphql-api/api-reference/objects/order-connection.md))

List of orders of this subscription

| Argument                                                                                   | Description                                                             |
| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
| createdSince ([ISO8601DateTime](/graphql-api/api-reference/objects/iso-8601-date-time.md)) | Filter orders to those that where created since the given datetime.     |
| paid ([Boolean](/graphql-api/api-reference/objects/boolean.md))                            | Only list orders with given payment status on related invoice.          |
| hasShopifyId ([Boolean](/graphql-api/api-reference/objects/boolean.md))                    | Filter orders by whether they have an associated Shopify order ID.      |
| reverse ([Boolean](/graphql-api/api-reference/objects/boolean.md))                         | Reverse the sort order                                                  |
| status ([OrderStatus](/graphql-api/api-reference/objects/order-status.md))                 | Filter orders on given status. Lists all orders if none given.          |
| updatedSince ([ISO8601DateTime](/graphql-api/api-reference/objects/iso-8601-date-time.md)) | Filter orders to those that where updated since the given datetime.     |
| updatedUntil ([ISO8601DateTime](/graphql-api/api-reference/objects/iso-8601-date-time.md)) | Filter orders to those that where updated until the given datetime.     |
| orderBy ([OrderSortEnum](/graphql-api/api-reference/objects/order-sort-enum.md))           | Specify the sort order for orders. Defaults to CREATED\_AT.             |
| shipmentDateFrom ([ISO8601Date](/graphql-api/api-reference/objects/iso-8601-date.md))      | Filter orders with a shipment date on or later than.                    |
| shipmentDateTo ([ISO8601Date](/graphql-api/api-reference/objects/iso-8601-date.md))        | Filter orders with a shipment date on or prior to.                      |
| after ([String](/graphql-api/api-reference/objects/string.md))                             | Returns the elements in the list that come after the specified cursor.  |
| before ([String](/graphql-api/api-reference/objects/string.md))                            | Returns the elements in the list that come before the specified cursor. |
| first ([Int](/graphql-api/api-reference/objects/int.md))                                   | Returns the first *n* elements from the list.                           |
| last ([Int](/graphql-api/api-reference/objects/int.md))                                    | Returns the last *n* elements from the list.                            |

#### paidAmount ([Float](/graphql-api/api-reference/objects/float.md))

The amount that is succesfully paid so far.

#### pausedAt ([ISO8601DateTime](/graphql-api/api-reference/objects/iso-8601-date-time.md))

The time the subscription was paused.

#### pausedUntil ([ISO8601DateTime](/graphql-api/api-reference/objects/iso-8601-date-time.md))

The time the subscription will be automatically resumed.

#### paymentMethod ([String](/graphql-api/api-reference/objects/string.md))

The payment method currently in use for billing

#### paymentMethodSummary ([String](/graphql-api/api-reference/objects/string.md))

The last 4 digits of the current payment method.

#### paymentMethodTranslated ([String](/graphql-api/api-reference/objects/string.md))

Localised string of the payment method currently in use for billing.

#### phoneNumber ([String](/graphql-api/api-reference/objects/string.md))

The customer's full international phone number

#### pickupPoint ([PickupPoint](/graphql-api/api-reference/objects/pickup-point.md))

The pickup point associated with this subscription, if delivery method is pickup\_point.

#### products (\[[Product](/graphql-api/api-reference/objects/product.md)!])

List of products the subscription is on (via orderedProducts).

#### ~~project (~~[~~Project~~](/graphql-api/api-reference/objects/project.md)~~!)~~

*`Deprecated: Will be removed.`*

#### ~~projectId (~~[~~ID~~](/graphql-api/api-reference/objects/id.md)~~!)~~

*`Deprecated: Will be removed.`*

#### pspPaymentMethodDetails ([JSON](/graphql-api/api-reference/objects/json.md))

The payment method details returned by PSP currently used for billing.

#### referrerCode ([DiscountCode](/graphql-api/api-reference/objects/discount-code.md))

The unique referral code this subscription can share with others.

#### rejectedAt ([ISO8601DateTime](/graphql-api/api-reference/objects/iso-8601-date-time.md))

The date and time when the subscription was rejected.

#### salutation ([String](/graphql-api/api-reference/objects/string.md))

The customer's salutation (mr,ms,mx).

#### serviceChannel ([ServiceChannel](/graphql-api/api-reference/objects/service-channel.md))

Returns the service channel this subscription has signed up to

#### shippingMethodId ([ID](/graphql-api/api-reference/objects/id.md))

The ID of the shipping method used for this subscription.

#### shippingNotes ([String](/graphql-api/api-reference/objects/string.md))

The customer's shipping notes (delivery instructions).

#### signupCompletedAt ([String](/graphql-api/api-reference/objects/string.md))

The date and time when the subscription completed their signup and made their initial payment (or no payment if free).

#### skipAutoActivationOnSignup ([Boolean](/graphql-api/api-reference/objects/boolean.md)!)

If true then the subscription won't be activated after signup and initial payment.

#### startDate ([ISO8601DateTime](/graphql-api/api-reference/objects/iso-8601-date-time.md)!)

The date and time when this subscription was (or will be) charged for the first time.

#### state ([String](/graphql-api/api-reference/objects/string.md))

The customer's state

#### status ([SubscriptionStatus](/graphql-api/api-reference/objects/subscription-status.md)!)

Status of this customer.

#### stoppedAt ([ISO8601DateTime](/graphql-api/api-reference/objects/iso-8601-date-time.md))

The date and time when the subscription was automatically stopped.

#### subscribedPlan ([SubscribedPlan](/graphql-api/api-reference/objects/subscribed-plan.md))

Returns the plan relationship and contract terms of the current plan

#### subscriptionAcceptanceChecks ([SubscriptionAcceptanceCheckConnection](/graphql-api/api-reference/objects/subscription-acceptance-check-connection.md))

List of acceptance checks of this subscription

| Argument                                                        | Description                                                             |
| --------------------------------------------------------------- | ----------------------------------------------------------------------- |
| after ([String](/graphql-api/api-reference/objects/string.md))  | Returns the elements in the list that come after the specified cursor.  |
| before ([String](/graphql-api/api-reference/objects/string.md)) | Returns the elements in the list that come before the specified cursor. |
| first ([Int](/graphql-api/api-reference/objects/int.md))        | Returns the first *n* elements from the list.                           |
| last ([Int](/graphql-api/api-reference/objects/int.md))         | Returns the last *n* elements from the list.                            |

#### subscriptionAccount ([SubscriptionAccount](/graphql-api/api-reference/objects/subscription-account.md))

The subscription account this subscription belongs to.

#### subscriptionAccountId ([ID](/graphql-api/api-reference/objects/id.md))

ID of the subscription account this subscription belongs to.

#### subscriptionFiles (\[[SubscriptionFile](/graphql-api/api-reference/objects/subscription-file.md)!]!)

Files attached to this subscription.

#### termsAccepted ([Boolean](/graphql-api/api-reference/objects/boolean.md)!)

Whether the customer accepted the terms and conditions.

#### termsAcceptedOn ([String](/graphql-api/api-reference/objects/string.md))

Whether the customer has accepted the terms\&conditions.

#### token ([String](/graphql-api/api-reference/objects/string.md))

Unique token of the subscription

#### trialPeriodMonths ([Int](/graphql-api/api-reference/objects/int.md))

The number of months before customer is charged for the first time.

#### updatePaymentMethodUrl ([String](/graphql-api/api-reference/objects/string.md))

Send your customer to this URL to allow them to update their active payment method.

#### updatedAt ([String](/graphql-api/api-reference/objects/string.md))

The date and time when the subscription was last updated.

#### vatNumber ([String](/graphql-api/api-reference/objects/string.md))

The company's VAT number.

#### verifiedIdentity ([SubscriptionIdentity](/graphql-api/api-reference/objects/subscription-identity.md))

Details of the verified identity if present.

#### versions ([VersionConnection](/graphql-api/api-reference/objects/version-connection.md))

Version history (audit log) of this subscription.

| Argument                                                        | Description                                                             |
| --------------------------------------------------------------- | ----------------------------------------------------------------------- |
| after ([String](/graphql-api/api-reference/objects/string.md))  | Returns the elements in the list that come after the specified cursor.  |
| before ([String](/graphql-api/api-reference/objects/string.md)) | Returns the elements in the list that come before the specified cursor. |
| first ([Int](/graphql-api/api-reference/objects/int.md))        | Returns the first *n* elements from the list.                           |
| last ([Int](/graphql-api/api-reference/objects/int.md))         | Returns the last *n* elements from the list.                            |

#### zipcode ([String](/graphql-api/api-reference/objects/string.md))

The customer's postal code or zipcode.