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.
When managing items within a cart, utilize the items.id rather than the product.id
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
}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,
...
}Retrieve an existing cart using the ID that was returned when created.
Arguments
The id of the cart to retrieve.
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.
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 one or more arbitrary queries in the response, possibly related to the main query.
See including for more details.
const { swell } = require('swell-node');
swell.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
Unique identifier for the cart.
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.
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.
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
Amount of customer's account credit applied for initial payment, if applicable.
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.
Expandable link to the customer's account.
Customer notes provided when placing the order, if any.
ID of the coupon applied to the cart.
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).
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.
Optional message to include with the order when shipping to the recipient.
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.
Indicates the order is intended as a gift for the recipient.
Indicates the customer was not logged in when placing the order.
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.
List of promotion IDs applied to the cart.
Indicates the cart was recovered and converted to an order after being abandoned.
Shipping discount applied by coupons, promotions, or custom logic.
Shipping tax amount, if applicable.
Indicates shipping total includes taxes, if applicable.
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 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.
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.
Expandable link to 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 order webhook first failed, if applicable. Value is unset after an order webhook is successfully returned for the record.
Total discount amount.
Indicates the cart has at least one line item with delivery=giftcard.
Total payment amount applied to the order from giftcards.
Grand total including items, shipping, and taxes.
Total discount applied to line items.
Total shipping weight of all line items.
Total taxes applied to line items.
Total quantity of all line items.
Unique incremental cart number, assigned automatically using a format configured in general settings.
ID of the the converted order, if applicable.
Expandable link to the converted order, if applicable.
Expandable list of promotions applied to the cart.
Indicates the cart has at least one line item with delivery=shipment.
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.
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.
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.
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.
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.
When a cart is converted to an order, this field represents the corresponding order_id.
Expands into the order that the cart was converted into.
Indicates the order is tax-exempt. Taxes will not be calculated or applied when true.
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 customer's account credit is applied to the initial payment.
Date the order webhook last succeeded, if applicable. Value is unset after an order webhook fails to return for the record.
Expandable links to the purchase links added to the cart.
Unique identifiers for the purchase links.
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.
const { swell } = require('swell-node');
swell.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
ID of the cart to convert.
const { swell } = require('swell-node');
swell.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
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('/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
The id for the cart to delete.
const { swell } = require('swell-node');
swell.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,
...
}