Backend API

Subscription plans

Subscription plans is the recurring order for which

Subscription model

The subscription model represents the recurring order (plan) 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 product.

product

Product

Expandable link to the subscription plan product.

active

boolean

Indicates the subscription is currently active.

billing

object

Subscription billing details.

billing_schedule

object

Billing schedule for subscription plan.

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 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_created

dateauto

Date and time the subscription was created.

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

dateauto

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

dateauto

When automated payment has failed, this is the date when the system will automatically retry.

date_period_end

dateauto

End date of the current billing period.

date_period_start

date

Start date of the current billing period.

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

dateauto

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.

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

currencyauto

Total discount applied to line items.

item_tax

currency

Total taxes applied to line items.

item_total

currencyauto

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.

notes

string

Internal admin notes. These are not visible to the customer.

number

stringauto

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.

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.

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

booleanauto

Indicates the last invoice was fully paid.

payment_balance

currencyauto

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

currencyauto

Total price of the plan (price * quantity).

product_discount_each

currencyauto

Total discount amount of the subscription plan, divided by quantity.

product_discount_total

currencyauto

Total discount applied to the subscription plan.

product_discounts

array of object

List of discounts applied to the subscription plan by coupons.

product_name

string

This field is a copy of the item's product.name.

product_tax_each

currencyauto

Total tax amount of the subscription plan, divided by quantity.

product_tax_total

currencyauto

Total tax applied to the subscription plan.

product_taxes

array of objectauto

List of tax rules applied to the subscription plan based on tax settings.

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.

recurring_discount_total

currencyauto

Total recurring discount applied to the subscription including line items.

recurring_item_discount

currencyauto

Total discount applied to recurring line items.

recurring_item_tax

currencyauto

Total taxes applied to recurring line items.

recurring_item_total

currencyauto

Sum of all recurring line items before discounts and taxes.

recurring_tax_included_total

currencyauto

Total of taxes applied separately from the subscription plan and recurring line items.

recurring_tax_total

currencyauto

Total taxes applied to the subscription including recurring line items.

recurring_total

currencyauto

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

enumauto

Current status of the subscription. Can be pending, active, trial, pastdue, unpaid, canceled, or paid.

sub_total

currencyauto

Sum of all line items before discounts and taxes.

tax_included

booleanauto

Indicates the subscription plan price includes taxes.

tax_included_total

currencyauto

Total of taxes applied separately from the subscription plan and line items.

tax_total

currencyauto

Total taxes applied to the subscription including line items.

taxes

array of objectauto

List of taxes applied to the subscription.

taxes_fixed

boolean

When true, taxes are not applied to the subscription. When false, taxes are calculated and applied to the subscription.

trial

booleanauto

Indicates the subscription is in a trial period and the first invoice will be issued on date_trial_end.

unpaid

booleanauto

Indicates the last invoice was marked as unpaid. This occurs automatically after all payment attempts are exhausted, as configured in subscription settings.

variant

Product variant

Expandable link to the subscription plan variant, if applicable.

variant_id

objectId

ID of the subscription plan variant, if applicable.

Create a subscription plan

Create a subscription plan for a product with a subscription purchase option.

Arguments

account_id

objectIdrequired

ID of the subscribed customer's account.

product_id

objectIdrequired

ID of the subscription plan 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.

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.

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

await swell.post('/products', {
  body: {
    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: {
      model: 'products'
    },
    product_name: 'Skooma',
    variant_id: '62b1e30767145000197b2bc0',
    variant: {
    },
    price: 75,
    quantity: 1,
    price_total: 75,
    options: [
      {
        id: 'Monthly',
        value: 99
      }
    ]
  }
};
The subscription model
{
  "id": "5cad15bc9b14d1990724663a",
  "delivery": "subscription"
  "name": "Pro plan",
  "options": [
    {
      "id": "5ca24ab32599d4179c24a624",
      "name": "Plan",
      "variant": true,
      "subscription": true,
      "values": [
        {
          "id": "5ca24ad59c077817e5fe2ba3",
          "name": "Monthly",
          "subscription_interval": "monthly",
          "price": 99
        },
        {
          "id": "5ca24ad59c077817e5fe2ba4",
          "name": "Yearly",
          "subscription_interval": "yearly",
          "price": 999
        }
      ]
    }
  ],
  "slug": "pro-plan",
  "type": "subscription"
}

Retrieve a subscription plan

Retrieving a subscription plan with the ID that was returned when created.

Arguments

id

objectIdrequired

The id of the subscription to retrieve.

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

await swell.get('/subscriptions/{id}', {
});
The subscription model
{
  "id": "5cad15bc9b14d1990724663a",
  "delivery": "subscription"
  "name": "Coffee club",
  "bundle_items": [
    {
      "product_id": "5ca24abb9c077817e5fe2b36",
      "quantity": 1
    }
  ],
  "options": [
    {
      "id": "5ca24ab32599d4179c24a624",
      "name": "Plan",
      "variant": true,
      "subscription": true,
      "values": [
        {
          "id": "5ca24ad59c077817e5fe2ba3",
          "name": "Weekly",
          "subscription_interval": "weekly",
          "price": 15
        },
        {
          "id": "5ca24ad59c077817e5fe2ba3",
          "name": "Monthly",
          "subscription_interval": "monthly",
          "price": 19
        }
      ]
    }
  ],
  "slug": "coffee-club",
  "type": "subscription"
}

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

billing

object

Subscription billing details.

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.

coupon_code

string

Coupon code applied to the subscription. See coupons for details.

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.

product_id

objectIdrequired

ID of the subscription plan 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.

status

enumauto

Current status of the subscription. Can be pending, active, trial, pastdue, unpaid, canceled, or paid.

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

const url = 'https://api.swell.store/subscritpions/{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 subscription 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 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 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/subscriptions
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/subscriptions', {
  limit: 25,
  page: 1,
  }
);
The subscription model
{
  "count": 54,
  "page_count": 25,
  "page": 1,
  "results": [
    {
      "currency": "USD",
      "account_id": "62acbadb3edcc300128d4178",
      "billing": {
        "first_name": "Wandering",
        "last_name": "Traveller",
        "company": null,
        "address1": null,
        "address2": null,
        "city": null,
        "zip": null,
        "country": null,
        "state": null,
        "phone": null,
        "name": "Wandering Traveller",
        "card": {
          "brand": "Visa",
          "last4": "4242",
          "exp_month": 7,
          "exp_year": 2024,
          "token": "card_s4FQeFxdb8ErigKVxS9cR3js",
          "address_check": "unchecked",
          "zip_check": "unchecked",
          "cvc_check": "unchecked",
          "fingerprint": "883f20e8bc00d0f9e1c42967b39a4f22",
          "date_created": "2022-06-21T18:44:14.767Z"
        },
        "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",
        "zip": null,
        "country": "US",
        "state": null,
        "phone": null,
        "name": "Wandering Traveller",
        "account_address_id": "62acbbe0d69a3b0012c7eae5",
        "use_account": true,
        "price": null
      },
      "shipment_rating": {
        "date_created": "2022-06-27T17:51:05.110Z",
        "fingerprint": "08f0fbfe821509fe87fd4f4ed6c14666",
        "services": [
          {
            "id": "standard",
            "name": "Standard Shipping",
            "price": 5,
            "description": "Standard shipping service"
          },
          {
            "id": "express",
            "name": "Express Shipping",
            "price": 15,
            "description": "Express shipping service"
          }
        ]
      },
      "order_id": "62b9ee09e342a30012319601",
      "order_item_id": "62b9f12391fed80013478224",
      "product_id": "62b1e30767145000197b2bbf",
      "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,
      "coupon_id": null,
      "coupon_use_count": null,
      "discounts": [],
      "tax_included": false,
      "shipment_tax_included": false,
      "display_currency": null,
      "items": [],
      "product_name": "Skooma",
      "price_total": 75,
      "payment_balance": -81,
      "trial": false,
      "paid": false,
      "unpaid": true,
      "product_discount_total": 0,
      "product_discount_each": 0,
      "product_tax_total": 0,
      "product_tax_each": 0,
      "shipment_price": 0,
      "shipment_total": 0,
      "shipment_tax_included_total": 0,
      "date_period_end": "2023-09-27T18:14:53.861Z",
      "item_total": 0,
      "recurring_item_total": 0,
      "sub_total": 75,
      "item_discount": 0,
      "recurring_item_discount": 0,
      "item_tax": 0,
      "recurring_item_tax": 0,
      "discount_total": 0,
      "recurring_discount_total": 0,
      "tax_total": 0,
      "recurring_tax_total": 0,
      "tax_included_total": 0,
      "recurring_tax_included_total": 0,
      "grand_total": 75,
      "recurring_total": 75,
      "ordering": true,
      "plan_id": null,
      "plan_name": null,
      "interval": "monthly",
      "interval_count": 1,
      "trial_days": 0,
      "taxes": null,
      "active": true,
      "date_period_start": "2023-08-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",
      "notified_payment_expiring": false,
      "date_payment_retry": null,
      "payment_error": "Unable to complete payment, invoice not found",
      "retry_resolve": "unpaid",
      "date_payment_failed": "2023-01-27T18:15:03.450Z",
      "id": "62b9f39d8b9a9a00133b7784"
    },
    . . .

Delete a subscription

Delete a subscription permanently.

Arguments

id

objectIdrequired

The id of the subscription to delete.

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

await swell.delete('/subscriptions/{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: SubscriptionsNext: Accounts →
© 2023 Swell
Terms of servicePrivacy policy