Backend API

Subscription plans

Subscription plans is the recurring order for which

The subscription plan model

A subscription product is achieved by creating a product with a defined subscription purchase option.

Fields

id

objectId

Unique identifier for the product.

name

stringrequired

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.

subscription_interval

enum

The default billing interval when this product is used as a subscription plan. Can be monthly, yearly, weekly, or daily.

Possible enum values:

monthlydailyweeklyyearly

subscription_interval_count

int

Multiplier when combined with subscription_interval. For example, to make a subscription bill every two 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.

The product model
{
  "purchase_options": {
    "standard": {
      "active": true,
      "price": 75,
      "sale": true,
      "sale_price": 60,
      "prices": [
        {
          "account_group": "vip",
          "price": 65,
          "quantity_max": null,
          "quantity_min": null,
          "$locale": {
            "en-US": {
              "description": ""
            },
            "ja": {
              "description": ""
            }
          }
        }
      ]
    },
    "subscription": {
      "active": true,
      "plans": [
        {
          "name": "Monthly",
          "description": null,
          "price": 75,
          "billing_schedule": {
            "interval": "monthly",
            "interval_count": 1,
            "limit": null,
            "trial_days": 1
          },
          "id": "62b1e30767145000197b2bc0",
          "active": true,
          "$locale": {
            "en-US": {
              "description": null,
              "name": "Monthly"
            },
            "ja": {
              "description": ""
            }
          }
        }
      ]
    }
  },
  "name": "Skooma",
  "sku": "0004E0A9",
  "active": true,
  "images": [
    {
      "file": {
        "id": "62b1e2b34bf1a70019cbf610",
        "date_uploaded": "2022-06-21T15:24:35.166Z",
        "length": 7024,
        "md5": "4b39c328dc2652792c048d0fd3f8a426",
        "filename": null,
        "content_type": "image/png",
        "metadata": null,
        "url": "https://cdn.schema.io/launch-storefront/62b1e2b34bf1a70019cbf610/4b39c328dc2652792c048d0fd3f8a426",
        "width": 64,
        "height": 64
      },
      "id": "62b1e30767145000197b2bc1",
      "$locale": {
        "en-US": {
          "file": {
            "id": "62b1e2b34bf1a70019cbf610",
            "date_uploaded": "2022-06-21T15:24:35.166Z",
            "length": 7024,
            "md5": "4b39c328dc2652792c048d0fd3f8a426",
            "filename": null,
            "content_type": "image/png",
            "metadata": null,
            "url": "https://cdn.schema.io/launch-storefront/62b1e2b34bf1a70019cbf610/4b39c328dc2652792c048d0fd3f8a426",
            "width": 64,
            "height": 64
          }
        }
      }
    }
  ],
  "cost": 60,
  "variable": false,
  "description": "​Damage Intelligence 2 pts<br>Drain Agility 60 pts for 20 secs<br>Fortify Speed and Strength 60 pts for 20 secs​",
  "tags": [],
  "meta_title": null,
  "meta_description": "Several skooma dealers can be found in and around Cyrodiil, usually in hidden and out of sight spots, such as Shady Sam and Nordinor. A skooma den can also be found right above Carandial's house in Bravil. There is also a skooma smuggling ring led by Dulfish gro-Orum that can be uncovered in Cheydinhal through investigation by the player.",
  "slug": "skooma",
  "attributes": {
    "rooms": [
      "Kitchen"
    ],
    "room_usage": [
      "Kitchen",
      "Dining room",
      "Bedroom",
      "Bathroom",
      "Ballroom"
    ]
  },
  "delivery": "shipment",
  "bundle": null,
  "price": 75,
  "stock_tracking": false,
  "options": [],
  "currency": "USD",
  "type": "standard",
  "tax_class": "standard",
  "date_created": "2022-06-21T15:25:59.518Z",
  "stock_status": null,
  "category_index": {
    "sort": {
      "628bb55d499bba0019b1ab91": 0
    },
    "id": [
      "628bb55d499bba0019b1ab91"
    ]
  },
  "date_updated": "2023-07-22T15:27:54.751Z",
  "popularity": 41,
  "prices": [
    {
      "account_group": "vip",
      "price": 65,
      "quantity_max": null,
      "quantity_min": null,
      "$locale": {
        "en-US": {
          "description": ""
        },
        "ja": {
          "description": ""
        }
      }
    }
  ],
  "sale": true,
  "sale_price": 60,
  "stock_level": -1,
  "engraving": "To my dearest Caedmon, you shall always be the greatest blacksmith",
  "magic_level": 660,
  "your_engraving": "To my dearest Caedmon, you shall always be the greatest blacksmith",
  "content": {
    "your_engraving": "To my dearest Caedmon, you shall always be the greatest blacksmith",
    "enchanted": "nope"
  },
  "cuztomization": {
    "engraving": true,
    "engraving_text": "Get stuffed Mariel"
  },
  "cross_sells": [
    {
      "id": "63628888adb6305fff690058",
      "product_id": "628ba4811869c10019b41f62",
      "discount_type": "fixed",
      "discount_amount": null
    }
  ],
  "up_sells": [
    {
      "id": "63628882adb6305fff690057",
      "product_id": "628ba701499bba0019b1a9bb"
    }
  ],
  "things": [
    {
      "date": "2023-04-13T17:00:00.000Z",
      "log": "Something happened",
      "id": "6437102e171326001374f584"
    }
  ],
  "id": "62b1e30767145000197b2bbf",
  "$locale": {
    "en-US": {
      "name": "Skooma",
      "description": "​Damage Intelligence 2 pts<br>Drain Agility 60 pts for 20 secs<br>Fortify Speed and Strength 60 pts for 20 secs​",
      "tags": [],
      "meta_title": null,
      "meta_description": "Several skooma dealers can be found in and around Cyrodiil, usually in hidden and out of sight spots, such as Shady Sam and Nordinor. A skooma den can also be found right above Carandial's house in Bravil. There is also a skooma smuggling ring led by Dulfish gro-Orum that can be uncovered in Cheydinhal through investigation by the player."
    }
  }
}

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

stringrequired

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.

active

boolean

Set true to make the product visible to customers in a storefront, otherwise it will be hidden.

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.

description

string

A long form description of the product. May have HTML or other markup.

POST/products
const swell = require('swell-node').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
        }
      }]
    }
  }
});

Retrieve a subscription plan

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

Arguments

id

objectIdrequired

The id of the product to retrieve.

GET/products/:id
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/products/{id}');

Update a subscription plan

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

Arguments

active

boolean

Indicates whether the product is active and available in the storefront.

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.

description

string

A long-form description of the product. May contain HTML or other markup languages.

images

array of object

List of images depicting the bundle.

options

array of object

Options that allow for variations of the base product. If the option is part of a variant or required=true, an option value must be set for the product to be added to a cart.

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.

prices

array of object

Price rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.

stock_level

int

Quantity of the product currently in stock (including all variants), based on the sum of the stock entries.

tags

array of child_scalar

Array of searchable tags to aid in search discoverability.

PUT/products/:id
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.put('/products/{id}', {
  purchase_options: {
    subscription: {
      active: true,
      plans: [{
        name: 'Weekly',
        price: 105,
        billing_schedule: {
          interval: 'weekly',
          trial_days: 0
        }
      }]
    }
  }
});
The product model
{
  "name": "Skooma",
  "purchase_options": {
    "subscription": {
      "active": true,
      "plans": [
        {
          "name": "Weekly",
          "description": null,
          "price": 105,
          "billing_schedule": {
            "interval": "weekly",
            "interval_count": 1,
            "limit": null,
            "trial_days": 0
          },
          "id": "64e799c1307e48001237eef5",
          "active": true,
          "$locale": {
            "en-US": {
              "name": "Monthly",
              "description": null
            }
          }
        }
      ]
    }
  },
  "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",
  "$locale": {
    "en-US": {
      "name": "Skooma"
    }
  }
}

List all subscription plans

Return a list of products with subscription plans.

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 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 for more details.

limit

int

Limit the number of records returned, ranging between 1 and 1000. Defaults to 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 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 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 for more details.

GET/products
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/products', {
  limit: 25,
  page: 1,
  headers: {
    'filter': JSON.stringify({
      'key': 'subscription',
      'value': 'true'
    })
  }
});
The product model
{
  "count": 15,
  "page_count": 1,
  "page": 1,
  "results": [
    {
      "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,
              "$locale": {
                "en-US": {
                  "name": "Monthly",
                  "description": null
                }
              }
            }
          ]
        }
      },
      "currency": "USD",
      "slug": "skooma",
      "price": 75,
      "type": "standard",
      "delivery": "shipment",
      "tax_class": "standard",
      "date_created": "2023-08-24T17:56:17.162Z",
      "active": false,
      "stock_status": null,
      "id": "64e799c1307e48001237eef4"
    }
  ]
}
. . .

Delete a subscription plan

Delete a subscription product permanently. The method outlined removes the entire product. Alternatively, you can also remove the subscription purchase_option, should you wish to retain the product and any other associated purchase options.

This is not recommended if there are currently active subscriptions that reference this product. Update those subscriptions prior to deleting the subscription product.

Arguments

id

objectIdrequired

The id of the product you wish to delete.

DELETE/products/:id
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.delete('/products/{id}');
← Back: SubscriptionsNext: Accounts →
© 2026 Swell
Terms of servicePrivacy policy