Frontend API
Manage subscriptions associated with the logged-in customer's account.
Return a list of active and canceled subscriptions for an account.
Returns all subscriptions, with offset pagination using limit and page.
await swell.subscriptions.list()
Return a single subscription by ID.
await swell.subscriptions.get(id)
Methods to create, update, and pause a subscription.
Subscribe the customer to a new product for recurring billing.
await swell.subscriptions.create({
product_id: '5c15505200c7d14d851e510f',
// the following parameters are optional
variant_id: '5c15505200c7d14d851e510g',
quantity: 1,
coupon_code: '10PERCENTOFF',
items: [
{
product_id: '5c15505200c7d14d851e510h',
quantity: 1
}
]
})
Updates a single subscription.
await swell.subscriptions.update('5c15505200c7d14d851e510f', {
// the following parameters are optional
quantity: 2,
coupon_code: '10PERCENTOFF',
items: [
{
product_id: '5c15505200c7d14d851e510h',
quantity: 1
}
]
})
Pauses a subscription indefinitely or skips a billing cycle.
await swell.subscriptions.update(subscription.id, {
paused: true,
date_pause_end: null
})
Cancel a single subscription.
await swell.subscriptions.update('5c15505200c7d14d851e510f', {
canceled: true
})
Methods to add, update, and remove an invoice item on a subscription.
Returns the updated subscriptions object.
await swell.subscriptions.addItem('5c15505200c7d14d851e510f', {
product_id: '5c15505200c7d14d851e510f',
quantity: 1,
options: [
{
id: 'color',
value: 'Blue'
}
]
})
Returns the updated subscriptions object.
await swell.subscriptions.updateItem('5c15505200c7d14d851e510f', '<item_id>', {
quantity: 2
})
Returns the updated subscriptions object.
await swell.subscriptions.removeItem('5c15505200c7d14d851e510f', '<item_id>')
Manage subscriptions associated with the logged-in customer's account.
List subscriptions
Return a list of active and canceled subscriptions for an account.
The parameters of this query are search, where, sort, limit, page, _locale, and _currency.
query getSubscriptions {
subscriptions(_currency: "USD") {
results {
id
status
datePeriodEnd
product {
name
id
slug
price
}
billingSchedule {
interval
intervalCount
trialDays
}
recurringTotal
}
}
}
Get a subscription
Return a single subscription by ID.
The parameters of this query are id, _locale, and _currency.
query getSubscriptionById {
subscriptionById(id: "62b1e30767145000197b2bc0") {
status
datePeriodEnd
quantity
trial
dateTrialEnd
product {
id
name
slug
price
}
grandTotal
currency
shipping {
name
address1
city
state
country
zip
}
billing {
name
address1
city
state
country
zip
method
card {
brand
last4
expMonth
expYear
}
}
billingSchedule {
interval
intervalCount
}
}
}Subscription management
Methods to create, update, and pause a subscription.
Create a new subscription
Subscribe the customer to a new product for recurring billing. Returns the updated subscription object.
The parameters of this mutation are input (required).
mutation createSubscription {
createSubscription(
input: { productId: "62b1e30767145000197b2bbf", quantity: 1 }
) {
product {
name
id
price
}
quantity
trial
grandTotal
}
}Update a subscription
Updates a single subscription. Returns the updated subscription object.
The parameters of this mutation are id (required) and input (required).
mutation updateSubscription {
updateSubscription(
id: "62b9ee09e744d10013710365"
input: {
productId: "62b1e30767145000197b2bbf"
quantity: 2
couponCode: "10PERCENTOFF"
}
) {
product {
name
id
price
}
quantity
trial
grandTotal
}
}Pause a subscription
Pauses a subscription indefinitely or skips a billing cycle. Returns the updated subscription object.
The parameters of this mutation are id (required) and input (required).
mutation pauseSubscription {
updateSubscription(
id: "62b9ee09e744d10013710365"
input: { paused: true, datePauseEnd: null }
) {
product {
name
id
price
}
status
quantity
grandTotal
}
}
Cancel a subscription
Cancel a single subscription. Returns the updated subscription object.
The parameters of this mutation are id (required) and input (required).
mutation cancelSubscription {
updateSubscription(
id: "62b9ee09e744d10013710365"
input: { productId: "62b1e30767145000197b2bbf", canceled: true }
) {
product {
name
id
price
}
status
quantity
grandTotal
}
}Invoice management
Methods to add, update, and remove an invoice item on a subscription.
Add an invoice item
Add an invoice item to a subscription. Returns the updated subscription object.
The parameters of this mutation are subscriptionId (required) and input (required).
mutation addSubscriptionItem {
addSubscriptionItem(
subscriptionId: "62b9f39d8b9a9a00133b7784"
input: { productId: "62b1e30767145000197b2bbf", quantity: 1 }
) {
product {
name
id
price
}
quantity
priceTotal
}
}Update an item
Update an invoice item on a subscription. Returns the updated subscription object.
The parameters of this mutation are subscriptionId (required), itemId (required), and input (required).
mutation updateSubscriptionItem {
updateSubscriptionItem(
subscriptionId: "62b9f39d8b9a9a00133b7784"
itemId: "62b9f12391fed80013478224"
input: { quantity: 2 }
) {
product {
name
id
price
}
quantity
grandTotal
}
}Remove an item
Remove an item from a subscription. Returns the updated subscription object.
The parameters of this mutation are subscriptionId (required) and itemId (required).
mutation deleteSubscriptionItem {
deleteSubscriptionItem(
subscriptionId: "62b9f39d8b9a9a00133b7784"
itemId: "62b9f12391fed80013478224"
) {
product {
name
id
price
}
quantity
priceTotal
}
}