Backend API

Carts

A cart is a pending request to purchase products from your store. Carts contain all the information needed to fulfill a purchase. Once the customer is ready to complete their purchase, a simple API call is made to convert a cart to an order.

When managing items within a cart, utilize the items.id rather than the product.id

The cart model

Fields

id

objectId

Unique identifier for the cart.

abandoned

boolean

Indicates the cart was abandoned after 3 hours of inactivity. After being marked as abandoned, this field is automatically set back to false after an update to items, billing, or shipping info.

abandoned_notifications

int

Number of abandoned cart notifications sent to the customer.

account

Account

Expandable link to the customer's account.

account_credit_amount

currency

Amount of customer's account credit applied for initial payment, if applicable.

account_credit_applied

boolean

Indicates the customer's account credit is applied to the initial payment.

account_id

objectId

ID of the customer's account.

account_info_saved

boolean

Indicates the customer chose to save shipping and billing information to their account when submitting the order.

account_logged_in

boolean

Indicates the customer was logged into their account when placing the order.

active

boolean

Indicates the cart has been updated by a customer within the last 3 hours.

billing

object

The customer's billing details. Defaults to account.billing. Updating billing will also update the corresponding account billing object.

checkout_id

string

Customer-facing unique identifier for the cart used in URLs and for abandoned cart recovery.

checkout_url

string

URL to checkout for the cart, set automatically when the cart has at least items, shipping, or billing details set. Can also be set explicitly when creating or updating the cart for custom checkouts.

comments

string

Customer notes provided when placing the order, if any.

coupon

Coupon

Expandable link to the coupon applied to the cart.

coupon_code

string

Coupon code applied to the cart.

coupon_id

objectId

ID of the coupon applied to the cart.

currency

string

Three-letter ISO currency code in uppercase. Defaults to the store's base currency.

currency_rate

float

Currency percentage used in calculating the fixed amount.

date_abandoned

date

Date the cart was or will be marked as abandoned.

date_abandoned_next

date

Next date the cart will be marked as abandoned when using a series of abandoned cart recovery notices (advanced cart recovery).

date_created

dateauto

Date and time the cart was created.

date_updated

dateauto

Date and time the cart was last updated.

date_webhook_first_failed

date

Date the order webhook first failed, if applicable. Value is unset after an order webhook is successfully returned for the record.

date_webhook_last_succeeded

date

Date the order webhook last succeeded, if applicable. Value is unset after an order webhook fails to return for the record.

discount_total

currency

Total discount amount.

discounts

array of object

List of discounts applied to the cart.

display_currency

string

Three-letter ISO currency code representing the user's preferred display currency, if applicable.

display_locale

string

Locale code representing the user's preferred display locale, if applicable.

draft

boolean

Indicates the cart is a draft. The Swell dashboard uses draft carts to designate entries in the Draft orders section of the dashboard.

gift

boolean

Indicates the order is intended as a gift for the recipient.

gift_message

string

Optional message to include with the order when shipping to the recipient.

giftcard_delivery

boolean

Indicates the cart has at least one line item with delivery=giftcard.

giftcard_total

currencyauto

Total payment amount applied to the order from giftcards.

giftcards

array of object

List of gift cards applied to the cart.

grand_total

currencyauto

Grand total including items, shipping, and taxes.

guest

boolean

Indicates the customer was not logged in when placing the order.

item_discount

currency

Total discount applied to line items.

item_quantity

intauto

Total quantity of all line items.

item_shipment_weight

floatauto

Total shipping weight of all line items.

item_tax

currencyauto

Total taxes applied to line items.

item_tax_included

boolean

Indicates line item prices include taxes.

items

array of object

List of line items describing the products ordered.

metadata

object

Arbitrary data, typically set in a checkout flow to store custom values. See Frontend API for more details.

notes

string

Internal admin notes. These are not visible to the customer.

number

stringauto

Unique incremental cart number, assigned automatically using a format configured in general settings.

order

Order

Expandable link to the converted order, if applicable.

order_id

objectId

ID of the the converted order, if applicable.

orig_price

currency

Reflects the automatic price of an item, and indicates whether it's on sale or not, so as to determine if the price was customized by an API call.

promotion_ids

array of child_scalar

List of promotion IDs applied to the cart.

promotions

Promotion

Expandable list of promotions applied to the cart.

purchase_link_ids

array of string

Unique identifiers for the purchase links.

purchase_links

Purchase Link

Expandable links to the purchase links added to the cart.

purchase_links_errors

array of object

List of purchase link errors applied to the cart. Added when clicking on the purchase link, if any resources are blocking the creation of the cart.

recovered

boolean

Indicates the cart was recovered and converted to an order after being abandoned.

schedule

object

Schedule for a recurring order.

shipment_delivery

boolean

Indicates the cart has at least one line item with delivery=shipment.

shipment_discount

currency

Shipping discount applied by coupons, promotions, or custom logic.

shipment_price

currency

Total shipping price before discounts.

shipment_rating

object

Object describing the shipping services and rates available for the cart. Shipping country must be set before retrieving shipping rates.

shipment_tax

currency

Shipping tax amount, if applicable.

shipment_tax_included

boolean

Indicates shipping total includes taxes, if applicable.

shipment_total

currency

Total shipping price after discounts.

shipping

object

The customer's shipping details. Defaults to account.shipping. Updating shipping will also update the corresponding account shipping object.

status

enumauto

Current status of the cart. Can be active, converted, abandoned, or recovered.

Possible enum values:

convertedrecoveredabandonedactive

sub_total

currency

Sum of all line items before discounts, taxes and shipping.

subscription

Subscription

Expandable link to the subscription that spawned the order, if applicable.

subscription_delivery

boolean

Indicates the cart has at least one line item with delivery=subscription.

subscription_id

objectId

ID of the subscription that spawned the order, if applicable.

target_order

Order

Expands into the order that the cart was converted into.

target_order_id

objectId

When a cart is converted to an order, this field represents the corresponding order_id.

tax_included_total

currency

Total with shipping and item taxes included. Allows for an alternate display style, as normally sub_total and tax_total are shown separately.

tax_total

currency

Total tax amount applied to the cart including line items and shipping.

taxes

array of object

List of taxes applied to the cart.

taxes_fixed

boolean

Indicates the order is tax-exempt. Taxes will not be calculated or applied when true.

webhook_attempts_failed

int

Number of failed order webhook attempts, if applicable. Value is unset after an order webhook is successfully returned for the record.

webhook_response

string

Text response of the last failed order webhook attempt, if applicable. Value is unset after an order webhook is successfully returned for the record.

webhook_status

int

HTTP response status of the last failed order webhook attempt, if applicable. Value is unset after an order webhook is successfully returned for the record.

The cart model
{
  "id": "60f199509111e7000000000e",
  "abandoned": false,
  "account_id": "60f199509111e7000000000f",
  "account_info_saved": true,
  "account_logged_in": true,
  "billing": {
    "name": "Uriel Septim VII",
    "first_name": "Uriel",
    "last_name": "Septim",
    "address1": "Imperial City Palace",
    "city": "Imperial City",
    "state": "NY",
    "zip": 11201,
    "country": "US",
    "phone": "(555) 555-5555",
    "method": "card",
    "card": {
      "token": "card_1Ds1K7E30PFlZWil6Q7bJ1PD",
      "test": true,
      "last4": "4242",
      "brand": "Visa",
      "address_check": "unchecked",
      "zip_check": "unchecked",
      "cvc_check": "unchecked",
      "exp_month": 1,
      "exp_year": 2029,
      "fingerprints": "3e63991847bbdaafdbc5c8f110ad803f"
    },
    "account_card_id": "5c3ac9870b3b171a7dfaf089"
  },
  "checkout_id": "e785b5ac4355ceef41ae2fd1c47df4bc",
  "checkout_url": "https://example.swell.store/checkout/e785b5ac4355ceef41ae2fd1c47df4bc",
  "comments": null,
  "coupon_code": "DREAMS",
  "coupon_id": "60f199509111e70000000010",
  "currency": "USD",
  "date_created": "2021-07-16T14:36:00.057Z",
  "date_updated": "2021-07-16T14:36:00.057Z",
  "date_webhook_first_failed": null,
  "discount_total": 5,
  "discounts": [
    {
      "id": "coupon-0",
      "type": "coupon",
      "amount": 5,
      "rule": {
        "type": "product",
        "value_type": "fixed",
        "value_amount": 2.5,
        "product_id": "5c524166f4e8f3446a10331b"
      }
    }
  ],
  "gift_message": null,
  "giftcards": [
    {
      "id": "5841c5691c64c63e75d29e43",
      "amount": 25,
      "code": "B6UQY3DHRCM4BQYU",
      "code_formatted": "B6UQ Y3DH RCM4 BQYU",
      "last4": "BQYU"
    }
  ],
  "gift": true,
  "giftcard_total": 25,
  "grand_total": 41.98,
  "guest": false,
  "item_discount": 5,
  "item_quantity": 2,
  "item_shipment_weight": 2,
  "item_tax": 2,
  "items": [
    {
      "id": "5ca537326a0ec32a521139dd",
      "product_id": "5c524166f4e8f3446a10331b",
      "variant_id": "5c524166f4e8f3446a10331f",
      "quantity": 2,
      "price": 19.99,
      "price_total": 38.98,
      "orig_price": 19.99,
      "delivery": "shipment",
      "shipment_weight": 1,
      "options": [
        {
          "id": "5becb84fac207653a4816ee5",
          "name": "Size",
          "value": "Small",
          "variant": true
        },
        {
          "id": "5becb84fac207653a4816ee6",
          "name": "Color",
          "value": "Yellow",
          "variant": true
        }
      ],
      "discounts": [
        {
          "id": "coupon-0",
          "amount": 5
        }
      ],
      "discount_each": 2.5,
      "discount_total": 5,
      "taxes": [
        {
          "id": "sales-tax",
          "amount": 2
        }
      ],
      "tax_each": 1,
      "tax_total": 2
    }
  ],
  "notes": null,
  "number": 2039476,
  "order_id": "60f199509111e70000000011",
  "promotion_ids": null,
  "shipment_delivery": true,
  "shipment_discount": 0,
  "shipment_price": 5,
  "shipment_rating": {
    "fingerprint": "71e03117e684192f4f33569dab1c74ee",
    "services": [
      {
        "id": "standard",
        "name": "Standard Shipping",
        "price": 5
      },
      {
        "id": "express",
        "name": "Express Shipping",
        "price": 10
      },
      {
        "id": "next_day",
        "name": "Next Day Shipping",
        "price": 20
      }
    ],
    "errors": null
  },
  "shipment_tax": 0,
  "shipment_tax_included_total": 5,
  "shipment_total": 5,
  "shipping": {
    "name": "Uriel Septim VII",
    "first_name": "Uriel",
    "last_name": "Septim",
    "address1": "Imperial City Palace",
    "city": "Imperial City",
    "zip": 11201,
    "country": "US",
    "phone": "(555) 555-5555",
    "price": 5,
    "service": "standard",
    "service_name": "Standard",
    "account_address_id": "5c12c5fdfcd74b34e19cf659"
  },
  "status": "converted",
  "sub_total": 38.98,
  "tax_included_total": 2,
  "tax_total": 2,
  "taxes": [
    {
      "id": "sales-tax",
      "name": "Sales tax",
      "priority": 1,
      "rate": 0.1,
      "amount": 2
    }
  ],
  "webhook_attempts_failed": null,
  "webhook_response": null,
  "webhook_status": 200
}

Create a cart

Create a new cart. If you wish to generate your own unique ID for the record, it must use BSON ObjectID format for compatibility.

When adding shipping.services to a cart, you must first add the products to the cart.

Arguments

account_id

objectId

ID of the customer's account.

billing

object

The customer's billing details. Defaults to account.billing. Updating billing will also update the corresponding account billing object.

coupon_code

string

Coupon code applied to the cart. See coupons for details.

items

array of object

List of line items describing the products ordered.

shipping

object

The customer's shipping details. Defaults to account.shipping. Updating shipping will also update the corresponding account shipping object.

POST/carts
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.post('/carts', {
  items: [
    {
      product_id: '5cad15bc9b14d1990724663a',
      quantity: 2,
    }
  ],
  billing: {
    ...
  },
  shipping: {
    ...
  },
  coupon_code: 'FREESHIPPING',
});
Response
{
  "id": "5cad15bc9b14d1990724663a",
  "active": true,
  "billing": {...},
  "shipping": {...},
  "items": [
    {
      "id": "5a9ea7ba3f95740a914267f2",
      "product_id": "5cad15bc9b14d1990724663b",
      "quantity": 2,
      "price": 9.99,
      "price_total": 18.98,
      "shipment_weight": 1.5,
      ...
    }
  ],
  "coupon_code": "FREESHIPPING",
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "discount_total": 0,
  "grand_total": 18.98,
  "item_quantity": 2,
  "item_shipment_weight": 3.0,
  "item_tax": 0,
  "number": "100101",
  "shipment_price": 0,
  "shipment_total": 0,
  "status": "active",
  "sub_total": 0,
  "tax_total": 0,
  ...
}

Retrieve a cart

Retrieve an existing cart using the ID that was returned when created.

Arguments

id

objectIdrequired

The id of the cart to retrieve.

expand

string

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.

fields

string

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

string

Include one or more arbitrary queries in the response, possibly related to the main query.

See including for more details.

GET /carts/:id
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/carts/{id}', {
  id: '5cad15bc9b14d1990724663a',
});
Response
{
  "id": "5cad15bc9b14d1990724663a",
  "active": true,
  "billing": {...},
  "shipping": {...},
  "items": [
    {
      "id": "5a9ea7ba3f95740a914267f2",
      "product_id": "5cad15bc9b14d1990724663b",
      "quantity": 2,
      "price": 9.99,
      "price_total": 18.98,
      "shipment_weight": 1.5,
      ...
    }
  ],
  "coupon_code": "FREESHIPPING",
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "discount_total": 0,
  "grand_total": 18.98,
  "item_quantity": 2,
  "item_shipment_weight": 3.0,
  "item_tax": 0,
  "number": "100101",
  "shipment_price": 0,
  "shipment_total": 0,
  "status": "active",
  "sub_total": 0,
  "tax_total": 0,
  ...
}

Update a cart

Update an existing cart 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

id

objectIdrequired

Unique identifier for the cart.

account_id

objectId

ID of the customer's account.

billing

object

The customer's billing details. Defaults to account.billing. Updating billing will also update the corresponding account billing object.

coupon_code

string

Coupon code applied to the cart. See coupons for details.

items

array of object

List of line items describing the products ordered.

shipping

object

The customer's shipping details. Defaults to account.shipping. Updating shipping will also update the corresponding account shipping object.

PUT/carts/:id
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.put('/carts/{id}', {
  id: '5cad15bc9b14d1990724663a',
  shipping: {
    name: 'Jon Snow',
    address1: '1 Main Street',
    city: 'Brooklyn',
    state: 'NY',
    zip: '11201',
    country: 'US',
    phone: '(555) 555-5555',
  },
});
Response
{
  "id": "5cad15bc9b14d1990724663a",
  "active": true,
  "billing": {...},
  "shipping": {
    "name": "Jon Snow",
    "first_name": "Jon",
    "last_name": "Snow",
    "address1": "1 Main Street",
    "city": "Brooklyn",
    "state": "NY",
    "zip": "11201",
    "country": "US",
    "phone": "(555) 555-5555"
  },
  "items": [
    {
      "id": "5a9ea7ba3f95740a914267f2",
      "product_id": "5cad15bc9b14d1990724663b",
      "quantity": 2,
      "price": 9.99,
      "price_total": 18.98,
      "shipment_weight": 1.5,
      ...
    }
  ],
  "coupon_code": "FREESHIPPING",
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "date_updated": "2019-04-01T00:00:00.000Z",
  "discount_total": 0,
  "grand_total": 18.98,
  "item_quantity": 2,
  "item_shipment_weight": 3.0,
  "item_tax": 0,
  "number": "100101",
  "shipment_price": 0,
  "shipment_total": 0,
  "status": "active",
  "sub_total": 0,
  "tax_total": 0,
  ...
}

Convert carts to orders

Create a new order from an active cart. This call will map items and other properties from a cart while creating the order and mark the cart as converted. Returns an error if any of the required order properties are missing from the cart, or if product stock is unavailable.

Arguments

cart_id

objectId

ID of the cart to convert.

POST/orders
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.post('/orders', {
  cart_id: '5cad15bc9b14d1990724663a',
});
Response
{
  "id": "5cad15bc9b14d1990724663b",
  "account_id": "5a9ea7ba3f95740a914267f1",
  "billing": {...},
  "cart_id": "5cad15bc9b14d1990724663a",
  "shipping": {...},
  "items": [
    {
      "id": "5a9ea7ba3f95740a914267f2",
      "product_id": "5cad15bc9b14d1990724663b",
      "quantity": 2,
      "price": 9.99,
      "price_total": 18.98,
      "shipment_weight": 1.5,
      ...
    }
  ],
  "coupon_code": "FREESHIPPING",
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "delivered": false,
  "discount_total": 0,
  "grand_total": 18.98,
  "item_quantity": 2,
  "item_shipment_weight": 3.0,
  "item_tax": 0,
  "number": "100101",
  "paid": false,
  "payment_balance": -18.98,
  "payment_total": 0,
  "refund_total": 0,
  "refunded": false,
  "shipment_price": 0,
  "shipment_total": 0,
  "status": "payment_pending",
  "sub_total": 0,
  "tax_total": 0,
  ...
}

List all carts

Return a list of carts

Arguments

expand

string

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.

fields

string

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

object

Include one or more arbitrary queries in the response which are potentially related to the main query.

See including for more details.

limit

int

Limit the number of records returned, ranging between 1 and 1000. Defaults to 15.

page

int

The page number of results to return given the specified or default limit.

search

string

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.

sort

string

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.

where

object

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.

GET/carts
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/carts', {
  where: { active: true },
  limit: 25,
  page: 1,
});
Response
{
  "count": 51,
  "results": [
    {
      "id": "5cad15bc9b14d1990724663a",
      "active": true,
      "billing": {...},
      "shipping": {
        "name": "Jon Snow",
        "first_name": "Jon",
        "last_name": "Snow",
        "address1": "1 Main Street",
        "city": "Brooklyn",
        "state": "NY",
        "zip": "11201",
        "country": "US",
        "phone": "(555) 555-5555"
      },
      "items": [
        {
          "id": "5a9ea7ba3f95740a914267f2",
          "product_id": "5cad15bc9b14d1990724663b",
          "quantity": 2,
          "price": 9.99,
          "price_total": 18.98,
          "shipment_weight": 1.5,
          ...
        }
      ],
      "coupon_code": "FREESHIPPING",
      "currency": "USD",
      "date_created": "2019-04-01T00:00:00.000Z",
      "date_updated": "2019-04-01T00:00:00.000Z",
      "discount_total": 0,
      "grand_total": 18.98,
      "item_quantity": 2,
      "item_shipment_weight": 3.0,
      "item_tax": 0,
      "number": "100101",
      "shipment_price": 0,
      "shipment_total": 0,
      "status": "active",
      "sub_total": 0,
      "tax_total": 0,
      ...
    },
    {...},
    {...}
  ],
  "page": 1,
  "pages": {
    "1": {
      "start": 1,
      "end": 25
    },
    "2": {
      "start": 26,
      "end": 50
    },
    "2": {
      "start": 51,
      "end": 51
    }
  }
}

Delete a cart

Arguments

id

objectIdrequired

The id for the cart to delete.

const swell = require('swell-node').init('store-id', 'secret-key');

await swell.delete('/carts/{id}', {
  id: '5cad15bc9b14d1990724663a',
});
Response
{
  "id": "5cad15bc9b14d1990724663a",
  "active": true,
  "billing": {...},
  "shipping": {
    "name": "Jon Snow",
    "first_name": "Jon",
    "last_name": "Snow",
    "address1": "1 Main Street",
    "city": "Brooklyn",
    "state": "NY",
    "zip": "11201",
    "country": "US",
    "phone": "(555) 555-5555"
  },
  "items": [
    {
      "id": "5a9ea7ba3f95740a914267f2",
      "product_id": "5cad15bc9b14d1990724663b",
      "quantity": 2,
      "price": 9.99,
      "price_total": 18.98,
      "shipment_weight": 1.5,
      ...
    }
  ],
  "coupon_code": "FREESHIPPING",
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "date_updated": "2019-04-01T00:00:00.000Z",
  "discount_total": 0,
  "grand_total": 18.98,
  "item_quantity": 2,
  "item_shipment_weight": 3.0,
  "item_tax": 0,
  "number": "100101",
  "shipment_price": 0,
  "shipment_total": 0,
  "status": "active",
  "sub_total": 0,
  "tax_total": 0,
  ...
}
← Back: Purchase linksNext: Orders →
© 2024 Swell
Terms of servicePrivacy policy