Backend API
Create a new cart.
When adding shipping.services to a cart, you must first add the products to the cart.
Arguments
ID of the customer's account.
The customer's billing details. Defaults to account.billing. Updating billing will also update the corresponding account billing object.
ID of the customer's credit card on file, if applicable.
Expandable link to the customer's credit card on file, if applicable.
Billing address line 1: street address/PO box/company name.
Billing address line 2: apartment/suite/unit/building.
Amazon billing details used when billing.method=amazon.
Amazon access token provided when a customer authorizes payment in a storefront.
Amazon order reference ID created when a customer initiates payment in a storefront.
Credit card billing details used when `billing.method=card`.
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.
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.
Billing city/district/suburb/town/village.
Two-letter ISO country code.
Indicates billing details represent the customer's default payment method.
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 last words of the name.
Method of payment. Can becard, account, amazon, paypal, or any one of the manual methods defined in payment settings.
Billing full name. If `first_name` or `last_name` are updated, then `name` will be automatically updated as a combination of first/last.
PayPal billing details used when billing.method=paypal.
PayPal payer ID provided when a customer authorizes payment in a storefront.
PayPal payment ID created when a customer initiates payment in a storefront.
Billing phone number.
Billing state/county/province/region.
Billing zip/postal code.
Stores the necessary information about the payment. This is typically the payment ID returned by the gateway after payment is initialized.
Affirm billing details used when billing.method=affirm.
Token used to communicate payment information to the gateway.
Resolve billing details used when billing.method=resolve.
Charge ID returned by the payment gateway for the payment.
Klarna billing details used when billing.method=klarna.
Payment information returned by the gateway during payment initialization.
Ideal billing details used when billing.method=ideal.
Token used to communicate payment information to the gateway.
Bancontact billing details used when billing.method=bancontact.
Payment information returned by the gateway during payment initialization.
Google Pay billing details used when billing.method=google.
One-time use reference element used to communicate payment information to a payment gateway.
Gateway used to facilitate the transaction. For example, gateway=braintree.
Apple Pay billing details used when billing.method=apple.
One-time use reference element used to communicate payment information to a payment gateway.
Gateway used to facilitate the transaction. For example, gateway=braintree.
Coupon code applied to the cart. See coupons for details.
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.
Method of delivery taken automatically from product.delivery.
Possible enum values:
Options that allow for variations of the base product. 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 cart.
Unique identifier for the object.
Human-friendly name of the option.
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.
Additional price added onto the base price of the product.
Additional shipping weight added onto the base weight of the product.
Total quantity of the bundle item to be fulfilled, calculated as item.quantity * bundle_item.quantity.
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.
Unique identifier for the item.
Total discount amount divided by quantity.
Total discount applied to the item.
Displays the original item list price and does not reflect discounts or sale pricing.
Total price added to sub total by multiplying quantity and price.
ID of location fromĀ /settings/shipping/locations. If specified, shipping is calculated from this location. Otherwise, the store's default location will be used.
Refers to the subscription interval that applies when delivery=subscription.
Refers to the subscription interval count that applies when delivery=subscription.
Refers to the subscription trial period that applies when delivery=subscription.
Total tax amount divided by quantity.
Total tax applied to the item.
Total of all trial prices on the order.
Indicates the item has been fulfilled as a subscription and marked as paid by reference to this order.
This field is a copy of the item's product.name.
Possible enum values:
Possible enum values:
Possible enum values:
The customer's shipping details. Defaults to account.shipping. Updating shipping will also update the corresponding account shipping object.
ID of the customer's address on file.
Expandable link to the customer's address on file.
Shipping address line 1: (street address/PO box/company name).
Shipping address line 2: (apartment/suite/unit/building).
Shipping city/district/suburb/town/village.
Two-letter ISO country code.
Indicates shipping details represent the customer's default shipping address.
Shipping first name. If name is updated, then first_name will be automatically updated as the first word of the name.
Shipping last name. If name is updated, then last_name will be automatically updated as the last words of the name.
Shipping full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.
Shipping phone number.
Price of the shipping service. Defaults to `shipment_rating.services.price` chosen by setting `service`.
ID of a shipping service as configured in shipment settings. Normally, this would be applied after retrieving shipping rates by using one of the shipment_rating.services.id values.
Name of the shipping service. Defaults to shipment_rating.services.name chosen by setting service.
Shipping state/county/province/region.
Shipping zip/postal code.
Indicates if the shipping is local pick up
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.
Number of abandoned cart notifications sent to the customer.
Expandable link to the customer's account.
Amount of customer's account credit applied for initial payment, if applicable.
Indicates the customer's account credit is applied to the initial payment.
Set true when the customer has indicated they want to save shipping and billing information to their account for future use.
Indicates the customer was logged into their account when placing the order.
Indicates the cart has been updated by a customer within the last 3 hours.
Customer-facing unique identifier for the cart used in URLs and for abandoned cart recovery.
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.
Customer notes provided when placing the order, if any.
Expandable link to the coupon applied to the cart.
ID of the coupon applied to the cart.
Three-letter ISO currency code in uppercase. Defaults to the store's base currency.
Currency percentage used in calculating the fixed amount.
Date the cart was or will be marked as abandoned.
Next date the cart will be marked as abandoned when using a series of abandoned cart recovery notices (advanced cart recovery).
Date the order webhook first failed, if applicable. Value is unset after an order webhook is successfully returned for the record.
Date the order webhook last succeeded, if applicable. Value is unset after an order webhook fails to return for the record.
Total discount amount.
List of discounts applied to the cart.
Unique identifier for the object.
Fixed discount amount.
Object describing the discount rule details. Custom discounts don't require this value.
Type of discount. Can be coupon or promo-<id> referring to the source of the discount. Custom discounts don't require this value.
Three-letter ISO currency code representing the user's preferred display currency, if applicable.
Locale code representing the user's preferred display locale, if applicable.
Indicates cart is a draft subscription.
Indicates the order is intended as a gift for the recipient.
Optional message to include with the order when shipping to the recipient.
Indicates the cart has at least one line item with delivery=giftcard.
Total payment amount applied to the order from giftcards.
List of gift cards applied to the cart.
Amount of the gift card balance to spend on this order. Defaults to giftcard.balance.
Specify a gift card code to apply to the cart. If the code is not found or invalid, a validation error is returned. Case-insensitive.
Unique identifier for the object.
Fully formatted gift card code for display purposes.
Expandable link to the gift card record.
Last four digits of the gift card code.
Grand total including items, shipping, and taxes.
Indicates the customer was not logged in when placing the order.
Total discount applied to line items.
Total quantity of all line items.
Total shipping weight of all line items.
Total taxes applied to line items.
Indicates line item prices include taxes.
Arbitrary data, typically set in a checkout flow to store custom values. See Storefront API for more details.
Internal admin notes. These are not visible to the customer.
Unique incremental cart number, assigned automatically using a format configured in general settings.
Expandable link to the converted order, if applicable.
ID of the the converted order, if applicable.
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.
List of promotion IDs applied to the cart.
Expandable list of promotions applied to the cart.
Unique identifiers for the purchase links.
Expandable links to the purchase links added to the cart.
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.
Unique identifier for the purchase link errors.
A purchase link error object.
A distinct code indicating the cause of the purchase link error.
A human-readable description of the purchase link error.
An object describing the resource that blocked the creation of the cart.
Resource ID for the error.
Resource model. For example: products or promotions.
A human-readable resource name.
Expandable link to the purchase link.
Unique identifier for the purchase link to which the error relates.
Indicates the cart was recovered and converted to an order after being abandoned.
Schedule for a recurring order.
Interval of recurring orders. Can be weekly, daily, monthly, yearly.
Possible enum values:
Interval multiplier for scheduled orders. For example, an interval_count=2 paired with an interval=monthly would recur twice a month.
Indicates the cart has at least one line item with delivery=shipment.
Shipping discount applied by coupons, promotions, or custom logic.
Total shipping price before discounts.
Object describing the shipping services and rates available for the cart. Shipping country must be set before retrieving shipping rates.
Unique fingerprint identifying the parameters used to calculate shipping rates. Rates should always be the same given the same parameters and shipping settings.
List of shipping services and rates available.
Unique identifier for the object.
Name of the shipment service.
Name of the third party carrier offering the service, if applicable.
Price of given shipment service.
Indicated whether the shipment service is local pick-up.
Applicable tax code for shipment service.
List of errors generated while retrieving rates, if any. When using third-party shipping services, any system errors will be listed here.
Brief description of the error.
Unique error code for reference.
MD5 hash value for referencing the shipment rating.
Shipping tax amount, if applicable.
Indicates shipping total includes taxes, if applicable.
Total of taxes applied separately from line items.
Total shipping price after discounts.
Current status of the cart. Can be active, converted, abandoned, or recovered.
Possible enum values:
Sum of all line items before discounts, taxes and shipping.
Expandable link to the subscription that spawned the order, if applicable.
Indicates the cart has at least one line item with delivery=subscription.
ID of the subscription that spawned the order, if applicable.
Expands into the order that the cart was converted into.
When a cart is converted to an order, this field represents the corresponding order_id.
Total with shipping and item taxes included. Allows for an alternate display style, as normally sub_total and tax_total are shown separately.
Total tax amount applied to the cart including line items and shipping.
List of taxes applied to the cart.
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.
Indicates the tax applies to shipping.
Indicates the order is tax-exempt. Taxes will not be calculated or applied when true.
Number of failed order webhook attempts, if applicable. Value is unset after an order webhook is successfully returned for the record.
Text response of the last failed order webhook attempt, if applicable. Value is unset after an order webhook is successfully returned for the record.
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.
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');
await swell.post('/carts', {
items: [
{
product_id: '5cad15bc9b14d1990724663a',
quantity: 2,
options: [...]
}
],
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,
...
}