Backend API

Subscriptions

Subscriptions allow charging a customer on a recurring basis. A subscription is a product with a subscription purchase_option defined. 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 charged by subscribing to a plan with bundle_items.

The subscription product 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 product

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 pricing option. When trial_days or date_trial_end are set, 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

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.

attributes

object

An object containing custom attribute key/value pairs. See attributes for more details.

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 request = require('request');

const url = 'https://api.swell.store/products';
const data = {
  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
        }
      }]
    }
  }
};
The product model
{
  "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 product

Retrieve an existing subscription product using the 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}');
The product model
{
  "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 product

Update an existing subscription product 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

objectIdrequired

Unique identifier for the product.

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

array of Stock

Expandable list of stock adjustments for the product.

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.

up_sells

array of object

List of products to display as up-sells on a product detail page.

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.

PUT/products/:id
const request = require('request');

const url = 'https://api.swell.store/products/{id}';
const data = {
  purchase_options: {
    subscription: {
      active: true,
      plans: [{
        name: encodeURIComponent('Weekly'),
        price: 105,
        billing_schedule: {
          interval: encodeURIComponent('weekly'),
          trial_days: 0
        }
      }]
    }
  }
};

const encodedData = JSON.stringify(data);

request({
  url,
  method: 'POST',
  body: encodedData
});
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 products

Return a list of subscriptions products.

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'
    })
  }
});
Response
{
  "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 productf

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 subscription plans that reference this product. Update the subscription plans 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}', {
});
The subscription model
{
  "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"
}
← Back: ReturnsNext: Subscription plans →
© 2024 Swell
Terms of servicePrivacy policy