# Create a subscription plan

Source: https://developers.swell.is/backend-api/subscription-plans/create-a-subscription-plan

When creating a product, utilizing the subscription `purchase option` will allow a customer to buy that product on a recurring subscription.

A recurring subscription order will be created when a customer purchases a product's subscription plan.

## Arguments

- `name` (string, required): Human-friendly name of the product.
- `purchase_options` (object): Configuration of one or more purchase options for the product. Can be `standard` for one-time purchases or `subscription` for a subscription plan. Products can support both purchase options simultaneously.
  - `standard` (object): Designates purchase option as a one-time purchase.
    - `id` (objectId): ID of the purchase option.
    - `name` (string, required): The name of the purchase option.
    - `description` (string): A long-form description of the product. May contain HTML or other markup languages.
    - `active` (boolean): Indicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the [Frontend](https://developers.swell.is/frontend-api/introduction). Default: `false`.
    - `price` (currency): List price used when `sale=false` or `sale_price` is not defined.
    - `sale` (boolean): Indicates whether the product option is on sale. If `true`, the `sale_price` will be used by default when the product is added to a cart.
    - `sale_price` (currency): Sale price used by default when `sale=true`, overriding `price`. Overrides product sale price.
    - `prices` (array of object): Price rules determined by cart quantity or customer account group. Overrides `price` and `sale_price` when conditions match.
      - `price` (currency, required): Price applied when conditions are met.
      - `account_group` (string): Customer account group as a condition to apply price.
      - `quantity_max` (int): Maximum quantity as a condition to apply price.
      - `quantity_min` (int): Minimum quantity as a condition to apply price.
    - `account_groups` (array of string): Array of account groups that are eligible to access the purchase option within the storefront.
  - `subscription` (object): Designates purchase option as a subscription plan.
    - `id` (objectId): ID of the subscription plan purchase option.
    - `name` (string, required): Name of the subscription plan purchase option.
    - `description` (string): A long-form description of the purchase option. May contain HTML or other markup languages.
    - `active` (boolean): Indicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the [Frontend](https://developers.swell.is/frontend-api/introduction). Default: `false`.
    - `account_groups` (array of string): Array of `account_group` names for which the purchase option is available.
    - `plans` (array of object): Array defining subscription plans and their respective configurations.
      - `id` (objectId): ID of the purchase option subscription plan.
      - `name` (string, required): Name of the subscription plan.
      - `description` (string): A long-form description of the subscription plan. May contain HTML or other markup languages.
      - `active` (boolean): Indicates whether the subscription plan is available for customers to purchase. Inactive products will not be returned on the [Frontend](https://developers.swell.is/frontend-api/introduction). Default: `fasle`.
      - `price` (currency): List price used when `sale=false` or `sale_price` is not defined.
      - `prices` (array of object): Price rules determined by cart quantity or customer account group. Overrides `price` and `sale_price` when conditions match.
        - `price` (currency, required): Price applied when conditions are met.
        - `account_group` (string): Customer account group as a condition to apply price.
        - `quantity_max` (int): Maximum quantity as a condition to apply price.
        - `quantity_min` (int): Minimum quantity as a condition to apply price.
      - `billing_schedule` (object, required): Determines the billing schedule for the subscription plan.
        - `interval` (enum, required): Subscription plan billing interval. Can be `daily`, `weekly`, `monthly`, or `yearly`. Possible values: `daily`, `weekly`, `monthly`, `yearly`.
        - `interval_count` (int, required): Multiplier for billing interval. For example, to make the billing cycle once every two weeks, set `interval=weekly` and `interval_count=2`. Default: `1`.
        - `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. Default: `∞`.
- `active` (boolean): Set `true` to make the product visible to customers in a storefront, otherwise it will be hidden. Default: `false`.
- `bundle` (boolean): Indicates whether the product is a bundle of other products.
- `bundle_items` (array of object): List of products sold as a bundle. Applicable only when `bundle=true`.
  - `product_id` (objectId, required): ID of the bundled product.
  - `quantity` (int): Quantity of the bundled product. Defaults to 1. Default: `1`.
  - `variant_id` (objectId): ID of the bundled variant, if applicable.
- `description` (string): A long form description of the product. May have HTML or other markup.
- `price` (currency): List price used when `sale=false` or `sale_price` is not defined. This value is intended for use via the frontend. See the `purchase_options` array to manage a product's price. Default: `0`.
- `attributes` (object): An object containing custom attribute key/value pairs. See [attributes](https://developers.swell.is/backend-api/attributes/the-attribute-model) for more details.
- `categories` (Category): Expandable link to all related product categories.
- `category` (Category): Expandable link to the primary category.
- `category_id` (objectId): Primary category, commonly used as a navigation anchor.
- `category_index` (object): Index of categories used for fast lookup operations.
  - `sort` (object): Index of category IDs and their respective sort positions.
    - `*` (int)
- `code` (string): Unique code to identify the gift card product.
- `cost` (currency): Cost of goods (COGS) that is used to calculate gross margins.
- `cross_sells` (array of object): List of products to display as cross-sells on a shopping cart page.
  - `product_id` (objectId, required): ID of the cross-sell product.
  - `discount_amount` (currency): Discount to apply as a fixed amount. Applicable only when `discount_type=fixed`.
  - `discount_percent` (float): Discount to apply as a percentage. Applicable only when `discount_type=percent`.
  - `discount_type` (enum): Type of discount to apply, either `fixed` or `percent`. Possible values: `fixed`, `percent`.
- `currency` (string): Three-letter ISO currency code in uppercase. Defaults to your store's base currency.
- `customizable` (boolean): Set `true` to enable custom options for this product in the admin panel.
- `delivery` (enum): Method of fulfillment automatically assigned based on `type`:

  - `shipment` means the product will be physically shipped to a customer.
  - `subscription` means the product will be fulfilled as a [subscription](https://developers.swell.is/backend-api/subscriptions/the-subscription-model) when an order is placed. `giftcard` delivery means the product will be fulfilled as a [gift card](https://developers.swell.is/backend-api/pages/the-pages-model) when an order is placed.
  - `null` means the product will not be fulfilled by one of the above methods.

  *Note: A bundle has its child products fulfilled individually; each product in the bundle must have its own fulfillment method.* Possible values: `shipment`, `subscription`, `giftcard`.
- `discontinued` (boolean): Indicates whether the product has been discontinued.
- `images` (array of object): List of images depicting the bundle.
  - `caption` (string): A brief description of the image, intended for display as a caption or alt text.
  - `file` (object): An object representing the image's source file.
    - `id` (objectId): Unique identifier for the file.
    - `date_uploaded` (date): Date the file was uploaded.
    - `length` (int): Size of the file in bytes.
    - `md5` (string): An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.
    - `filename` (string): Optional file name.
    - `content_type` (string): MIME content type of the file.
    - `metadata` (object): A set of arbitrary data that is typically used to store custom values.
    - `data` (filedata): Set or overwrite file data. Use the following format when writing a file from binary data (for example an image): `data[$binary]=<base64 encoded binary data>`.
    - `private` (boolean): Indicates whether the file is private.
    - `url` (string): A public URL to reference the file. Updated automatically if file content changes.
    - `width` (int): Image width in pixels, if applicable.
    - `height` (int): Image height in pixels, if applicable.
- `meta_description` (string): Page description used for search engine optimization purposes.
- `meta_keywords` (string): Page keywords used for search engine optimization purposes.
- `meta_title` (string): Page title used to override product name in storefronts.
- `prices` (array of object): Set price rules to use when conditions match the customer's account group or product quantity in a cart.
  - `price` (currency, required): Price applied when conditions are met.
  - `account_group` (string): Customer account group as a condition to apply price.
  - `quantity_max` (int): Maximum quantity as a condition to apply price.
  - `quantity_min` (int): Minimum quantity as a condition to apply price.
- `quantity_inc` (int): Specifies a quantified multiple the product must be sold in.
- `quantity_min` (int): Minimum quantity of the product that can be sold at once.
- `related_product_ids` (array of child_scalar): Array of related product IDs.
- `sale` (boolean): Set `true` to mark the product "on sale" and to use `sale_price` when the product is added to a cart.
- `sale_price` (currency): Sale price used to override list price when `sale=true`.
- `shipment_dimensions` (object): Product dimensions when packed for shipping. Typically used by 3rd party carriers in box packing algorithms to optimize shipping costs.
  - `height` (float): Height of the product in `unit`.
  - `length` (float): Length of the product in `unit`.
  - `unit` (enum): Either `in` (inches) or `cm` (centimeters). Possible values: `in`, `cm`. Default: `"in"`.
  - `width` (float): Width of the product in `unit`.
- `shipment_location` (string): ID of location from `/settings/shipping/locations`. If specified, shipping is calculated from this origin. Otherwise, the store's default location will be used.
- `shipment_package_quantity` (float): If specified, shipping is calculated using this as the maximum number of items per package. Otherwise, Swell assumes any quantity fits into a single package.
- `shipment_prices` (array of object): Product shipping price rules to override default shipping rules.
  - `service` (string, required): Shipping service required for this rule to apply.
  - `package_quantity` (int): Maximum package quantity when rule is applied.
  - `price` (currency): Shipping price when rule is applied.
  - `fee_type` (enum): Type of fee to apply in addition to `price`, either `fixed` or `percent`. Possible values: `fixed`, `percent`.
  - `fee_amount` (currency): Fixed amount to add when rule is applied. Only applicable when `fee_type=fixed`.
  - `fee_percent` (float): Percentage of the shipping price to add when rule is applied. Only applicable when `fee_type=percent`.
  - `total_min` (currency): Minimum order subtotal for this rule to apply.
  - `total_max` (currency): Maximum order subtotal for this rule to apply.
  - `weight_min` (float): Minimum order item weight for this rule to apply.
  - `weight_max` (float): Maximum order item weight for this rule to apply.
  - `state` (string): Shipping state required for this rule to apply.
  - `zip` (string): Shipping zip/postal code required for this rule to apply.
  - `country` (string): Shipping country required for this rule to apply.
  - `account_group` (string): Customer group required for this rule to apply.
- `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.
- `sku` (string): Stock keeping unit (SKU) used to track inventory in a warehouse.
- `slug` (string): Lowercase, hyphenated identifier typically used in URLs. When creating a product, a `slug` will be generated automatically from the `name`. Maximum length of 1,000 characters. Default: `{"$formula":"slug(name)"}`.
- `stock` (array of Stock): Expandable list of stock adjustments for the product.
- `stock_backorder` (boolean): Indicates whether the product can be backordered if out of stock.
- `stock_level` (int): Quantity of the product currently in stock (including all variants), based on the sum of the stock entries.
- `stock_preorder` (boolean): Indicates whether the product can be purchased as a preorder.
- `stock_purchasable` (boolean): Indicates whether the product's stock is purchasable.
- `stock_status` (enum, auto): String indicating the product's stock status for the purpose of ordering. When `stock_purchasable=true`, an order can be placed for this product regardless of current stock status, otherwise an order submission will be blocked unless stock status is `available`, `preorder ,`or `backorder`. Possible values: `discontinued`, `preorder`, `backorder`, `out_of_stock`, `in_stock`.
- `stock_tracking` (boolean): Set `true` to enable stock tracking this product.
- `subscription_interval` (enum): The default billing interval when this product is used as a subscription plan. Can be `monthly`, `yearly`, `weekly`, or `daily`. Possible values: `monthly`, `daily`, `weekly`, `yearly`.
- `subscription_interval_count` (int): Multiplier when combined with `subscription_interval`. For example, to make a subscription bill every 2 weeks, set `subscription_interval=weekly` and `subscription_interval_count=2`.
- `subscription_trial_days` (int): Number of days offered as a free trial before the customer is billed. If a subscription is canceled by the last day of the trial period, an invoice won't be issued.
- `summary` (string): A brief product summary.
- `tax_class` (string): Indicates the tax class for the product.
- `tax_code` (string): Product tax code for tracking with Avalara, TaxJar, etc.
- `up_sells` (array of object): List of products to display as up-sells on a product detail page.
  - `id` (objectId, auto): Unique identifier for the up-sell.
  - `product_id` (objectId, required): ID of the up-sell product.
  - `product` (product): Expandable link to the up-sell product.
- `variable` (boolean): Set `true` to generate variants for this product in the admin panel.
- `variants` (array of Variants): Expandable list of variants representing unique variations of the product. Each variant is a combination of one or more `options`. For example, Size and Color.
- `virtual` (boolean): Indicates whether the product is virtual.

## Example request

`POST /products`

**cURL**

```bash
curl -X POST https://api.swell.store/products \
  -u store-id:secret-key \
  -d "name=Skooma" \
  -d "purchase_options[subscription][active]=true" \
  -d "purchase_options[subscription][plans][0][name]=Monthly" \
  -d "purchase_options[subscription][plans][0][description]=null" \
  -d "purchase_options[subscription][plans][0][price]=75" \
  -d "purchase_options[subscription][plans][0][billing_schedule][interval]=monthly" \
  -d "purchase_options[subscription][plans][0][billing_schedule][interval_count]=1" \
  -d "purchase_options[subscription][plans][0][billing_schedule][limit]=null" \
  -d "purchase_options[subscription][plans][0][billing_schedule][trial_days]=1"
```

**Node**

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

await swell.post('/products', {
  name: 'Skooma',
  purchase_options: {
    subscription: {
      active: true,
      plans: [{
        name: 'Monthly',
        description: null,
        price: 75,
        billing_schedule: {
          interval: 'monthly',
          interval_count: 1,
          limit: null,
          trial_days: 1
        }
      }]
    }
  }
});
```

**PHP**

```php
<?php

use Swell\Client;

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

$data = array(
  'name' => 'Skooma',
  'purchase_options' => array(
    'subscription' => array(
      'active' => true,
      'plans' => array(
        array(
          'name' => 'Monthly',
          'description' => null,
          'price' => 75,
          'billing_schedule' => array(
            'interval' => 'monthly',
            'interval_count' => 1,
            'limit' => null,
            'trial_days' => 1
          )
        )
      )
    )
  )
);

$swell->post('/products', $data);

?>
```

## Example response

```json
{
  "name": "Skooma",
  "purchase_options": {
    "subscription": {
      "active": true,
      "plans": [
        {
          "name": "Monthly",
          "description": null,
          "price": 75,
          "billing_schedule": {
            "interval": "monthly",
            "interval_count": 1,
            "limit": null,
            "trial_days": 1
          },
          "id": "64e799c1307e48001237eef5",
          "active": true
        }
      ]
    }
  },
  "currency": "USD",
  "slug": "skooooma",
  "price": 75,
  "type": "standard",
  "delivery": "shipment",
  "tax_class": "standard",
  "date_created": "2023-08-24T17:56:17.162Z",
  "active": false,
  "stock_status": null,
  "id": "64e799c1307e48001237eef4"
}
```