Backend API
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.