Backend API
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"
}