Backend API

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.

Fields

idobjectId

Unique identifier for the cart.

abandonedboolean

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_notificationsint

Number of abandoned cart notifications sent to the customer.

account_idobjectId

ID of the customer's account.

accountAccount

Expandable link to the customer's account.

account_credit_amountcurrency

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

account_info_savedboolean

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

account_logged_inboolean

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

activeboolean

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

billingobject

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

checkout_idstring

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

checkout_urlstring

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.

commentsstring

Customer notes provided when placing the order, if any.

coupon_codestring

Coupon code applied to the cart.

coupon_idobjectId

ID of the coupon applied to the cart.

couponCoupon

Expandable link to the coupon applied to the cart.

currencystring

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

currency_ratefloat

Currency percentage used in calculating the fixed amount.

date_abandoneddate

Date the cart was or will be marked as abandoned.

date_abandoned_nextdate

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

date_createddateauto

Date and time the cart was created.

date_updateddateauto

Date and time the cart was last updated.

date_webhook_first_faileddate

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

discount_totalcurrency

Total discount amount.

discountsarray of object

List of discounts applied to the cart.

display_currencystring

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

display_localestring

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

giftboolean

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

gift_messagestring

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

giftcardsarray of object

List of gift cards applied to the cart.

giftcard_deliveryboolean

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

giftcard_totalcurrencyauto

Total payment amount applied to the order from giftcards.

grand_totalcurrencyauto

Grand total including items, shipping, and taxes.

guestboolean

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

item_discountcurrency

Total discount applied to line items.

item_shipment_weightfloatauto

Total shipping weight of all line items.

item_tax_includedboolean

Indicates line item prices include taxes.

item_taxcurrencyauto

Total taxes applied to line items.

item_quantityintauto

Total quantity of all line items.

itemsarray of object

List of line items describing the products ordered.

metadataobject

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

notesstring

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

numberstringauto

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

order_idobjectId

ID of the the converted order, if applicable.

orderOrder

Expandable link to the converted order, if applicable.

orig_pricecurrency

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_idsarray of child_scalar

List of promotion IDs applied to the cart.

promotionsPromotion

Expandable list of promotions applied to the cart.

recoveredboolean

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

shipment_deliveryboolean

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

shipment_discountcurrency

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

shipment_pricecurrency

Total shipping price before discounts.

shipment_ratingobject

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

shipment_taxcurrency

Shipping tax amount, if applicable.

shipment_tax_includedboolean

Indicates shipping total includes taxes, if applicable.

shipment_tax_included_totalcurrency

Total of taxes applied separately from line items.

shipment_totalcurrency

Total shipping price after discounts.

shippingobject

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

statusenumauto

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

sub_totalcurrency

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

subscriptionSubscription

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

subscription_deliveryboolean

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

subscription_idobjectId

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

tax_included_totalcurrency

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

tax_totalcurrency

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

taxesarray of object

List of taxes applied to the cart.

webhook_attempts_failedint

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

webhook_responsestring

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_statusint

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.

target_order_idobjectId

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

target_orderOrder

Expands into the order that the cart was converted into.

taxes_fixedboolean

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

account_credit_appliedboolean

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

date_webhook_last_succeededdate

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

purchase_linksPurchase link

Expandable links to the purchase links added to the cart.

purchase_link_idsarray of string

Unique identifiers for the purchase links.

purchase_links_errorsarray 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.

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 new cart.

Arguments

account_idobjectId

ID of the customer's account.

billingobject

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

coupon_codestring

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

itemsarray of object

List of line items describing the products ordered.

shippingobject

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 an existing cart using the ID that was returned when created.

Arguments

idobjectIdrequired

The id of the cart to retrieve.

expandstring

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.

fieldsstring

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.

includestring

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 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

idobjectIdrequired

Unique identifier for the cart.

account_idobjectId

ID of the customer's account.

billingobject

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

coupon_codestring

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

itemsarray of object

List of line items describing the products ordered.

shippingobject

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,
  ...
}

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_idobjectId

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,
  ...
}

Return a list of carts

Arguments

expandstring

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.

fieldsstring

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.
includeobject

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

See including for more details.

limitint

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

pageint

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

searchstring

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.

sortstring

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.

whereobject

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
    }
  }
}

Arguments

idobjectIdrequired

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,
  ...
}