Backend API
Subscriptions allow charging a customer on a recurring basis. A subscription is created when a customer purchases a plan from a product's subscription purchase_option. 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 for a physical product, or a product that contains physical bundle_items.
The subscription model represents a recurring order that is associated with a user's account and billed at regular intervals.
Fields
Unique identifier for the subscription.
ID of the subscribed customer's account.
Expandable link to the subscribed customer's account.
ID of the subscription plan product.
Expandable link to the subscription plan product.
Indicates the subscription is currently active.
Subscription billing details.
Billing full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.
Billing first name. If name is updated, then first_name will be automatically updated as the first word of the name.
Billing last name. If name is updated, then last_name will be automatically updated as the first word of the name.
Billing address line 1: street address/PO box/company name.
Billing address line 2: apartment/suite/unit/building.
Billing city/district/suburb/town/village.
Billing state/county/province/region.
VAT number associated with the billing address, if applicable.
Billing zip/postal code.
Two-letter ISO code country code.
Billing phone number.
Method of payment. Can be card, account, amazon, paypal, or any one of the manual methods defined in payment settings.
Token generated by Swell Checkout or Stripe.js.
Two-digit number representing the credit card expiration month.
Four-digit number representing the credit card expiration year.
Credit card brand. Can be American Express, Diners Club, Discover, JCB, MasterCard, UnionPay, Visa, or Unknown.
Brand of the card displayed to the customer, if different from the underlying brand (for example, co-branded cards).
Last four digits of the card number.
ID of the payment gateway that should be used to process payments.
Indicates this is a test card.
When used with a payment gateway that performs address checks and address1 was provided, can be pass, fail, unavailable, or unchecked.
When used with a payment gateway that performs address checks and zip was provided, can be pass, fail, unavailable, or unchecked.
When used with a payment gateway that performs CVC code checks and cvc was provided, can be pass, fail, unavailable, or unchecked.
Stores the necessary information about the payment. This is typically the payment ID returned by the gateway after payment is initialized.
Indicates billing details represent the customer's default payment method.
When true, inherits the address tied to the user's account.
ID of the customer's credit card on file, if applicable.
Expandable link to the customer's credit card on file, if applicable.
Billing schedule for subscription plan.
Subscription plan billing interval. Can be daily, weekly, monthly, or yearly.
Possible enum values:
Multiplier for billing interval. For example, to make the billing cycle once every two weeks, set interval=weekly and interval_count=2.
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.
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.
Current number of billing cycles that have occured.
Limit date for marking the end of the billing cycle.
ID of the corresponding bundle item, if applicable.
When true, indicates the subscription was or will be canceled at the end of the billing period.
Determines whether the subscription is canceled immediately or according to a specified schedule.
A brief message describing the reason the subscription was canceled, if applicable.
Indicates the subscription was canceled.
Indicates the subscription plan has completed all cycles.
Expandable link to the coupon applied to the subscription.
Coupon code applied to the subscription. See coupons for details.
ID of the coupon applied to the subscription.
Three-letter ISO currency code in uppercase. Defaults to the store's base currency.
Currency rate used in calculating the fixed amount.
Date the subscription was canceled, if applicable.
Cancel the subscription on the specified date.
Date when the subscription was un-canceled and restored to active status.
Date and time the subscription was created.
Deprecated: use date_order_period_start instead. Start date for the subscription order cycle.
End date for the subscription order period.
Start date for the subscription order period.
Date the subscription was unpaused, if applicable.
Date the subscription was paused, if applicable.
Pause the subscription on the specified date.
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 when the last automated payment failed, if applicable.
When automated payment has failed, this is the date when the system will automatically retry.
End date of the current billing period.
Start date of the current billing period.
Date the subscription was last prorated, if applicable. Used to calculate the charge or credit applied when the subscription is prorated.
The date a subscription was resumed.
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 the trial period started, if applicable.
Date and time the subscription was last updated.
Total discount amount.
List of all discounts applied to the subscription.
Unique identifier for the object.
Fixed discount amount.
Object describing the discount rule details. Custom discounts don't require this value.
ID of the source object that generated the discount, such as a coupon or promotion.
Type of discount. Can be coupon or sale referring to the source of the discount. Custom discounts don't require this value.
Possible enum values:
Indicates the subscription is a draft.
Grand total of the next invoice including line items and taxes.
Amount invoiced for the last billing period.
Expandable list of all invoices created by the subscription.
Total discount applied to line items.
Total taxes applied to line items.
Amount invoiced for the last billing period.
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.
Unique identifier for the object.
List of products sold as a bundle. Applicable only when bundle=true.
Unique identifier for the bundle item.
ID of the bundled product.
Expandable link to the bundled product.
Quantity of the bundled product. Defaults to 1.
Price of the bundle item.
Discount amount applied to each unit of the bundle item.
Tax amount applied to each unit of the bundle item.
Ratio of the bundle price allocated to this item.
ID of the bundled variant, if applicable.
Expandable link to the bundled product variant, if applicable.
Total quantity of bundle items.
Date and time the object was created.
A long-form description of the options. May contain HTML or other markup languages.
Total discount amount divided by quantity.
Total discount applied to the item.
List of discounts applied to the line item by coupons.
Unique identifier for the object.
Fixed discount amount.
Item options matching one or more of product.options, if applicable. When setting this value, specify either option id or name (case-insensitive) to identify the option.
Unique identifier for the object.
Name of the option. Populated automatically when adding an option by ID.
Price of the option added to plan price when selected.
If specified, shipping is calculated using this weight. Otherwise, Swell assumes 1 lb/oz/kg — depending on store's default weight unit.
Name value of the option. When setting this value, specify either the product option value id or name (case-insensitive) to identify the value.
Indicates the option refers to a variant aspect.
Price of the line item. Defaults to product price, if applicable. A negative value will be subtracted from the plan total and credited to the customer on their next invoice.
Total price of the line item (price * quantity).
ID of the item product, if applicable.
Expandable link to the item product, if applicable.
Indicates the item represents a proration charge or credit.
Quantity of the line item.
Indicates the item will remain on the subscription after the next invoice is created.
Total recurring discount amount divided by quantity, if applicable.
Total recurring discount applied to the item, if applicable.
Recurring price of the item, if applicable.
Total recurring price of the item (price * quantity), if applicable.
Total recurring tax amount divided by quantity, if applicable.
Total recurring tax applied to the item, if applicable.
Total tax amount divided by quantity.
Total tax applied to the item.
List of tax rules applied to the item based on tax settings.
Unique identifier for the object.
Fixed tax amount.
ID of the item variant, if applicable.
Expandable link to the item variant, if applicable.
Delivery frequency for the item.
Possible enum values:
Internal admin notes. These are not visible to the customer. This field holds a single block of text. To record a series of notes against the subscription, each attributed to a user, see Notes.
The order number for the subscription, based on the store order number format.
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.
Unique identifier for the object.
Name of the plan option. Populated automatically when adding an option by ID.
Price of the option added to plan price when selected.
Name value of the plan option. When setting this value, specify either value id or name (case-insensitive) to identify the value.
Indicates the option refers to a variant aspect.
ID of the order that originated the subscription, if applicable.
ID of the line item from the order that originated the subscription, if applicable.
Order schedule for the subscription plan.
Order interval for subscription plan. Can be monthly, daily, weekly, and yearly.
Possible enum values:
Multiplier for order interval. For example, to generate the subscription order once every two weeks, set interval=weekly and interval_count=2.
Specifies a limit to the number of orders created. For example, "limit"=10 would stop creating orders after the tenth order.
Designates the end date of the order cycle.
Indicates the subscription is actively placing orders.
Expandable list of all orders created by the subscription plan. This happens when a plan contains physical products as bundle_items.
Indicates the last invoice was fully paid.
Determines whether the subscription is paused at the end of the current billing period.
Determines whether the subscription is paused immediately or according to the schedule.
Number of billing cycles to skip while the subscription is paused.
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.
Total amount of payments for the last billing period.
Expandable list of all payments made on behalf of the subscription.
Expandable list of invoices that haven't been fully paid.
ID of the subscription plan.
Name of the subscription plan.
Price of the plan. Plan price can be overridden when creating or updating a subscription.
Total price of the plan (price * quantity).
Total discount amount of the subscription plan, divided by quantity.
Total discount applied to the subscription plan.
List of discounts applied to the subscription plan by coupons.
ID of the coupon applied for a discount.
Discount amount.
This field is a copy of the item's product.name.
Total tax amount of the subscription plan, divided by quantity.
Total tax applied to the subscription plan.
List of tax rules applied to the subscription plan based on tax settings.
Unique identifier for the object. Refers to one of the ids in the subscription taxes object.
Fixed tax amount.
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 of the plan to charge.
Total recurring discount applied to the subscription including line items.
Total discount applied to recurring line items.
Total taxes applied to recurring line items.
Sum of all recurring line items before discounts and taxes.
Total of taxes applied separately from the subscription plan and recurring line items.
Total taxes applied to the subscription including recurring line items.
Recurring total of the subscription including line items and taxes.
Total amount of refunds for the last billing period.
Expandable list of all refunds made on behalf of the subscription.
Current status of the subscription. Can be pending, active, trial, pastdue, unpaid, canceled, or paid.
Possible enum values:
Sum of all line items before discounts and taxes.
Indicates the subscription plan price includes taxes.
Total of taxes applied separately from the subscription plan and line items.
Total taxes applied to the subscription including line items.
List of taxes applied to the subscription.
Unique identifier for the object.
Fixed tax amount.
Name of the tax rule. For example "NY Sales Tax".
Priority indicates the order in which a tax rule was applied. Higher priority rules are added on top of other tax rules with a lower priority. Rules with the same priority are calculated excluding each other.
Tax percentage used in calculating the fixed amount.
When true, taxes are not applied to the subscription. When false, taxes are calculated and applied to the subscription.
Indicates the subscription is in a trial period and the first invoice will be issued on date_trial_end.
Indicates the last invoice was marked as unpaid. This occurs automatically after all payment attempts are exhausted, as configured in subscription settings.
Expandable link to the subscription plan variant, if applicable.
ID of the subscription plan variant, if applicable.
Name of the variant.
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
ID of the subscribed customer's account.
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.
Subscription billing details.
Billing full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.
Billing first name. If name is updated, then first_name will be automatically updated as the first word of the name.
Billing last name. If name is updated, then last_name will be automatically updated as the first word of the name.
Billing address line 1: street address/PO box/company name.
Billing address line 2: apartment/suite/unit/building.
Billing city/district/suburb/town/village.
Billing state/county/province/region.
Billing zip/postal code.
Two-letter ISO code country code.
Billing phone number.
Method of payment. Can be card, account, amazon, paypal, or any one of the manual methods defined in payment settings.
Token generated by Swell Checkout or Stripe.js.
Two-digit number representing the credit card expiration month.
Four-digit number representing the credit card expiration year.
Credit card brand. Can be American Express, Diners Club, Discover, JCB, MasterCard, UnionPay, Visa, or Unknown.
Last four digits of the card number.
ID of the payment gateway that should be used to process payments.
Indicates this is a test card.
When used with a payment gateway that performs address checks and address1 was provided, can be pass, fail, unavailable, or unchecked.
When used with a payment gateway that performs address checks and zip was provided, can be pass, fail, unavailable, or unchecked.
When used with a payment gateway that performs CVC code checks and cvc was provided, can be pass, fail, unavailable, or unchecked.
Stores the necessary information about the payment. This is typically the payment ID returned by the gateway after payment is initialized.
Indicates billing details represent the customer's default payment method.
When true, inherits the address tied to the user's account.
ID of the customer's credit card on file, if applicable.
Expandable link to the customer's credit card on file, if applicable.
Coupon code applied to the subscription. See coupons for details.
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.
Quantity of the plan to charge.
Expandable link to the subscribed customer's account.
Indicates the subscription is currently active.
Billing schedule for subscription plan.
Subscription plan billing interval. Can be daily, weekly, monthly, or yearly.
Possible enum values:
Multiplier for billing interval. For example, to make the billing cycle once every two weeks, set interval=weekly and interval_count=2.
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.
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.
Current number of billing cycles that have occured.
Limit date for marking the end of the billing cycle.
ID of the corresponding bundle item, if applicable.
When `true`, indicates the subscription was or will be canceled at the end of the billing period.
A brief message describing the reason the subscription was canceled, if applicable.
Indicates the subscription was canceled.
Indicates the subscription plan has completed all cycles.
Expandable link to the coupon applied to the subscription.
ID of the coupon applied to the subscription.
Three-letter ISO currency code in uppercase. Defaults to the store's base currency.
Currency rate used in calculating the fixed amount.
Date the subscription was canceled, if applicable.
Start date fo the subscription order cycle.
End date for the subscription order period.
Start date of the subscription order cycle.
Date the subscription was unpaused, if applicable.
Date the subscription was paused, if applicable.
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 when the last automated payment failed, if applicable.
When automated payment has failed, this is the date when the system will automatically retry.
End date of the current billing period.
Start date of the current billing period.
Date the subscription was last prorated, if applicable. Used to calculate the charge or credit applied when the subscription is prorated.
The date a subscription was resumed.
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 the trial period started, if applicable.
Total discount amount.
List of all discounts applied to the subscription.
Possible enum values:
Indicates the subscription is a draft.
Grand total of the next invoice including line items and taxes.
Amount invoiced for the last billing period.
Expandable list of all invoices created by the subscription.
Total discount applied to line items.
Total taxes applied to line items.
Amount invoiced for the last billing period.
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.
Possible enum values:
Internal admin notes. These are not visible to the customer.
The order number for the subscription, based on the store order number format.
ID of the order that originated the subscription, if applicable.
ID of the line item from the order that originated the subscription, if applicable.
Order schedule for the subscription plan.
Order interval for subscription plan. Can be monthly, daily, weekly, and yearly.
Possible enum values:
Multiplier for order interval. For example, to generate the subscription order once every two weeks, set interval=weekly and interval_count=2.
Specifies a limit to the number of orders created. For example, "limit"=10 would stop creating orders after the tenth order.
Designates the end date of the order cycle.
Indicates the subscription is actively placing orders.
Expandable list of all orders created by the subscription plan. This happens when a plan contains physical products as bundle_items.
Indicates the last invoice was fully paid.
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.
Total amount of payments for the last billing period.
Expandable list of all payments made on behalf of the subscription.
Expandable list of invoices that haven't been fully paid.
ID of the subscription plan.
Name of the subscription plan.
Price of the plan. Plan price can be overridden when creating or updating a subscription.
Total price of the plan (price * quantity).
Expandable link to the subscription plan product.
Total discount amount of the subscription plan, divided by quantity.
Total discount applied to the subscription plan.
List of discounts applied to the subscription plan by coupons.
This field is a copy of the item's product.name.
Total tax amount of the subscription plan, divided by quantity.
Total tax applied to the subscription plan.
List of tax rules applied to the subscription plan based on tax settings.
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.
Total recurring discount applied to the subscription including line items.
Total discount applied to recurring line items.
Total taxes applied to recurring line items.
Sum of all recurring line items before discounts and taxes.
Total of taxes applied separately from the subscription plan and recurring line items.
Total taxes applied to the subscription including recurring line items.
Recurring total of the subscription including line items and taxes.
Total amount of refunds for the last billing period.
Expandable list of all refunds made on behalf of the subscription.
Current status of the subscription. Can be pending, active, trial, pastdue, unpaid, canceled, or paid.
Possible enum values:
Sum of all line items before discounts and taxes.
Indicates the subscription plan price includes taxes.
Total of taxes applied separately from the subscription plan and line items.
Total taxes applied to the subscription including line items.
List of taxes applied to the subscription.
When true, taxes are not applied to the subscription. When false, taxes are calculated and applied to the subscription.
Indicates the subscription is in a trial period and the first invoice will be issued on date_trial_end.
Indicates the last invoice was marked as unpaid. This occurs automatically after all payment attempts are exhausted, as configured in subscription settings.
Expandable link to the subscription plan variant, if applicable.
ID of the subscription plan variant, if applicable.
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
}
]
});The subscription 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 an existing subscription using the ID that was returned when created.
Arguments
The id of the subscription to retrieve.
Expanding link fields and child collections is performed 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.
Return 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 category id is always returned.
Include one or more arbitrary queries in the response, possibly related to the main query.
See including for more details.
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');
await swell.get('/subscriptions/60f199509111e700000000b1');
The subscription 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 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
Unique identifier for the subscription.
Expandable link to the subscribed customer's account.
ID of the subscribed customer's account.
Indicates the subscription is currently active.
Subscription billing details.
Billing full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.
Billing first name. If name is updated, then first_name will be automatically updated as the first word of the name.
Billing last name. If name is updated, then last_name will be automatically updated as the first word of the name.
Billing address line 1: street address/PO box/company name.
Billing address line 2: apartment/suite/unit/building.
Billing city/district/suburb/town/village.
Billing state/county/province/region.
Billing zip/postal code.
Two-letter ISO code country code.
Billing phone number.
Method of payment. Can be card, account, amazon, paypal, or any one of the manual methods defined in payment settings.
Token generated by Swell Checkout or Stripe.js.
Two-digit number representing the credit card expiration month.
Four-digit number representing the credit card expiration year.
Credit card brand. Can be American Express, Diners Club, Discover, JCB, MasterCard, UnionPay, Visa, or Unknown.
Last four digits of the card number.
ID of the payment gateway that should be used to process payments.
Indicates this is a test card.
When used with a payment gateway that performs address checks and address1 was provided, can be pass, fail, unavailable, or unchecked.
When used with a payment gateway that performs address checks and zip was provided, can be pass, fail, unavailable, or unchecked.
When used with a payment gateway that performs CVC code checks and cvc was provided, can be pass, fail, unavailable, or unchecked.
Stores the necessary information about the payment. This is typically the payment ID returned by the gateway after payment is initialized.
Indicates billing details represent the customer's default payment method.
When true, inherits the address tied to the user's account.
ID of the customer's credit card on file, if applicable.
Expandable link to the customer's credit card on file, if applicable.
Billing schedule for subscription plan.
Subscription plan billing interval. Can be daily, weekly, monthly, or yearly.
Possible enum values:
Multiplier for billing interval. For example, to make the billing cycle once every two weeks, set interval=weekly and interval_count=2.
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.
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.
Current number of billing cycles that have occured.
Limit date for marking the end of the billing cycle.
ID of the corresponding bundle item, if applicable.
When true, indicates the subscription was or will be canceled at the end of the billing period.
A brief message describing the reason the subscription was canceled, if applicable.
Indicates the subscription was canceled.
Indicates the subscription plan has completed all cycles.
Expandable link to the coupon applied to the subscription.
Coupon code applied to the subscription. See coupons for details.
ID of the coupon applied to the subscription.
Three-letter ISO currency code in uppercase. Defaults to the store's base currency.
Currency rate used in calculating the fixed amount.
Date the subscription was canceled, if applicable.
Start date fo the subscription order cycle.
End date for the subscription order period.
Start date for the subscription order period.
Date the subscription was unpaused, if applicable.
Date the subscription was paused, if applicable.
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 when the last automated payment failed, if applicable.
When automated payment has failed, this is the date when the system will automatically retry.
End date of the current billing period.
Start date of the current billing period.
Date the subscription was last prorated, if applicable. Used to calculate the charge or credit applied when the subscription is prorated.
The date a subscription was resumed.
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 the trial period started, if applicable.
Total discount amount.
List of all discounts applied to the subscription.
Possible enum values:
Indicates the subscription is a draft.
Grand total of the next invoice including line items and taxes.
Amount invoiced for the last billing period.
Expandable list of all invoices created by the subscription.
Total discount applied to line items.
Total taxes applied to line items.
Amount invoiced for the last billing period.
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.
Possible enum values:
Internal admin notes. These are not visible to the customer.
The order number for the subscription, based on the store order number format.
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 of the order that originated the subscription, if applicable.
ID of the line item from the order that originated the subscription, if applicable.
Order schedule for the subscription plan.
Order interval for subscription plan. Can be monthly, daily, weekly, and yearly.
Possible enum values:
Multiplier for order interval. For example, to generate the subscription order once every two weeks, set interval=weekly and interval_count=2.
Specifies a limit to the number of orders created. For example, "limit"=10 would stop creating orders after the tenth order.
Designates the end date of the order cycle.
Indicates the subscription is actively placing orders.
Expandable list of all orders created by the subscription plan. This happens when a plan contains physical products as bundle_items.
Indicates the last invoice was fully paid.
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.
Total amount of payments for the last billing period.
Expandable list of all payments made on behalf of the subscription.
Expandable list of invoices that haven't been fully paid.
ID of the subscription plan.
Name of the subscription plan.
Price of the plan. Plan price can be overridden when creating or updating a subscription.
Total price of the plan (price * quantity).
Expandable link to the subscription plan product.
Total discount amount of the subscription plan, divided by quantity.
Total discount applied to the subscription plan.
List of discounts applied to the subscription plan by coupons.
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.
This field is a copy of the item's product.name.
Total tax amount of the subscription plan, divided by quantity.
Total tax applied to the subscription plan.
List of tax rules applied to the subscription plan based on tax settings.
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 of the plan to charge.
Total recurring discount applied to the subscription including line items.
Total discount applied to recurring line items.
Total taxes applied to recurring line items.
Sum of all recurring line items before discounts and taxes.
Total of taxes applied separately from the subscription plan and recurring line items.
Total taxes applied to the subscription including recurring line items.
Recurring total of the subscription including line items and taxes.
Total amount of refunds for the last billing period.
Expandable list of all refunds made on behalf of the subscription.
Current status of the subscription. Can be pending, active, trial, pastdue, unpaid, canceled, or paid.
Possible enum values:
Sum of all line items before discounts and taxes.
Indicates the subscription plan price includes taxes.
Total of taxes applied separately from the subscription plan and line items.
Total taxes applied to the subscription including line items.
List of taxes applied to the subscription.
When true, taxes are not applied to the subscription. When false, taxes are calculated and applied to the subscription.
Indicates the subscription is in a trial period and the first invoice will be issued on date_trial_end.
Indicates the last invoice was marked as unpaid. This occurs automatically after all payment attempts are exhausted, as configured in subscription settings.
Expandable link to the subscription plan variant, if applicable.
ID of the subscription plan variant, if applicable.
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');
await swell.put('/subscriptions/{id}', {
id: '60f199509111e700000000b1',
quantity: 2,
coupon_code: '10OFF'
});The subscription model
{
"id": "60f199509111e7000000009a",
"account_id": "60f199509111e700000000a0",
"product_id": "60f199509111e700000000a1",
"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 Skooma 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": "Skooma delivery",
"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"
}A subscription can be paused or canceled immediately, or scheduled to take effect on a future date. Both are driven by updating the subscription, and both distinguish intent from effect: canceled and paused record the intent, while active records whether the subscription is still running.
Set canceled to true with cancel_at_end set to false. When neither cancel_at_end nor cancel_at_schedule is already set on the subscription, sending canceled on its own cancels immediately too. The subscription is left with canceled: true, active: false, and date_canceled set to the current time.
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');
await swell.put('/subscriptions/{id}', {
id: '5c15505200c7d14d851e510f',
canceled: true,
cancel_at_end: false
});Send canceled together with cancel_at_schedule, or set the schedule first and confirm with canceled in a second request. The subscription is then canceled: true and active: true, with the calculated date in date_cancel_at. It keeps generating orders and invoices until that date, at which point active becomes false and date_canceled is set.
// Cancel on the next billing date
await swell.put('/subscriptions/{id}', {
id: '5c15505200c7d14d851e510f',
canceled: true,
cancel_at_schedule: 'billing'
});
// Or cancel on a specific date
await swell.put('/subscriptions/{id}', {
id: '5c15505200c7d14d851e510f',
canceled: true,
cancel_at_schedule: '2027-01-31T00:00:00.000Z'
});The same values apply to cancel_at_schedule and pause_at_schedule.
- billing: the end of the current billing period, from date_period_end. During a trial, date_trial_end is used instead.
- order: the end of the current order period, from date_order_period_end.
- first: whichever of the two comes first.
- last: whichever of the two comes last.
- An ISO 8601 date string: that exact date.
first and last both fall back to the billing period when the subscription has no order period. A value that cannot be read as a date, or a date that is not in the future, is ignored and no schedule is set.
Setting canceled to false reverses a cancellation whether it is still scheduled or already complete. A pending cancellation is dropped and date_cancel_at is cleared. A subscription that had already been canceled returns to active: true with date_canceled cleared, date_uncanceled set, and a new billing cycle starting immediately. If the most recent payment attempt had failed, it is retried.
await swell.put('/subscriptions/{id}', {
id: '5c15505200c7d14d851e510f',
canceled: false
});Pausing mirrors cancellation. Send paused: true with pause_at_end: false to pause immediately, which sets active: false and records date_paused. Send it with pause_at_schedule to schedule one, which keeps the subscription active and stores the calculated date in date_pause_at. Orders and invoices continue until that date.
Sending paused: true with pause_at_end: true is treated as pause_at_schedule: 'first'.
// Pause now
await swell.put('/subscriptions/{id}', {
id: '5c15505200c7d14d851e510f',
paused: true,
pause_at_end: false
});
// Pause at the end of the current billing period
await swell.put('/subscriptions/{id}', {
id: '5c15505200c7d14d851e510f',
paused: true,
pause_at_schedule: 'billing'
});Setting paused to false both cancels a pause that has not taken effect yet, clearing date_pause_at, and resumes a subscription that is already paused. Resuming always begins a new billing and ordering period, and an invoice or order is generated at that moment.
A resume can also be dated ahead. Set date_pause_end to resume at a specific time, or set pause_skip_cycles to resume after a number of cycles. Skipped cycles are counted from the current period end, following the same pause_at_schedule the pause used, and the result is stored in date_pause_end. A date_pause_end you provide takes precedence over pause_skip_cycles.
// Resume now, or drop a pause that hasn't taken effect
await swell.put('/subscriptions/{id}', {
id: '5c15505200c7d14d851e510f',
paused: false
});
// Resume two cycles after the current period ends
await swell.put('/subscriptions/{id}', {
id: '5c15505200c7d14d851e510f',
paused: false,
pause_skip_cycles: 2
});
// Resume on a specific date
await swell.put('/subscriptions/{id}', {
id: '5c15505200c7d14d851e510f',
date_pause_end: '2027-03-01T00:00:00.000Z'
});| State | canceled / paused | active | Orders and invoices |
| Active | false | true | Generated normally |
| Scheduled, waiting | true | true | Continue until the scheduled date |
| Canceled or paused immediately | true | false | Stopped |
| Stopping at period end, waiting | true | true | Stopped |
A subscription with canceled: true and active: true is therefore not yet finished. Read active to tell whether a subscription is still running, and date_cancel_at or date_pause_at to tell when it will stop.
Sending canceled: true with cancel_at_end: true, and no schedule set, stops orders and invoices right away while leaving active: true until the billing period ends. Sending paused: true with no scheduling fields behaves the same way for pausing. When cancel_at_schedule is present it takes precedence over cancel_at_end.
Return a list of subscriptions.
Fields
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.
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 one or more arbitrary queries in the response which are potentially related to the main query.
See including for more details.
Limit the number of records returned, ranging between 1 and 1000. Defaults to 15.
The page number of results to return given the specified or default limit.
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.
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.
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.
const { swell } = require('swell-node');
swell.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",
"name": "Wandering Traveller",
"card": {
"brand": "Visa",
"last4": "4242",
"exp_month": 7,
"exp_year": 2024,
"token": "card_s4FQeFxdb8ErigKVxS9cR3js"
},
"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",
"country": "US",
"name": "Wandering Traveller",
"account_address_id": "62acbbe0d69a3b0012c7eae5",
"use_account": true
},
"order_id": "62b9ee09e342a30012319601",
"order_item_id": "62b9f12391fed80013478224",
"product_id": "62b1e30767145000197b2bbf",
"product_name": "Skooma",
"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,
"discounts": [],
"items": [],
"price_total": 75,
"payment_balance": -81,
"trial": false,
"paid": false,
"unpaid": true,
"sub_total": 75,
"grand_total": 75,
"recurring_total": 75,
"ordering": true,
"plan_id": null,
"plan_name": null,
"active": true,
"date_period_start": "2023-08-27T18:14:53.861Z",
"date_period_end": "2023-09-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",
"date_payment_failed": "2023-01-27T18:15:03.450Z",
"payment_error": "Unable to complete payment, invoice not found",
"retry_resolve": "unpaid",
"id": "62b9f39d8b9a9a00133b7784"
},
. . . Delete a subscription permanently.
Arguments
The id of the subscription to delete.
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');
await swell.delete('/subscriptions/60f199509111e700000000c7');
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"
}