Backend API
Purchase links allow you to configure a pre-selected group of products within a cart and direct a customer to its checkout through a designated URL. Once enabled, the URL will be active and will direct anyone who clicks the link to an instance of the checkout, pre-populated with the products associated with that link.
Fields
The unique identifier for the purchase link.
Human-friendly name of the purchase link.
The active status of the purchase link is automatically set to off and must be toggled on to activate, share, and use.
Expandable link to the coupon applied to purchase link items.
ID of the coupon applied to purchase link items.
Three-letter ISO currency code in uppercase. Defaults to your store's base currency.
Date the purchase link was created.
Date the purchase link was last updated.
Total discount amount.
Discounts applied to purchase link items.
Unique identifier for the object.
Type of discount. Can be coupon or promo-<id> referring to the source of the discount. Custom discounts don't require this value.
Object describing the discount rule details. Custom discounts don't require this value.
Fixed discount amount.
Grand total including items, shipping, and taxes.
Total discount applied to line items.
List of line items describing the products ordered.
Unique identifier for the item.
Quantity of the bundle item being ordered. Defaults to 1.
Price of the item. If a product price is reduced by a sale or price rule, this would be set to the reduced price automatically. Also, item price can be overridden when adding to a cart. Line item prices don't change unless explicitly edited by a store admin.
Total price added to sub total by multiplying quantity and price.
Configuration of one or more purchase options for purchase link items. Can be standard for one-time purchases or subscription for a subscription plan. Products can support both purchase options simultaneously.
Possible enum values:
ID of the subscription plan.
Options that allow for variations of the base product within the purchase link. If the option is part of a variant or required=true, an option value must be set for the product to be added to a purchase link cart.
Unique identifier for the object.
Name value of the product option. When adding to the cart, specify either the product option value id or name (case-insensitive) to identify the value.
List of items offered as a bundle. Defaults to product.bundle_items.
Unique identifier for the object.
Quantity of the bundle item being ordered. Defaults to 1.
ID of the bundle item product.
Expandable link to the bundle item product.
ID of the bundle item variant.
Expandable link to the bundle item variant.
Unique identifier for the object.
Name value of the product option. When adding to the cart, specify either the product option value id or name (case-insensitive) to identify the value.
ID of product in the purchase link.
Expandable link to the product within the purchase link.
ID of the product variant, if applicable.
Expandable link to the product variant.
List of discounts applied to the item by coupons, promotions, or custom logic.
Unique identifier for the object. Refers to one of the IDs in the cart discounts object.
Fixed discount amount.
Total discount applied to the item.
Total discount amount divided by quantity.
Arbitrary item data, typically set in a checkout flow to store custom values. See Storefront API for details.
Arbitrary data, typically set in a checkout flow to store custom values. See Frontend API for more details.
Array of promotion ids associated to the purchase link.
Link to promotions associated to the purchase link.
The subtotal of all of the items in a purchase link.
The purchase link model
{
"active": true,
"name": "Mythic Dawn Commentaries Collection",
"items": [
{
"product_id": "628ba6011869c10019b41f70",
"quantity": 1,
"price": 60,
"id": "628ba7241869c10019b41f7d",
"orig_price": 60,
"delivery": "shipment",
"shipment_weight": 0,
"price_total": 60,
"discount_total": 0,
"discount_each": 0
},
{
"product_id": "628ba67a1869c10019b41f76",
"quantity": 1,
"price": 60,
"id": "628ba728499bba0019b1a9c2",
"orig_price": 60,
"delivery": "shipment",
"shipment_weight": 0,
"price_total": 60,
"discount_total": 0,
"discount_each": 0
},
{
"product_id": "628ba6b7499bba0019b1a9b2",
"quantity": 1,
"price": 60,
"id": "628ba72b499bba0019b1a9c5",
"orig_price": 60,
"delivery": "shipment",
"shipment_weight": 0,
"price_total": 60,
"discount_total": 0,
"discount_each": 0
},
{
"product_id": "628ba701499bba0019b1a9bb",
"quantity": 1,
"price": 60,
"id": "628ba72d499bba0019b1a9c8",
"orig_price": 60,
"delivery": "shipment",
"shipment_weight": 0,
"price_total": 60,
"discount_total": 0,
"discount_each": 0
}
],
"shipment_delivery": true,
"currency": "USD",
"sub_total": 240,
"item_discount": 0,
"discount_total": 0,
"grand_total": 240,
"date_created": "2022-05-23T15:24:20.977Z",
"date_updated": "2022-05-23T15:24:32.137Z",
"id": "5wFVZQzV"
}Create a purchase link.
Arguments
Human-friendly name of the purchase link.
List of line items describing the products ordered.
List of items offered as a bundle. Defaults to product.bundle_items.
ID of the bundle item product.
ID of the bundle item product.
Expandable link to the bundle product.
Quantity of the bundle item being ordered. Defaults to 1.
Weight to be used in shipping calculation, if applicable.
ID of the bundle item variant.
Expandable link to the bundle variant.
Description used for custom line items, when product is not defined.
List of discounts to apply to the item. Normally populated by applying a coupon or promotions.
Unique identifier for the object. Should refer to one of the IDs in the cart discounts object.
Fixed discount amount.
Arbitrary item data, typically set in a checkout flow to store custom values. See Storefront API for details.
Item options matching one or more of product.options. When adding to the cart, specify either option id or name (case-insensitive) to identify the option.
Gift card products have two special options that can be used when fulfilling gift cards by email. Use the option ID send_email and value as the recipient email address, and send_note as a custom message from the customer to the recipient sent by email.
Unique identifier for the object.
Name of the product option. Populated automatically when adding an option by ID.
Additional price added onto the base price of the product.
Additional shipping weight added onto the base weight of the product.
Name value of the product option. When adding to the cart, specify either the product option value id or name (case-insensitive) to identify the value.
Indicates the option refers to a variant aspect.
Method of delivery taken automatically from product.delivery
Possible enum values:
Price of the item. Override this value to set a custom price. Defaults to product price or sale price.
ID of the item product.
Expandable link to the product, if applicable.
Quantity of the item being ordered. Defaults to 1.
Weight to be used in shipping calculation, if applicable.
List of tax rules to apply to the item. Normally populated by tax settings.
Unique identifier for the object. Should refer to one of the IDs in the cart taxes object.
Fixed tax amount.
ID of the item variant, if applicable.
Expandable link to the variant, if applicable.
Indicates the cart has been updated by a customer within the last 3 hours.
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');
await swell.post('/purchaselinks', {
name: 'Purchase link example',
active: true,
items: [
{
product_id: '626034d4e7b741001968292d',
quantity: 1,
}
],
});Response
{
"active": true,
"name": "Purchase link example",
"items": [
{
"product_id": "626034d4e7b741001968292d",
"quantity": 1,
"price": 5,
"price_total": 5,
"discount_total": 0,
"discount_each": 0,
"id": "62681502ea4c3f00138da5ea"
}
],
"currency": "USD",
"sub_total": 5,
"item_discount": 0,
"discount_total": 0,
"grand_total": 5,
"date_created": "2022-04-26T15:51:30.324Z",
"date_updated": "2022-04-26T15:52:33.949Z",
"id": "DEEFRebs"
}Retrieve a purchase link.
Arguments
The id of the cart to retrieve.
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');
await swell.get('/purchaselinks/{id}');Response
{
"active": true,
"name": "Purchase link example",
"items": [
{
"product_id": "626034d4e7b741001968292d",
"quantity": 1,
"price": 5,
"price_total": 5,
"discount_total": 0,
"discount_each": 0,
"id": "62681502ea4c3f00138da5ea"
}
],
"currency": "USD",
"sub_total": 5,
"item_discount": 0,
"discount_total": 0,
"grand_total": 5,
"date_created": "2022-04-26T15:51:30.324Z",
"date_updated": "2022-04-26T15:52:33.949Z",
"id": "DEEFRebs"
}Update a purchase link.
Arguments
Unique identifier for the cart.
Human-friendly name of the purchase link.
The active status of the purchase link is automatically set to off and must be toggled on to activate, share, and use.
List of line items describing the products ordered.
List of items offered as a bundle. Defaults to product.bundle_items.
ID of the bundle item product.
ID of the bundle item product.
Expandable link to the bundle product.
Quantity of the bundle item being ordered. Defaults to 1.
Weight to be used in shipping calculation, if applicable.
ID of the bundle item variant.
Expandable link to the bundle variant.
Description used for custom line items, when product is not defined.
List of discounts to apply to the item. Normally populated by applying a coupon or promotions.
Unique identifier for the object. Should refer to one of the IDs in the cart discounts object.
Fixed discount amount.
Arbitrary item data, typically set in a checkout flow to store custom values. See Storefront API for details.
Item options matching one or more of product.options. When adding to the cart, specify either option id or name (case-insensitive) to identify the option.
Gift card products have two special options that can be used when fulfilling gift cards by email. Use the option ID send_email and value as the recipient email address, and send_note as a custom message from the customer to the recipient sent by email.
Unique identifier for the object.
Name of the product option. Populated automatically when adding an option by ID.
Additional price added onto the base price of the product.
Additional shipping weight added onto the base weight of the product.
Name value of the product option. When adding to the cart, specify either the product option value id or name (case-insensitive) to identify the value.
Indicates the option refers to a variant aspect.
Method of delivery taken automatically from product.delivery
Possible enum values:
Price of the item. Override this value to set a custom price. Defaults to product price or sale price.
ID of the item product.
Expandable link to the product, if applicable.
Quantity of the item being ordered. Defaults to 1.
Weight to be used in shipping calculation, if applicable.
List of tax rules to apply to the item. Normally populated by tax settings.
Unique identifier for the object. Should refer to one of the IDs in the cart taxes object.
Fixed tax amount.
ID of the item variant, if applicable.
Expandable link to the variant, if applicable.
Coupon code applied to the cart. See coupons for details.
List of promotion IDs applied to the cart.
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');
await swell.put('/purchaselinks/{id}', {
id: 'DEEFRebs',
active: true
});Response
{
"active": true,
"name": "Purchase link example",
"items": [
{
"product_id": "626034d4e7b741001968292d",
"quantity": 1,
"price": 5,
"price_total": 5,
"discount_total": 0,
"discount_each": 0,
"id": "62681502ea4c3f00138da5ea"
}
],
"currency": "USD",
"sub_total": 5,
"item_discount": 0,
"discount_total": 0,
"grand_total": 5,
"date_created": "2022-04-26T15:51:30.324Z",
"date_updated": "2022-04-26T15:52:33.949Z",
"id": "DEEFRebs"
}List all purchase links.
Arguments
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('/purchaselinks/');Response
{
"count": 39,
"results": [
{
"active": true,
"name": "Purchase link example",
"items": [
{
"product_id": "626034d4e7b741001968292d",
"options": [
{
"id": "626034de60bd1a69a444f233",
"name": "Size20-04",
"value": "s",
"value_id": "626034ee60bd1a69a444f234",
"variant": true
}
],
"quantity": 1,
"price": 5,
"price_total": 5,
"discount_total": 0,
"discount_each": 0,
"id": "62681502ea4c3f00138da5ea"
}
],
"currency": "USD",
"sub_total": 5,
"item_discount": 0,
"discount_total": 0,
"grand_total": 5,
"date_created": "2022-04-26T15:51:30.324Z",
"date_updated": "2022-04-26T15:52:33.949Z",
"id": "DEEFRebs"
},
{
"active": true,
"name": "Test items",
"items": [
{
"product_id": "625daa41e6e0e30019c4a084",
"quantity": 1,
"price": 100,
"id": "625daa53e6e0e30019c4a2a3",
"orig_price": 100,
"delivery": "shipment",
"shipment_weight": 0,
"price_total": 100,
"discount_total": 50,
"discount_each": 50,
"discounts": [
{
"id": "coupon-0",
"amount": 50
}
]
}
],
"shipment_delivery": true,
"currency": "USD",
"sub_total": 100,
"item_discount": 50,
"discount_total": 50,
"grand_total": 50,
"date_created": "2022-04-18T17:51:34.937Z",
"date_updated": "2022-04-18T18:13:40.581Z",
"coupon_code": "SIMPLETEST",
"promotion_ids": [
null,
null,
null,
null,
null,
null,
null,
"625da6a2e6e0e30019c471dd"
],
"coupon_id": "625da691e6e0e30019c46fea",
"discounts": [
{
"type": "coupon",
"rule": {
"value_fixed": 50,
"type": "total",
"value_type": "fixed"
},
"amount": 50,
"id": "coupon-0"
}
],
"shipment_discount": null,
"id": "vASbh0zY"
},
{
"name": "NEW PURCHASE LINK",
"items": [
{
"purchase_option": {
"plan_id": "6256eb710c7aaf0012dd1731",
"billing_schedule": {
"interval": "weekly",
"interval_count": 1,
"trial_days": 0,
"limit": null
},
"type": "subscription",
"plan_name": "Weekly"
},
"quantity": 1,
"price": 65,
"product_id": "6256eb710c7aaf0012dd1722",
"id": "62599ad09a57a6001a8ca827",
"orig_price": 65,
"shipment_weight": 0,
"price_total": 65,
"discount_total": 0,
"discount_each": 0
}
],
"subscription_delivery": true,
"currency": "USD",
"sub_total": 65,
"item_discount": 0,
"discount_total": 0,
"grand_total": 65,
"date_created": "2022-04-15T16:18:24.644Z",
"active": true,
"date_updated": "2022-04-15T16:31:35.254Z",
"id": "midpIahm"
},
. . .
],
"page": 1,
"pages": {
"1": {
"start": 1,
"end": 15
},
"2": {
"start": 16,
"end": 30
},
"3": {
"start": 31,
"end": 39
}
}
}Delete a purchase link.
Arguments
The id for the purchase link to delete.
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');
await swell.delete('/purchaselinks/{id}', {
});Response
{
"active": true,
"name": "Purchase link example",
"items": [
{
"product_id": "626034d4e7b741001968292d",
"quantity": 1,
"price": 5,
"price_total": 5,
"discount_total": 0,
"discount_each": 0,
"id": "62681502ea4c3f00138da5ea"
}
],
"currency": "USD",
"sub_total": 5,
"item_discount": 0,
"discount_total": 0,
"grand_total": 5,
"date_created": "2022-04-26T15:51:30.324Z",
"date_updated": "2022-04-26T15:52:33.949Z",
"id": "DEEFRebs"
}