# Subscriptions

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

Subscriptions allow charging a customer on a recurring basis. A subscription is created when a customer purchases a plan from a product's `subscription` `purchase_option`. In addition to the plan, subscriptions can have line items that are charged on a recurring basis or just once—depending on the use case. Orders can be automatically generated every time a subscription is for a physical product, or a product that contains physical `bundle_items`.

## 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.


## Create a subscription

Create a new subscription to bill a customer for a product on a recurring schedule.

`trial_days` or `date_trial_end` being set means no invoices will be created; otherwise, the customer's default billing card will be charged immediately. If the charge fails, this will return a validation error describing the failure and an invoice will not be created. If the charge succeeds, an invoice will be created and paid by the charge immediately.

### Arguments

- `account_id` (objectId, required): ID of the subscribed customer's account.
- `product_id` (objectId, required): ID of the [subscription plan](https://developers.swell.is/backend-api/subscription-plans) product. When changing the subscription product, the difference in price is prorated by adding a line item. The customer will be charged or credited the difference on their next invoice.
- `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.
  - `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): 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`.
    - `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.
- `coupon_code` (string): Coupon code applied to the subscription. See [coupons](#coupons) for details.
- `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)
  - `name` (string)
  - `value` (string)
  - `value_id` (objectId)
  - `variant` (boolean)
  - `price` (currency)
  - `shipment_weight` (float)
- `quantity` (int): Quantity of the plan to charge. Default: `1`.
- `account` (Account): Expandable link to the subscribed customer's account.
- `active` (boolean): Indicates the subscription is currently active. Default: `false`.
- `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_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_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_order_cycle_start` (date): Start date fo the subscription order cycle.
- `date_order_period_end` (date): End date for the subscription order period.
- `date_order_period_start` (date): Start date of the subscription order cycle.
- `date_pause_end` (date): Date the subscription was unpaused, if applicable.
- `date_paused` (date): Date the subscription was paused, if applicable.
- `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.
- `discount_total` (currency): Total discount amount.
- `discounts` (array of object): List of all discounts applied to the subscription.
  - `id` (string)
  - `type` (enum): Possible values: `sale`, `coupon`.
  - `rule` (object)
  - `amount` (currency)
- `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)
  - `date_created` (date, auto)
  - `quantity` (int): Default: `1`.
  - `price` (currency)
  - `price_total` (currency)
  - `description` (string)
  - `delivery` (enum): Possible values: `shipment`, `giftcard`.
  - `options` (array of object)
    - `id` (string)
    - `name` (string)
    - `value` (string)
    - `value_id` (objectId)
    - `variant` (boolean)
    - `price` (currency)
    - `shipment_weight` (float)
  - `bundle_items` (array of object)
    - `id` (objectId)
    - `quantity` (int)
    - `quantity_total` (int)
    - `product_id` (objectId)
    - `product` (product)
    - `variant_id` (objectId)
    - `variant` (variant)
  - `proration` (boolean)
  - `proration_product_id` (objectId)
  - `recurring` (boolean)
  - `recurring_price` (currency)
  - `recurring_price_total` (currency)
  - `discounts` (array of object)
    - `id` (string)
    - `amount` (currency)
  - `discount_total` (currency)
  - `discount_each` (currency)
  - `recurring_discount_total` (currency)
  - `recurring_discount_each` (currency)
  - `taxes` (array of object)
    - `id` (string)
    - `amount` (currency)
  - `tax_total` (currency)
  - `tax_each` (currency)
  - `recurring_tax_total` (currency)
  - `recurring_tax_each` (currency)
  - `product_id` (objectId)
  - `product` (product)
  - `variant_id` (objectId)
  - `variant` (variant)
- `notes` (string): Internal admin notes. These are not visible to the customer.
- `number` (string, auto): The order number for the subscription, based on the store order number format.
- `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`.
- `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` (Product): Expandable link to the subscription plan product.
- `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)
  - `amount` (currency)
- `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)
  - `amount` (currency)
- `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.
- `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)
  - `name` (string)
  - `priority` (int)
  - `rate` (float)
  - `amount` (currency)
- `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.

### Example request

`POST /subscriptions`

**cURL**

```bash
$ curl https://api.swell.store/subscriptions \
  -u store-id:secret-key \
  -d billing.first_name=John \
  -d billing.last_name=Doe \
  -d billing.address1=123 Main Street \
  -d billing.address2=Apt. 100 \
  -d billing.city=Anytown \
  -d billing.state=CA \
  -d billing.zip=12345 \
  -d billing.country=US \
  -d billing.phone=123-456-7890 \
  -d billing.method=credit_card \
  -d product_id=62b1e30767145000197b2bbf \
  -d product_name=Skooma \
  -d variant_id=62b1e30767145000197b2bc0 \
  -d price=75 \
  -d quantity=1 \
  -d price_total=75 \
  -d options[0].id=Monthly \
  -d options[0].value=99
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.post('/subscriptions', {
  billing: {
    first_name: 'John',
    last_name: 'Doe',
    address1: '123 Main Street',
    address2: 'Apt. 100',
    city: 'Anytown',
    state: 'CA',
    zip: 12345,
    country: 'US',
    phone: '123-456-7890',
    method: 'credit_card'
  },
  product_id: '62b1e30767145000197b2bbf',
  product_name: 'Skooma',
  variant_id: '62b1e30767145000197b2bc0',
  price: 75,
  quantity: 1,
  price_total: 75,
  options: [
    {
      id: 'Monthly',
      value: 99
    }
  ]
});
```

**PHP**

```php
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->post('/subscriptions', [
   'billing' => [
    'first_name' => 'John',
    'last_name' => 'Doe',
    'address1' => '123 Main Street',
    'address2' => 'Apt. 100',
    'city' => 'Anytown',
    'state' => 'CA',
    'zip' => 12345,
    'country' => 'US',
    'phone' => '123-456-7890',
    'method' => 'credit_card'
  ],
  'product_id' => '62b1e30767145000197b2bbf',
  'product_name' => 'Skooma',
  'variant_id' => '62b1e30767145000197b2bc0',
  'price' => 75,
  'quantity' => 1,
  'price_total' => 75,
  'options' => [
    [
      'id' => 'Monthly',
      'value' => 99
    ]
  ]
]);
```

### Example response

```json
{
  "id": "60f199509111e7000000009a",
  "account_id": "60f199509111e700000000a9",
  "product_id": "60f199509111e700000000aa",
  "active": true,
  "cancel_at_end": false,
  "cancel_reason": null,
  "canceled": false,
  "currency": "USD",
  "date_canceled": null,
  "date_created": "2021-07-16T14:36:00.483Z",
  "date_payment_expiring": "2031-01-01T08:00:00.000Z",
  "date_payment_failed": null,
  "date_payment_retry": null,
  "date_period_end": "2019-03-24T04:28:12.962Z",
  "date_period_start": "2019-02-24T04:28:12.962Z",
  "date_trial_end": "2019-02-24T04:28:12.962Z",
  "date_trial_start": "2019-01-24T04:28:12.962Z",
  "date_updated": "2021-07-16T14:36:00.483Z",
  "discount_total": 0,
  "discounts": null,
  "grand_total": 148.8946,
  "interval": "monthly",
  "interval_count": 1,
  "invoice_total": 99,
  "item_discount": 0,
  "item_tax": 0,
  "item_total": 49.8946,
  "items": [
    {
      "id": "5ca537326a0ec32a521139dd",
      "date_created": "2019-03-24T22:56:33.467Z",
      "description": "Remaining time on Example Subscription",
      "proration": true,
      "quantity": 1,
      "price": 49.8946,
      "price_total": 49.8946,
      "recurring_price": 0,
      "recurring_price_total": 0,
      "discount_total": 0,
      "discount_each": 0,
      "recurring_discount_total": 0,
      "recurring_discount_each": 0,
      "tax_total": 0,
      "tax_each": 0,
      "recurring_tax_total": 0,
      "recurring_tax_each": 0
    }
  ],
  "notes": null,
  "options": [
    {
      "id": "5becb84fac207653a4816ee5",
      "name": "Plan",
      "value": "Monthly"
    }
  ],
  "order_id": "60f199509111e7000000009d",
  "order_item_id": "60f199509111e7000000009e",
  "paid": true,
  "payment_balance": 0,
  "payment_total": 99,
  "price": 99,
  "price_total": 99,
  "product_discount_each": 0,
  "product_discount_total": 0,
  "product_discounts": null,
  "product_tax_each": 0,
  "product_tax_total": 0,
  "product_taxes": null,
  "quantity": 1,
  "recurring_discount_total": 0,
  "recurring_item_discount": 0,
  "recurring_item_tax": 0,
  "recurring_item_total": 0,
  "recurring_tax_included_total": 0,
  "recurring_tax_total": 0,
  "recurring_total": 99,
  "refund_total": 0,
  "status": "active",
  "sub_total": 148.8946,
  "tax_included_total": 0,
  "tax_total": 0,
  "taxes": null,
  "trial": false,
  "trial_days": 14,
  "unpaid": false,
  "variant_id": "60f199509111e7000000009f"
}
```


## Retrieve a subscription

Retrieve an existing subscription using the ID that was returned when created.

### Arguments

- `id` (objectId, required): The id of the subscription to retrieve.
- `expand` (string): Expanding link fields and child collections is performed using the expand argument.

  - For example, `expand=account` would return a related customer account if one exists.

  When the field represents a collection, you can specify the query limit.

  - For example, `expand=variants:10` would return up to 10 records of the variants collection.

  See [expanding ](https://developers.swell.is/backend-api/querying/expanding)for more details.
- `fields` (string): Return only the specified fields in the result. For example `fields=name,slug` would return only the fields `name` and `slug` in the response. Supports nested object and array fields using dot-notation, for example, `items.product_id`. The category `id` is always returned.
- `include` (string): Include one or more arbitrary queries in the response, possibly related to the main query.

  See [including ](https://developers.swell.is/backend-api/querying/including)for more details.

### Example request

`GET /subscriptions/:id`

**cURL**

```bash
$ curl https://api.swell.store/subscriptions/60f199509111e700000000b1 \
  -u store-id:secret-key
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.get('/subscriptions/60f199509111e700000000b1');
```

**PHP**

```php
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/subscriptions/60f199509111e700000000b1');

?>
```

### Example response

```json
{
  "id": "60f199509111e700000000b1",
  "account_id": "60f199509111e700000000b2",
  "product_id": "60f199509111e700000000b3",
  "active": true,
  "cancel_at_end": false,
  "cancel_reason": null,
  "canceled": false,
  "currency": "USD",
  "date_canceled": null,
  "date_created": "2021-07-16T14:36:00.483Z",
  "date_payment_expiring": "2031-01-01T08:00:00.000Z",
  "date_payment_failed": null,
  "date_payment_retry": null,
  "date_period_end": "2019-03-24T04:28:12.962Z",
  "date_period_start": "2019-02-24T04:28:12.962Z",
  "date_trial_end": "2019-02-24T04:28:12.962Z",
  "date_trial_start": "2019-01-24T04:28:12.962Z",
  "date_updated": "2021-07-16T14:36:00.483Z",
  "discount_total": 0,
  "discounts": null,
  "grand_total": 148.8946,
  "interval": "monthly",
  "interval_count": 1,
  "invoice_total": 99,
  "item_discount": 0,
  "item_tax": 0,
  "item_total": 49.8946,
  "items": [
    {
      "id": "5ca537326a0ec32a521139dd",
      "date_created": "2019-03-24T22:56:33.467Z",
      "description": "Remaining time on Example Subscription",
      "proration": true,
      "quantity": 1,
      "price": 49.8946,
      "price_total": 49.8946,
      "recurring_price": 0,
      "recurring_price_total": 0,
      "discount_total": 0,
      "discount_each": 0,
      "recurring_discount_total": 0,
      "recurring_discount_each": 0,
      "tax_total": 0,
      "tax_each": 0,
      "recurring_tax_total": 0,
      "recurring_tax_each": 0
    }
  ],
  "notes": null,
  "options": [
    {
      "id": "5becb84fac207653a4816ee5",
      "name": "Plan",
      "value": "Monthly"
    }
  ],
  "order_id": "60f199509111e7000000009d",
  "order_item_id": "60f199509111e7000000009e",
  "paid": true,
  "payment_balance": 0,
  "payment_total": 99,
  "price": 99,
  "price_total": 99,
  "product_discount_each": 0,
  "product_discount_total": 0,
  "product_discounts": null,
  "product_tax_each": 0,
  "product_tax_total": 0,
  "product_taxes": null,
  "quantity": 1,
  "recurring_discount_total": 0,
  "recurring_item_discount": 0,
  "recurring_item_tax": 0,
  "recurring_item_total": 0,
  "recurring_tax_included_total": 0,
  "recurring_tax_total": 0,
  "recurring_total": 99,
  "refund_total": 0,
  "status": "active",
  "sub_total": 148.8946,
  "tax_included_total": 0,
  "tax_total": 0,
  "taxes": null,
  "trial": false,
  "trial_days": 14,
  "unpaid": false,
  "variant_id": "60f199509111e7000000009f"
}
```


## Update a subscription

Update an existing subscription using the ID that was returned when created. Updating performs a merge operation. To explicitly override values such as arrays, use the `$set` operator.

### Arguments

- `id` (objectId, required): Unique identifier for the subscription.
- `account` (Account): Expandable link to the subscribed customer's account.
- `account_id` (objectId, required): ID of the subscribed customer's account.
- `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.
  - `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): 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`.
    - `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_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](#coupons) 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_order_cycle_start` (date): Start date fo 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_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.
- `discount_total` (currency): Total discount amount.
- `discounts` (array of object): List of all discounts applied to the subscription.
  - `id` (string)
  - `type` (enum): Possible values: `sale`, `coupon`.
  - `rule` (object)
  - `amount` (currency)
- `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)
  - `date_created` (date, auto)
  - `quantity` (int): Default: `1`.
  - `price` (currency)
  - `price_total` (currency)
  - `description` (string)
  - `delivery` (enum): Possible values: `shipment`, `giftcard`.
  - `options` (array of object)
    - `id` (string)
    - `name` (string)
    - `value` (string)
    - `value_id` (objectId)
    - `variant` (boolean)
    - `price` (currency)
    - `shipment_weight` (float)
  - `bundle_items` (array of object)
    - `id` (objectId)
    - `quantity` (int): Default: `1`.
    - `quantity_total` (int)
    - `product_id` (objectId)
    - `product` (product)
    - `variant_id` (objectId)
    - `variant` (variant)
  - `proration` (boolean)
  - `proration_product_id` (objectId)
  - `recurring` (boolean)
  - `recurring_price` (currency)
  - `recurring_price_total` (currency)
  - `discounts` (array of object)
    - `id` (string)
    - `amount` (currency)
  - `discount_total` (currency)
  - `discount_each` (currency)
  - `recurring_discount_total` (currency)
  - `recurring_discount_each` (currency)
  - `taxes` (array of object)
    - `id` (string)
    - `amount` (currency)
  - `tax_total` (currency)
  - `tax_each` (currency)
  - `recurring_tax_total` (currency)
  - `recurring_tax_each` (currency)
  - `product_id` (objectId)
  - `product` (product)
  - `variant_id` (objectId)
  - `variant` (variant)
- `notes` (string): Internal admin notes. These are not visible to the customer.
- `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)
  - `name` (string)
  - `value` (string)
  - `value_id` (objectId)
  - `variant` (boolean)
  - `price` (currency)
  - `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`.
- `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` (Product): Expandable link to the subscription plan product.
- `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)
  - `amount` (currency)
- `product_id` (objectId, required): ID of the [subscription plan](https://developers.swell.is/backend-api/subscription-plans) product. When changing the subscription product, the difference in price is prorated by adding a line item. The customer will be charged or credited the difference on their next invoice.
- `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)
  - `amount` (currency)
- `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)
  - `name` (string)
  - `priority` (int)
  - `rate` (float)
  - `amount` (currency)
- `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.

### Example request

`PUT /subscriptions/:id`

**cURL**

```bash
$ curl https://api.swell.store/subscriptions/60f199509111e700000000b1 \
  -u store-id:secret-key \
  -X PUT \
  -d quantity=2 \
  -d coupon_code=10OFF
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.put('/subscriptions/{id}', {
  id: '60f199509111e700000000b1',
  quantity: 2,
  coupon_code: '10OFF'
});
```

**PHP**

```php
<?php

use Swell\Client;

$swell = new Client('store-id', 'secret-key');

$swell->put('/subscriptions/{id}', [
  'id' => '60f199509111e700000000b1',
  'quantity' => 2,
  'coupon_code' => '10OFF'
]);

?>
```

### Example response

```json
{
  "id": "60f199509111e7000000009a",
  "account_id": "60f199509111e700000000a0",
  "product_id": "60f199509111e700000000a1",
  "active": true,
  "cancel_at_end": false,
  "cancel_reason": null,
  "canceled": false,
  "currency": "USD",
  "date_canceled": null,
  "date_created": "2021-07-16T14:36:00.483Z",
  "date_payment_expiring": "2031-01-01T08:00:00.000Z",
  "date_payment_failed": null,
  "date_payment_retry": null,
  "date_period_end": "2019-03-24T04:28:12.962Z",
  "date_period_start": "2019-02-24T04:28:12.962Z",
  "date_trial_end": "2019-02-24T04:28:12.962Z",
  "date_trial_start": "2019-01-24T04:28:12.962Z",
  "date_updated": "2021-07-16T14:36:00.483Z",
  "discount_total": 0,
  "discounts": null,
  "grand_total": 148.8946,
  "interval": "monthly",
  "interval_count": 1,
  "invoice_total": 99,
  "item_discount": 0,
  "item_tax": 0,
  "item_total": 49.8946,
  "items": [
    {
      "id": "5ca537326a0ec32a521139dd",
      "date_created": "2019-03-24T22:56:33.467Z",
      "description": "Remaining time on Skooma Subscription",
      "proration": true,
      "quantity": 1,
      "price": 49.8946,
      "price_total": 49.8946,
      "recurring_price": 0,
      "recurring_price_total": 0,
      "discount_total": 0,
      "discount_each": 0,
      "recurring_discount_total": 0,
      "recurring_discount_each": 0,
      "tax_total": 0,
      "tax_each": 0,
      "recurring_tax_total": 0,
      "recurring_tax_each": 0
    }
  ],
  "notes": null,
  "options": [
    {
      "id": "5becb84fac207653a4816ee5",
      "name": "Skooma delivery",
      "value": "Monthly"
    }
  ],
  "order_id": "60f199509111e7000000009d",
  "order_item_id": "60f199509111e7000000009e",
  "paid": true,
  "payment_balance": 0,
  "payment_total": 99,
  "price": 99,
  "price_total": 99,
  "product_discount_each": 0,
  "product_discount_total": 0,
  "product_discounts": null,
  "product_tax_each": 0,
  "product_tax_total": 0,
  "product_taxes": null,
  "quantity": 1,
  "recurring_discount_total": 0,
  "recurring_item_discount": 0,
  "recurring_item_tax": 0,
  "recurring_item_total": 0,
  "recurring_tax_included_total": 0,
  "recurring_tax_total": 0,
  "recurring_total": 99,
  "refund_total": 0,
  "status": "active",
  "sub_total": 148.8946,
  "tax_included_total": 0,
  "tax_total": 0,
  "taxes": null,
  "trial": false,
  "trial_days": 14,
  "unpaid": false,
  "variant_id": "60f199509111e7000000009f"
}
```


## Pausing and canceling

A subscription can be paused or canceled immediately, or scheduled to take effect on a future date. Both are driven by updating the subscription, and both distinguish intent from effect: `canceled` and `paused` record the intent, while `active` records whether the subscription is still running.

#### Canceling immediately

Set `canceled` to `true` with `cancel_at_end` set to `false`. When neither `cancel_at_end` nor `cancel_at_schedule` is already set on the subscription, sending `canceled` on its own cancels immediately too. The subscription is left with `canceled: true`, `active: false`, and `date_canceled` set to the current time.

**Cancel a subscription immediately**

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.put('/subscriptions/{id}', {
  id: '5c15505200c7d14d851e510f',
  canceled: true,
  cancel_at_end: false
});
```

#### Scheduling a cancellation

Send `canceled` together with `cancel_at_schedule`, or set the schedule first and confirm with `canceled` in a second request. The subscription is then `canceled: true` and `active: true`, with the calculated date in `date_cancel_at`. It keeps generating orders and invoices until that date, at which point `active` becomes `false` and `date_canceled` is set.

**Schedule a cancellation**

**Node**

```javascript
// Cancel on the next billing date
await swell.put('/subscriptions/{id}', {
  id: '5c15505200c7d14d851e510f',
  canceled: true,
  cancel_at_schedule: 'billing'
});

// Or cancel on a specific date
await swell.put('/subscriptions/{id}', {
  id: '5c15505200c7d14d851e510f',
  canceled: true,
  cancel_at_schedule: '2027-01-31T00:00:00.000Z'
});
```

##### Schedule values

The same values apply to `cancel_at_schedule` and `pause_at_schedule`.

- `billing`: the end of the current billing period, from `date_period_end`. During a trial, `date_trial_end` is used instead.
- `order`: the end of the current order period, from `date_order_period_end`.
- `first`: whichever of the two comes first.
- `last`: whichever of the two comes last.
- An ISO 8601 date string: that exact date.

`first` and `last` both fall back to the billing period when the subscription has no order period. A value that cannot be read as a date, or a date that is not in the future, is ignored and no schedule is set.

#### Undoing a cancellation

Setting `canceled` to `false` reverses a cancellation whether it is still scheduled or already complete. A pending cancellation is dropped and `date_cancel_at` is cleared. A subscription that had already been canceled returns to `active: true` with `date_canceled` cleared, `date_uncanceled` set, and a new billing cycle starting immediately. If the most recent payment attempt had failed, it is retried.

**Undo a cancellation**

**Node**

```javascript
await swell.put('/subscriptions/{id}', {
  id: '5c15505200c7d14d851e510f',
  canceled: false
});
```

#### Pausing

Pausing mirrors cancellation. Send `paused: true` with `pause_at_end: false` to pause immediately, which sets `active: false` and records `date_paused`. Send it with `pause_at_schedule` to schedule one, which keeps the subscription active and stores the calculated date in `date_pause_at`. Orders and invoices continue until that date.

Sending `paused: true` with `pause_at_end: true` is treated as `pause_at_schedule: 'first'`.

**Pause a subscription**

**Node**

```javascript
// Pause now
await swell.put('/subscriptions/{id}', {
  id: '5c15505200c7d14d851e510f',
  paused: true,
  pause_at_end: false
});

// Pause at the end of the current billing period
await swell.put('/subscriptions/{id}', {
  id: '5c15505200c7d14d851e510f',
  paused: true,
  pause_at_schedule: 'billing'
});
```

#### Resuming

Setting `paused` to `false` both cancels a pause that has not taken effect yet, clearing `date_pause_at`, and resumes a subscription that is already paused. Resuming always begins a new billing and ordering period, and an invoice or order is generated at that moment.

A resume can also be dated ahead. Set `date_pause_end` to resume at a specific time, or set `pause_skip_cycles` to resume after a number of cycles. Skipped cycles are counted from the current period end, following the same `pause_at_schedule` the pause used, and the result is stored in `date_pause_end`. A `date_pause_end` you provide takes precedence over `pause_skip_cycles`.

**Resume a subscription**

**Node**

```javascript
// Resume now, or drop a pause that hasn't taken effect
await swell.put('/subscriptions/{id}', {
  id: '5c15505200c7d14d851e510f',
  paused: false
});

// Resume two cycles after the current period ends
await swell.put('/subscriptions/{id}', {
  id: '5c15505200c7d14d851e510f',
  paused: false,
  pause_skip_cycles: 2
});

// Resume on a specific date
await swell.put('/subscriptions/{id}', {
  id: '5c15505200c7d14d851e510f',
  date_pause_end: '2027-03-01T00:00:00.000Z'
});
```

#### States

| State | canceled / paused | active | Orders and invoices |
| --- | --- | --- | --- |
| Active | false | true | Generated normally |
| Scheduled, waiting | true | true | Continue until the scheduled date |
| Canceled or paused immediately | true | false | Stopped |
| Stopping at period end, waiting | true | true | Stopped |

A subscription with `canceled: true` and `active: true` is therefore not yet finished. Read `active` to tell whether a subscription is still running, and `date_cancel_at` or `date_pause_at` to tell when it will stop.

#### Stopping at the end of the current period

Sending `canceled: true` with `cancel_at_end: true`, and no schedule set, stops orders and invoices right away while leaving `active: true` until the billing period ends. Sending `paused: true` with no scheduling fields behaves the same way for pausing. When `cancel_at_schedule` is present it takes precedence over `cancel_at_end`.


## List all subscriptions

Return a list of subscriptions.

### Fields

- `expand` (string): Expand link fields and child collections by using the expand argument.

  - For example, `expand=account` would return a related customer account if one exists.

  When the field represents a collection, you can specify the query limit.

  - For example, `expand=variants:10` would return up to 10 records of the variants collection.

  See [expanding](https://developers.swell.is/backend-api/querying/expanding) for more details.
- `fields` (string): Returns only the specified fields in the result.

  - For example `fields=name,slug` would return only the fields `name` and `slug` in the response.

  Supports nested object and array fields using dot-notation.

  - For example, `items.product_id`. The product `id` is always returned.
- `include` (object): Include one or more arbitrary queries in the response which are potentially related to the main query.

  See [including](https://developers.swell.is/backend-api/querying/including) for more details.
- `limit` (int): Limit the number of records returned, ranging between `1` and `1000`. Defaults to `15`. Default: `15`.
- `page` (int): The page number of results to return given the specified or default `limit`.
- `search` (string): A text search is performed using the search argument. Searchable fields are defined by the model.

  - For example, `search=red` would return records containing the word "red" anywhere in the defined text fields.

  See [searching](https://developers.swell.is/backend-api/querying/searching) for more details.
- `sort` (string): Expression to sort results by using a format similar to a SQL sort statement.

  - For example, `sort=name asc` would return records sorted by name ascending.

  See [sorting](https://developers.swell.is/backend-api/querying/sorting) for more details.
- `where` (object): An object with criteria to filter the result.

  - For example, `active=true` would return records containing a field `active` with the value `true`.

  It's also possible to use query operators, for example, `$eq`, `$ne`, `$gt`, and more.

  See [querying](https://developers.swell.is/backend-api/querying) for more details.

### Example request

`GET /subscriptions`

**cURL**

```bash
$ curl "https://api.swell.store/subscriptions?limit=25&page=1" \
  -u store-id:secret-key \
  -G
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.get('/subscriptions', {
  limit: 25,
  page: 1
});
```

**PHP**

```php
<?php

use Swell\Client;

$swell = new Client('store-id', 'secret-key');

$swell->get('/subscriptions', [
  'limit' => 25,
  'page' => 1
]);

?>
```

### Example response

```json
{
  "count": 54,
  "results": [
    {
      "currency": "USD",
      "account_id": "62acbadb3edcc300128d4178",
      "billing": {
        "first_name": "Wandering",
        "last_name": "Traveller",
        "name": "Wandering Traveller",
        "card": {
          "brand": "Visa",
          "last4": "4242",
          "exp_month": 7,
          "exp_year": 2024,
          "token": "card_s4FQeFxdb8ErigKVxS9cR3js"
        },
        "method": "card",
        "account_card_id": "62b2117ed9dce40019a6587b",
        "use_account": true
      },
      "shipping": {
        "first_name": "Wandering",
        "last_name": "Traveller",
        "company": "Urbul gro-Orkulg's crew",
        "address1": "1234 City Isle",
        "address2": "Cyrodiil",
        "city": "Heartlands",
        "country": "US",
        "name": "Wandering Traveller",
        "account_address_id": "62acbbe0d69a3b0012c7eae5",
        "use_account": true
      },
      "order_id": "62b9ee09e342a30012319601",
      "order_item_id": "62b9f12391fed80013478224",
      "product_id": "62b1e30767145000197b2bbf",
      "product_name": "Skooma",
      "variant_id": null,
      "options": null,
      "price": 75,
      "quantity": 1,
      "billing_schedule": {
        "interval": "monthly",
        "interval_count": 1,
        "limit": null,
        "trial_days": 0
      },
      "order_schedule": null,
      "coupon_code": null,
      "discounts": [],
      "items": [],
      "price_total": 75,
      "payment_balance": -81,
      "trial": false,
      "paid": false,
      "unpaid": true,
      "sub_total": 75,
      "grand_total": 75,
      "recurring_total": 75,
      "ordering": true,
      "plan_id": null,
      "plan_name": null,
      "active": true,
      "date_period_start": "2023-08-27T18:14:53.861Z",
      "date_period_end": "2023-09-27T18:14:53.861Z",
      "test": true,
      "date_created": "2022-06-27T18:14:53.887Z",
      "status": "unpaid",
      "number": "100004",
      "date_updated": "2023-08-27T18:15:01.146Z",
      "invoices": "62b9f1d191fed8001347822a",
      "invoice_total": 81,
      "payment_total": 0,
      "date_payment_expiring": "2024-07-01T00:00:00.000Z",
      "date_payment_failed": "2023-01-27T18:15:03.450Z",
      "payment_error": "Unable to complete payment, invoice not found",
      "retry_resolve": "unpaid",
      "id": "62b9f39d8b9a9a00133b7784"
    },
    {...}
  ],
  "page": 1,
  "page_count": 3,
  "limit": 25,
  "pages": {
    "1": {
      "start": 1,
      "end": 25
    },
    "2": {
      "start": 26,
      "end": 50
    },
    "3": {
      "start": 51,
      "end": 54
    }
  }
}
```


## Delete a subscription

Delete a subscription permanently.

### Arguments

- `id` (objectId, required): The id of the subscription to delete.

### Example request

`DELETE /subscriptions/:id`

**cURL**

```bash
$ curl https://api.swell.store/subscriptions/60f199509111e700000000c7 \
  -u store-id:secret-key \
  -X DELETE
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.delete('/subscriptions/60f199509111e700000000c7');
```

**PHP**

```php
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->delete('/subscriptions/60f199509111e700000000c7');

?>
```

### Example response

```json
{
  "id": "60f199509111e700000000c7",
  "account_id": "60f199509111e700000000c8",
  "product_id": "60f199509111e700000000c9",
  "active": true,
  "cancel_at_end": false,
  "cancel_reason": null,
  "canceled": false,
  "currency": "USD",
  "date_canceled": null,
  "date_created": "2021-07-16T14:36:00.483Z",
  "date_payment_expiring": "2031-01-01T08:00:00.000Z",
  "date_payment_failed": null,
  "date_payment_retry": null,
  "date_period_end": "2019-03-24T04:28:12.962Z",
  "date_period_start": "2019-02-24T04:28:12.962Z",
  "date_trial_end": "2019-02-24T04:28:12.962Z",
  "date_trial_start": "2019-01-24T04:28:12.962Z",
  "date_updated": "2021-07-16T14:36:00.483Z",
  "discount_total": 0,
  "discounts": null,
  "grand_total": 148.8946,
  "interval": "monthly",
  "interval_count": 1,
  "invoice_total": 99,
  "item_discount": 0,
  "item_tax": 0,
  "item_total": 49.8946,
  "items": [
    {
      "id": "5ca537326a0ec32a521139dd",
      "date_created": "2019-03-24T22:56:33.467Z",
      "description": "Remaining time on Example Subscription",
      "proration": true,
      "quantity": 1,
      "price": 49.8946,
      "price_total": 49.8946,
      "recurring_price": 0,
      "recurring_price_total": 0,
      "discount_total": 0,
      "discount_each": 0,
      "recurring_discount_total": 0,
      "recurring_discount_each": 0,
      "tax_total": 0,
      "tax_each": 0,
      "recurring_tax_total": 0,
      "recurring_tax_each": 0
    }
  ],
  "notes": null,
  "options": [
    {
      "id": "5becb84fac207653a4816ee5",
      "name": "Plan",
      "value": "Monthly"
    }
  ],
  "order_id": "60f199509111e7000000009d",
  "order_item_id": "60f199509111e7000000009e",
  "paid": true,
  "payment_balance": 0,
  "payment_total": 99,
  "price": 99,
  "price_total": 99,
  "product_discount_each": 0,
  "product_discount_total": 0,
  "product_discounts": null,
  "product_tax_each": 0,
  "product_tax_total": 0,
  "product_taxes": null,
  "quantity": 1,
  "recurring_discount_total": 0,
  "recurring_item_discount": 0,
  "recurring_item_tax": 0,
  "recurring_item_total": 0,
  "recurring_tax_included_total": 0,
  "recurring_tax_total": 0,
  "recurring_total": 99,
  "refund_total": 0,
  "status": "active",
  "sub_total": 148.8946,
  "tax_included_total": 0,
  "tax_total": 0,
  "taxes": null,
  "trial": false,
  "trial_days": 14,
  "unpaid": false,
  "variant_id": "60f199509111e7000000009f"
}
```