# The subscription model

Source: https://developers.swell.is/backend-api/subscriptions/the-subscription-model

The subscription model represents a recurring order that is associated with a user's account and billed at regular intervals.

## Fields

- `id` (objectId): Unique identifier for the subscription.
- `account_id` (objectId): ID of the subscribed customer's account.
- `account` (Account): Expandable link to the subscribed customer's account.
- `product_id` (objectId): ID of the [subscription plan](https://developers.swell.is/backend-api/subscription-plans) product.
- `product` (Product): Expandable link to the subscription plan product.
- `active` (boolean): Indicates the subscription is currently active. Default: `false`.
- `billing` (object): Subscription billing details.
  - `name` (string): Billing full name. If `first_name` or `last_name` are updated, then `name` will be automatically updated as a combination of first/last.
  - `first_name` (string): Billing first name. If `name` is updated, then `first_name` will be automatically updated as the first word of the name.
  - `last_name` (string): Billing last name. If `name` is updated, then `last_name` will be automatically updated as the first word of the name.
  - `address1` (string): Billing address line 1: street address/PO box/company name.
  - `address2` (string): Billing address line 2: apartment/suite/unit/building.
  - `city` (string): Billing city/district/suburb/town/village.
  - `state` (string): Billing state/county/province/region.
  - `vat_number` (string): VAT number associated with the billing address, if applicable.
  - `zip` (string): Billing zip/postal code.
  - `country` (string): Two-letter ISO code country code.
  - `phone` (string): Billing phone number.
  - `method` (string): Method of payment. Can be `card`, `account`, `amazon`, `paypal`, or any one of the manual methods defined in payment settings.
  - `card` (object)
    - `token` (string, required): Token generated by Swell Checkout or Stripe.js.
    - `exp_month` (int): Two-digit number representing the credit card expiration month.
    - `exp_year` (int): Four-digit number representing the credit card expiration year.
    - `brand` (string): Credit card brand. Can be `American Express`, `Diners Club`, `Discover`, `JCB`, `MasterCard`, `UnionPay`, `Visa`, or `Unknown`.
    - `display_brand` (string): Brand of the card displayed to the customer, if different from the underlying brand (for example, co-branded cards).
    - `last4` (string): Last four digits of the card number.
    - `gateway` (string): ID of the payment gateway that should be used to process payments.
    - `test` (boolean): Indicates this is a test card.
    - `address_check` (string): When used with a payment gateway that performs address checks and `address1` was provided, can be `pass`, `fail`, `unavailable`, or `unchecked`.
    - `zip_check` (string): When used with a payment gateway that performs address checks and `zip` was provided, can be `pass`, `fail`, `unavailable`, or `unchecked`.
    - `cvc_check` (string): When used with a payment gateway that performs CVC code checks and `cvc` was provided, can be `pass`, `fail`, `unavailable`, or `unchecked`.
  - `intent` (object): Stores the necessary information about the payment. This is typically the payment ID returned by the gateway after payment is initialized.
  - `default` (boolean): Indicates billing details represent the customer's default payment method.
  - `use_account` (boolean): When `true`, inherits the address tied to the user's account.
  - `account_card_id` (objectId): ID of the customer's credit card on file, if applicable.
  - `account_card` (account_card): Expandable link to the customer's credit card on file, if applicable.
- `billing_schedule` (object): Billing schedule for subscription plan.
  - `interval` (enum): Subscription plan billing interval. Can be `daily`, `weekly`, `monthly`, or `yearly`. Possible values: `monthly`, `daily`, `weekly`, `yearly`.
  - `interval_count` (int): Multiplier for billing interval. For example, to make the billing cycle once every two weeks, set `interval=weekly` and `interval_count=2`. Default: `1`.
  - `trial_days` (int): Number of days offered as a free trial on the subscription plan before the customer is billed. If a subscription is canceled by the last day of the trial period, an invoice won't be issued.
  - `limit` (int): Specifies a limit to the number of billing cycles for the subscription plan. For example, `"limit"=10` would stop billing the customer after the tenth billing cycle.
  - `limit_current` (int): Current number of billing cycles that have occured.
  - `date_limit_end` (date): Limit date for marking the end of the billing cycle.
- `bundle_item_id` (objectId): ID of the corresponding bundle item, if applicable.
- `cancel_at_end` (boolean): When `true`, indicates the subscription was or will be canceled at the end of the billing period.
- `cancel_at_schedule` (boolean): Determines whether the subscription is canceled immediately or according to a specified schedule.
- `cancel_reason` (string): A brief message describing the reason the subscription was canceled, if applicable.
- `canceled` (boolean): Indicates the subscription was canceled.
- `complete` (boolean): Indicates the subscription plan has completed all cycles.
- `coupon` (Coupon): Expandable link to the coupon applied to the subscription.
- `coupon_code` (string): Coupon code applied to the subscription. See [coupons](https://developers.swell.is/backend-api/coupons/the-coupon-model) for details.
- `coupon_id` (objectId): ID of the coupon applied to the subscription.
- `currency` (string): Three-letter ISO currency code in uppercase. Defaults to the store's base currency.
- `currency_rate` (float): Currency rate used in calculating the fixed amount.
- `date_canceled` (date): Date the subscription was canceled, if applicable.
- `date_cancel_at` (date): Cancel the subscription on the specified date.
- `date_uncanceled` (date): Date when the subscription was un-canceled and restored to active status.
- `date_created` (date, auto): Date and time the subscription was created.
- `date_order_cycle_start` (date): Deprecated: use `date_order_period_start` instead. Start date for the subscription order cycle.
- `date_order_period_end` (date): End date for the subscription order period.
- `date_order_period_start` (date): Start date for the subscription order period.
- `date_pause_end` (date): Date the subscription was unpaused, if applicable.
- `date_paused` (date): Date the subscription was paused, if applicable.
- `date_pause_at` (date): Pause the subscription on the specified date.
- `date_payment_expiring` (date, auto): Date when the customer's current default credit card will expire, used to notify the customer to update their payment information before their card expires.
- `date_payment_failed` (date): Date when the last automated payment failed, if applicable.
- `date_payment_retry` (date, auto): When automated payment has failed, this is the date when the system will automatically retry.
- `date_period_end` (date, auto): End date of the current billing period.
- `date_period_start` (date): Start date of the current billing period. Default: `null`.
- `date_prorated` (date): Date the subscription was last prorated, if applicable. Used to calculate the charge or credit applied when the subscription is prorated.
- `date_resumed` (date): The date a subscription was resumed.
- `date_trial_end` (date): Date the trial period did end in the past or will end in the future. Changing this value can be used to update the billing period of a subscription with or without a trial. For example, to set the monthly billing date to the 1st of the month, update `date_trial_end` to the first of the next month.
- `date_trial_start` (date): Date the trial period started, if applicable.
- `date_updated` (date, auto): Date and time the subscription was last updated.
- `discount_total` (currency): Total discount amount.
- `discounts` (array of object): List of all discounts applied to the subscription.
  - `id` (string): Unique identifier for the object.
  - `amount` (currency): Fixed discount amount.
  - `rule` (object): Object describing the discount rule details. Custom discounts don't require this value.
  - `source_id` (objectId): ID of the source object that generated the discount, such as a coupon or promotion.
  - `type` (enum): Type of discount. Can be `coupon` or `sale` referring to the source of the discount. Custom discounts don't require this value. Possible values: `sale`, `coupon`.
- `draft` (boolean): Indicates the subscription is a draft.
- `grand_total` (currency): Grand total of the next invoice including line items and taxes.
- `invoice_total` (currency): Amount invoiced for the last billing period.
- `invoices` (Invoice): Expandable list of all invoices created by the subscription.
- `item_discount` (currency, auto): Total discount applied to line items.
- `item_tax` (currency): Total taxes applied to line items.
- `item_total` (currency, auto): Amount invoiced for the last billing period.
- `items` (array of object): List of invoice line items added to the subscription. Recurring items are charged repeatedly, otherwise they are charged on the next invoice and then removed from the subscription.
  - `id` (objectId, auto): Unique identifier for the object.
  - `bundle_items` (array of object): List of products sold as a bundle. Applicable only when `bundle=true`.
    - `id` (objectId): Unique identifier for the bundle item.
    - `product_id` (objectId): ID of the bundled product.
    - `product` (product): Expandable link to the bundled product.
    - `quantity` (int): Quantity of the bundled product. Defaults to 1. Default: `1`.
    - `price` (currency): Price of the bundle item.
    - `discount_each` (currency): Discount amount applied to each unit of the bundle item.
    - `tax_each` (currency): Tax amount applied to each unit of the bundle item.
    - `amount_ratio` (float): Ratio of the bundle price allocated to this item.
    - `variant_id` (objectId): ID of the bundled variant, if applicable.
    - `variant` (variant): Expandable link to the bundled product variant, if applicable.
    - `quantity_total` (int): Total quantity of bundle items.
  - `date_created` (date, auto): Date and time the object was created.
  - `description` (string): A long-form description of the options. May contain HTML or other markup languages.
  - `discount_each` (currency): Total discount amount divided by quantity.
  - `discount_total` (currency): Total discount applied to the item.
  - `discounts` (array of object): List of discounts applied to the line item by [coupons](https://developers.swell.is/backend-api/coupons/the-coupon-model).
    - `id` (string): Unique identifier for the object.
    - `amount` (currency): Fixed discount amount.
  - `options` (array of object): Item options matching one or more of `product.options`, if applicable. When setting this value, specify either option `id` or `name` (case-insensitive) to identify the option.
    - `id` (string): Unique identifier for the object.
    - `name` (string): Name of the option. Populated automatically when adding an option by ID.
    - `price` (currency): Price of the option added to plan price when selected.
    - `shipment_weight` (float): If specified, shipping is calculated using this weight. Otherwise, Swell assumes 1 lb/oz/kg — depending on store's default weight unit.
    - `value` (string): Name value of the option. When setting this value, specify either the product option value `id` or `name` (case-insensitive) to identify the value.
    - `variant` (boolean): Indicates the option refers to a variant aspect.
    - `value_id` (objectId)
  - `price` (currency): Price of the line item. Defaults to product price, if applicable. A negative value will be subtracted from the plan total and credited to the customer on their next invoice.
  - `price_total` (currency): Total price of the line item (`price * quantity`).
  - `product_id` (objectId): ID of the item product, if applicable.
  - `product` (product): Expandable link to the item product, if applicable.
  - `proration` (boolean): Indicates the item represents a proration charge or credit.
  - `quantity` (int): Quantity of the line item. Default: `1`.
  - `recurring` (boolean): Indicates the item will remain on the subscription after the next invoice is created.
  - `recurring_discount_each` (currency): Total recurring discount amount divided by quantity, if applicable.
  - `recurring_discount_total` (currency): Total recurring discount applied to the item, if applicable.
  - `recurring_price` (currency): Recurring price of the item, if applicable.
  - `recurring_price_total` (currency): Total recurring price of the item (`price * quantity`), if applicable.
  - `recurring_tax_each` (currency): Total recurring tax amount divided by quantity, if applicable.
  - `recurring_tax_total` (currency): Total recurring tax applied to the item, if applicable.
  - `tax_each` (currency): Total tax amount divided by quantity.
  - `tax_total` (currency): Total tax applied to the item.
  - `taxes` (array of object): List of tax rules applied to the item based on tax settings.
    - `id` (string): Unique identifier for the object.
    - `amount` (currency): Fixed tax amount.
  - `variant_id` (objectId): ID of the item variant, if applicable.
  - `variant` (variant): Expandable link to the item variant, if applicable.
  - `delivery` (enum): Delivery frequency for the item. Possible values: `shipment`, `giftcard`.
  - `proration_product_id` (objectId)
- `notes` (string): Internal admin notes. These are not visible to the customer. This field holds a single block of text. To record a series of notes against the subscription, each attributed to a user, see [Notes](https://developers.swell.is/backend-api/notes).
- `number` (string, auto): The order number for the subscription, based on the store order number format.
- `options` (array of object): Plan options matching one or more of `product.options`. When setting this value, specify either option `id` or `name` (case-insensitive) to identify the option.
  - `id` (string): Unique identifier for the object.
  - `name` (string): Name of the plan option. Populated automatically when adding an option by ID.
  - `price` (currency): Price of the option added to plan price when selected.
  - `value` (string): Name value of the plan option. When setting this value, specify either value `id` or `name` (case-insensitive) to identify the value.
  - `variant` (boolean): Indicates the option refers to a variant aspect.
  - `value_id` (objectId)
  - `shipment_weight` (float)
- `order_id` (objectId): ID of the order that originated the subscription, if applicable.
- `order_item_id` (objectId): ID of the line item from the order that originated the subscription, if applicable.
- `order_schedule` (object): Order schedule for the subscription plan.
  - `interval` (enum): Order interval for subscription plan. Can be `monthly`, `daily`, weekly, and `yearly`. Possible values: `monthly`, `daily`, `weekly`, `yearly`.
  - `interval_count` (int): Multiplier for order interval. For example, to generate the subscription order once every two weeks, set `interval=weekly` and `interval_count=2`. Default: `1`.
  - `limit` (int): Specifies a limit to the number of orders created. For example, `"limit"=10` would stop creating orders after the tenth order.
  - `date_limit_end` (date): Designates the end date of the order cycle.
  - `limit_current` (int)
- `ordering` (boolean): Indicates the subscription is actively placing orders.
- `orders` (Order): Expandable list of all orders created by the subscription plan. This happens when a plan contains physical products as `bundle_items`.
- `paid` (boolean, auto): Indicates the last invoice was fully paid. Default: `false`.
- `pause_at_end` (boolean): Determines whether the subscription is paused at the end of the current billing period.
- `pause_at_schedule` (boolean): Determines whether the subscription is paused immediately or according to the schedule.
- `pause_skip_cycles` (int): Number of billing cycles to skip while the subscription is paused.
- `payment_balance` (currency, auto): Balance of payments on the invoice for the last billing period. A negative number indicates payment is owed, while a positive balance indicates refund is due. Zero balance indicates the invoice was fully paid.
- `payment_total` (currency): Total amount of payments for the last billing period.
- `payments` (Payment): Expandable list of all payments made on behalf of the subscription.
- `pending_invoices` (Invoice): Expandable list of invoices that haven't been fully paid.
- `plan_id` (objectId): ID of the subscription plan.
- `plan_name` (string): Name of the subscription plan.
- `price` (currency): Price of the plan. Plan price can be overridden when creating or updating a subscription.
- `price_total` (currency, auto): Total price of the plan (`price * quantity`).
- `product_discount_each` (currency, auto): Total discount amount of the subscription plan, divided by quantity.
- `product_discount_total` (currency, auto): Total discount applied to the subscription plan.
- `product_discounts` (array of object): List of discounts applied to the subscription plan by [coupons](https://developers.swell.is/backend-api/coupons/the-coupon-model).
  - `id` (string): ID of the coupon applied for a discount.
  - `amount` (currency): Discount amount.
- `product_name` (string): This field is a copy of the item's `product.name`. Default: `{"$formula":"if(product_id, product.name, null)"}`.
- `product_tax_each` (currency, auto): Total tax amount of the subscription plan, divided by quantity.
- `product_tax_total` (currency, auto): Total tax applied to the subscription plan.
- `product_taxes` (array of object, auto): List of tax rules applied to the subscription plan based on tax settings.
  - `id` (string): Unique identifier for the object. Refers to one of the ids in the subscription `taxes` object.
  - `amount` (currency): Fixed tax amount.
- `prorated` (boolean): When `false`, indicates the subscription should not be prorated if the plan product is changed, otherwise a prorated charge or credit will be added at the appropriate time.
- `quantity` (int): Quantity of the plan to charge. Default: `1`.
- `recurring_discount_total` (currency, auto): Total recurring discount applied to the subscription including line items.
- `recurring_item_discount` (currency, auto): Total discount applied to recurring line items.
- `recurring_item_tax` (currency, auto): Total taxes applied to recurring line items.
- `recurring_item_total` (currency, auto): Sum of all recurring line items before discounts and taxes.
- `recurring_tax_included_total` (currency, auto): Total of taxes applied separately from the subscription plan and recurring line items.
- `recurring_tax_total` (currency, auto): Total taxes applied to the subscription including recurring line items.
- `recurring_total` (currency, auto): Recurring total of the subscription including line items and taxes.
- `refund_total` (currency): Total amount of refunds for the last billing period.
- `refunds` (Refund): Expandable list of all refunds made on behalf of the subscription.
- `status` (enum, auto): Current status of the subscription. Can be `pending`, `draft`, `complete`, `paused`, `active`, `trial`, `pastdue`, `unpaid`, or `canceled`. Possible values: `pending`, `draft`, `complete`, `paused`, `active`, `trial`, `pastdue`, `unpaid`, `canceled`. Default: `"pending"`.
- `sub_total` (currency, auto): Sum of all line items before discounts and taxes.
- `tax_included` (boolean, auto): Indicates the subscription plan price includes taxes.
- `tax_included_total` (currency, auto): Total of taxes applied separately from the subscription plan and line items.
- `tax_total` (currency, auto): Total taxes applied to the subscription including line items.
- `taxes` (array of object, auto): List of taxes applied to the subscription.
  - `id` (string): Unique identifier for the object.
  - `amount` (currency): Fixed tax amount.
  - `name` (string): Name of the tax rule. For example "NY Sales Tax".
  - `priority` (int): Priority indicates the order in which a tax rule was applied. Higher priority rules are added on top of other tax rules with a lower priority. Rules with the same priority are calculated excluding each other.
  - `rate` (float): Tax percentage used in calculating the fixed amount.
- `taxes_fixed` (boolean): When true, taxes are not applied to the subscription. When false, taxes are calculated and applied to the subscription.
- `trial` (boolean, auto): Indicates the subscription is in a trial period and the first invoice will be issued on `date_trial_end`.
- `unpaid` (boolean, auto): Indicates the last invoice was marked as unpaid. This occurs automatically after all payment attempts are exhausted, as configured in subscription settings. Default: `false`.
- `variant` (Product variant): Expandable link to the subscription plan variant, if applicable.
- `variant_id` (objectId): ID of the subscription plan variant, if applicable.
- `variant_name` (string): Name of the variant.