Backend API
Fields
Unique identifier for the cart.
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.
ID of the customer's account.
Indicates the customer chose to save shipping and billing information to their account when submitting the order.
Indicates the customer was logged into their account when placing the order.
Date the cart was last accessed by the customer.
Indicates the cart has been updated by a customer within the last 3 hours.
The customer's billing details. Defaults to account.billing. Updating billing will also update the corresponding account billing object.
Billing full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.
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.
Billing address line 1: (street address/PO box/company name).
Billing address line 2: (apartment/suite/unit/building).
Billing city/district/suburb/town/village.
Billing state/county/province/region.
Billing zip/postal code.
Two-letter ISO country code.
Billing phone number.
Method of payment. Can be card, account, amazon, paypal, or any one of the manual methods defined in payment settings.
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.
Indicates billing details represent the customer's default payment method.
ID of the customer's credit card on file, if applicable.
Expandable link to the customer's credit card on file, if applicable.
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.
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.
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.
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.
The ID of an authorized payment.
Expandable link to an authorized payment.
Coupon code 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.
Location to purchase products from, when using multi-location inventory.
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).
Indicates an item was added to the cart, used for conversion tracking.
Indicates the cart reached checkout, used for conversion tracking.
Date and time the cart was created.
Date and time the cart was last updated.
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 the cart is a draft. The Swell dashboard uses draft carts to designate entries in the Draft orders section of the dashboard.
Indicates the cart is a draft used to create a 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.
Unique identifier for the object.
Amount of the gift card balance to spend for initial payment. If not specified, each gift cards will be spent in order until payment is completed.
Gift card code to apply. A validation error will be returned if the code is not valid.
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.
Grand total of items with a trial period, charged when their trials end.
Total amount that may be authorized for items with a trial period.
Total amount to be authorized on the payment method, rather than captured immediately.
Total amount to be captured on the payment method.
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.
Total discount applied to items with a trial period.
Total tax applied to items with a trial period.
Indicates line item prices include taxes.
List of line items describing the products ordered.
When adding an item to the cart, only product_id is required. All other properties such as variant_id, quantity and options may be specified if relevant to the product.
If applicable, variant_id is automatically resolved from options, however you may pass variant_id if the value is known by the application.
Gift card items support special option values to indicate that the gift card fulfillment email should be sent to a different recipient containing the newly generated gift card code.
Gift card options:
- id=send_email: Specify a different email to receive the gift card.
- id=send_note: Specify an optional note added to the gift card fulfillment email.
Example:
"options": [{ "id": "send_email", "value": "recipient@example.com" }]
Unique identifier for the item.
List of items offered as a bundle. Defaults to product.bundle_items.
Unique identifier for the object.
ID of the item product.
Expandable link to the bundle item product.
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.
Shipping weight taken automatically from product.shipment_weight, if applicable.
Quantity of the bundle item being ordered. Defaults to 1.
Total quantity of the bundle item to be fulfilled, calculated as item.quantity * bundle_item.quantity.
ID of the bundle item variant.
Expandable link to the bundle item variant.
Method of fulfillment automatically assigned based on type such as shipment, subscription, giftcard, and null. Each product in the bundle must have its own fulfillment method.
Possible enum values:
A long-form description of the product. Can contain HTML or other markup languages.
Total discount amount divided by quantity.
Total discount applied to the item.
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.
Arbitrary item data, typically set in a checkout flow to store custom values. See Storefront API for details.
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.
When adding an item to a cart, only the name and value must be specified in the request, while id, price, shipment_weight and variant are populated automatically.
Unique identifier for the option object. Generated automatically.
Human-friendly name of the option.
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.
Displays the original item list price and does not reflect discounts or sale pricing.
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.
ID of the bundle item product.
This field is a copy of the item's product.name.
Expandable link to the bundle item product.
Quantity of the bundle item being ordered. Defaults to 1.
ID of location fromĀ /settings/shipping/locations. If specified, shipping is calculated from this location. Otherwise, the store's default location will be used.
Shipping weight taken automatically from product.shipment_weight, if applicable.
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.
Indicates the item has been fulfilled as a subscription and marked as paid by reference to this order.
Total tax amount divided by quantity.
Total tax applied to the item.
List of tax rules applied to the item based on tax settings or custom logic.
Unique identifier for the object. Refers to one of the IDs in the cart taxes object.
Fixed tax amount.
Total of all trial prices on the order.
ID of the bundle item variant.
Expandable link to the bundle item variant.
Arbitrary data, typically set in a checkout flow to store custom values. See Frontend 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.
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.
Indicates the cart contains at least one item with a trial period.
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.
Date and time the object was created.
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 shipping price after discounts.
The customer's shipping details. Defaults to account.shipping. Updating shipping will also update the corresponding account shipping object.
Shipping full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.
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 address line 1: (street address/PO box/company name).
Shipping address line 2: (apartment/suite/unit/building).
Shipping city/district/suburb/town/village.
Shipping state/county/province/region.
Shipping zip/postal code.
Two-letter ISO country code.
Shipping phone number.
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.
Price of the shipping service. Defaults to shipment_rating.services.price chosen by setting service.
Indicates shipping details represent the customer's default shipping address.
ID of the customer's address on file.
Expandable link to the customer's address on file.
Indicates whether shipping for local pick-up.
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.
Subtotal of items with a trial period, charged when their trials end.
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 of items with a trial period including taxes, if applicable.
Total tax amount applied to the cart including line items and shipping.
List of taxes applied to the cart.
Unique identifier for the object.
Name of the tax rule. For example, "NY Sales Tax".
Fixed tax amount.
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.
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
}