# Create a subscription

Source: https://developers.swell.is/backend-api/subscriptions/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"
}
```