# Carts Source: https://developers.swell.is/backend-api/carts A cart is a *pending* request to purchase products from your store. Carts contain all the information needed to fulfill a purchase. Once the customer is ready to complete their purchase, a simple API call is made to convert a cart to an [order](https://developers.swell.is/backend-api/orders/the-order-model). > **Tip:** When managing items within a cart, utilize the `items.id` rather than the `product.id` ## The cart model ### Fields - `id` (objectId): Unique identifier for the cart. - `abandoned` (boolean): Indicates the cart was abandoned after 3 hours of inactivity. After being marked as abandoned, this field is automatically set back to `false` after an update to items, billing, or shipping info. - `abandoned_notifications` (int): Number of abandoned cart notifications sent to the customer. - `account` (Account): Expandable link to the customer's account. - `account_credit_amount` (currency): Amount of customer's account credit applied for initial payment, if applicable. - `account_credit_applied` (boolean): Indicates the customer's account credit is applied to the initial payment. - `account_id` (objectId): ID of the customer's account. - `account_info_saved` (boolean): Indicates the customer chose to save shipping and billing information to their account when submitting the order. - `account_logged_in` (boolean): Indicates the customer was logged into their account when placing the order. - `date_last_accessed` (date): Date the cart was last accessed by the customer. - `active` (boolean): Indicates the cart has been updated by a customer within the last 3 hours. Default: `true`. - `billing` (object): The customer's billing details. Defaults to `account.billing`. Updating billing will also update the corresponding account billing object. - `name` (string, required): Billing full name. If `first_name` or `last_name` are updated, then `name` will be automatically updated as a combination of first/last. - `first_name` (string): Billing first name. If `name` is updated, then `first_name` will be automatically updated as the first word of the name. - `last_name` (string): Billing last name. If `name` is updated, then `last_name` will be automatically updated as the last words of the name. - `address1` (string): Billing address line 1: (street address/PO box/company name). - `address2` (string): Billing address line 2: (apartment/suite/unit/building). - `city` (string, required): Billing city/district/suburb/town/village. - `state` (string): Billing state/county/province/region. - `zip` (string): Billing zip/postal code. - `country` (string): Two-letter ISO country code. - `phone` (string): Billing phone number. - `method` (string): Method of payment. Can be `card`, `account`, `amazon`, `paypal`, or any one of the manual methods defined in payment settings. - `card` (object): Credit card billing details used when `billing.method=card`. - `token` (string, required): Token generated by Swell Checkout or Stripe.js. - `exp_month` (int): Two-digit number representing the credit card expiration month. - `exp_year` (int): Four-digit number representing the credit card expiration year. - `brand` (string): Credit card brand. Can be `American Express`, `Diners Club`, `Discover`, `JCB`, `MasterCard`, `UnionPay`, `Visa`, or `Unknown`. - `last4` (string): Last four digits of the card number. - `gateway` (string): ID of the payment gateway that should be used to process payments. - `test` (boolean): Indicates this is a test card. - `address_check` (string): When used with a payment gateway that performs address checks and `address1` was provided, can be `pass`, `fail`, `unavailable`, or `unchecked`. - `zip_check` (string, required): When used with a payment gateway that performs address checks and `zip` was provided, can be `pass`, `fail`, `unavailable`, or `unchecked`. - `cvc_check` (string): When used with a payment gateway that performs CVC code checks and `cvc` was provided, can be `pass`, `fail`, `unavailable`, or `unchecked`. - `default` (boolean): Indicates billing details represent the customer's default payment method. - `account_card_id` (objectId): ID of the customer's credit card on file, if applicable. - `account_card` (account_card): Expandable link to the customer's credit card on file, if applicable. - `amazon` (object): Amazon billing details used when `billing.method=amazon`. - `access_token` (string, required): Amazon access token provided when a customer authorizes payment in a storefront. - `order_reference_id` (string, required): Amazon order reference ID created when a customer initiates payment in a storefront. - `paypal` (object): PayPal billing details used when `billing.method=paypal`. - `payer_id` (string): PayPal payer ID provided when a customer authorizes payment in a storefront. - `payment_id` (string): PayPal payment ID created when a customer initiates payment in a storefront. - `intent` (object): Stores the necessary information about the payment. This is typically the payment ID returned by the gateway after payment is initialized. - `affirm` (object): Affirm billing details used when `billing.method=affirm`. - `checkout_token` (string): Token used to communicate payment information to the gateway. - `resolve` (object): Resolve billing details used when `billing.method=resolve`. - `charge_id` (string): Charge ID returned by the payment gateway for the payment. - `klarna` (object): Klarna billing details used when `billing.method=klarna`. - `source` (string): Payment information returned by the gateway during payment initialization. - `ideal` (object): Ideal billing details used when `billing.method=ideal`. - `token` (string): Token used to communicate payment information to the gateway. - `bancontact` (object): Bancontact billing details used when `billing.method=bancontact`. - `source` (string): Payment information returned by the gateway during payment initialization. - `google` (object): Google Pay billing details used when `billing.method=google`. - `nonce` (string): One-time use reference element used to communicate payment information to a payment gateway. - `gateway` (string): Gateway used to facilitate the transaction. For example, `gateway=braintree`. - `apple` (object): Apple Pay billing details used when `billing.method=apple`. - `nonce` (string): One-time use reference element used to communicate payment information to a payment gateway. - `gateway` (string): Gateway used to facilitate the transaction. For example, `gateway=braintree`. - `checkout_id` (string): Customer-facing unique identifier for the cart used in URLs and for abandoned cart recovery. Default: `{"$formula":"md5(alphanum(128))"}`. - `checkout_url` (string): URL to checkout for the cart, set automatically when the cart has at least `items`, `shipping`, or `billing` details set. Can also be set explicitly when creating or updating the cart for custom checkouts. - `comments` (string): Customer notes provided when placing the order, if any. - `coupon` (Coupon): Expandable link to the coupon applied to the cart. - `authorized_payment_id` (string): The ID of an authorized payment. - `authorized_payment` (Payment): Expandable link to an authorized payment. - `coupon_code` (string): [Coupon](https://developers.swell.is/backend-api/coupons/the-coupon-model) code applied to the cart. - `coupon_id` (objectId): ID of the coupon applied to the cart. - `currency` (string): Three-letter ISO currency code in uppercase. Defaults to the store's base currency. - `currency_rate` (float): Currency percentage used in calculating the fixed amount. - `location` (string): Location to purchase products from, when using multi-location inventory. - `date_abandoned` (date): Date the cart was or will be marked as abandoned. - `date_abandoned_next` (date): Next date the cart will be marked as abandoned when using a series of abandoned cart recovery notices (advanced cart recovery). - `conversion_add` (boolean): Indicates an item was added to the cart, used for conversion tracking. - `conversion_checkout` (boolean): Indicates the cart reached checkout, used for conversion tracking. - `date_created` (date, auto): Date and time the cart was created. - `date_updated` (date, auto): Date and time the cart was last updated. - `date_webhook_first_failed` (date): Date the order webhook first failed, if applicable. Value is unset after an order webhook is successfully returned for the record. - `date_webhook_last_succeeded` (date): Date the order webhook last succeeded, if applicable. Value is unset after an order webhook fails to return for the record. - `discount_total` (currency): Total discount amount. - `discounts` (array of object): List of discounts applied to the cart. - `id` (string): Unique identifier for the object. - `amount` (currency): Fixed discount amount. - `rule` (object): Object describing the discount rule details. Custom discounts don't require this value. - `type` (string): Type of discount. Can be `coupon` or `promo-` referring to the source of the discount. Custom discounts don't require this value. - `display_currency` (string): Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) representing the user's preferred display currency, if applicable. - `display_locale` (string): Locale code representing the user's preferred display locale, if applicable. - `draft` (boolean): Indicates the cart is a draft. The Swell dashboard uses draft carts to designate entries in the **Draft orders** section of the dashboard. - `draft_subscription` (boolean): Indicates the cart is a draft used to create a subscription. - `gift` (boolean): Indicates the order is intended as a gift for the recipient. - `gift_message` (string): Optional message to include with the order when shipping to the recipient. - `giftcard_delivery` (boolean): Indicates the cart has at least one line item with `delivery=giftcard`. - `giftcard_total` (currency, auto): Total payment amount applied to the order from `giftcards`. - `giftcards` (array of object): List of gift cards applied to the cart. - `id` (objectId): Unique identifier for the object. - `amount` (currency): 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. - `code` (string): Gift card code to apply. A validation error will be returned if the code is not valid. - `code_formatted` (string): Fully formatted gift card code for display purposes. - `giftcard` (giftcard): Expandable link to the gift card record. - `last4` (string): Last four digits of the gift card code. - `grand_total` (currency, auto): Grand total including items, shipping, and taxes. - `trial_grand_total` (currency): Grand total of items with a trial period, charged when their trials end. - `trial_auth_total` (currency): Total amount that may be authorized for items with a trial period. - `auth_total` (currency): Total amount to be authorized on the payment method, rather than captured immediately. - `capture_total` (currency): Total amount to be captured on the payment method. - `guest` (boolean): Indicates the customer was not logged in when placing the order. Default: `(formula)`. - `item_discount` (currency): Total discount applied to line items. - `item_quantity` (int, auto): Total quantity of all line items. - `item_shipment_weight` (float, auto): Total shipping weight of all line items. - `item_tax` (currency, auto): Total taxes applied to line items. - `trial_item_discount` (currency): Total discount applied to items with a trial period. - `trial_item_tax` (currency): Total tax applied to items with a trial period. - `item_tax_included` (boolean): Indicates line item prices include taxes. - `items` (array of object): 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. #### Adding gift card items to the cart 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" }]` - `id` (objectId, auto): Unique identifier for the item. - `bundle_items` (array of object): List of items offered as a bundle. Defaults to `product.bundle_items`. - `id` (objectId): Unique identifier for the object. - `product_id` (objectId, required): ID of the item product. - `product` (product): Expandable link to the bundle item product. - `delivery` (enum): Method of delivery taken automatically from `product.delivery`. Possible values: `shipment`, `giftcard`, `subscription`. Default: `{"$formula":"if(product_id, product.delivery)"}`. - `options` (array of object): 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. - `id` (string): Unique identifier for the object. - `name` (string): Human-friendly name of the option. - `value` (string): 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. - `variant` (boolean): Indicates the option refers to a variant aspect. - `price` (currency): Additional price added onto the base price of the product. - `shipment_weight` (float): Additional shipping weight added onto the base weight of the product. - `shipment_weight` (float, auto): Shipping weight taken automatically from `product.shipment_weight`, if applicable. - `quantity` (int): Quantity of the bundle item being ordered. Defaults to 1. Default: `1`. - `quantity_total` (int): Total quantity of the bundle item to be fulfilled, calculated as `item.quantity * bundle_item.quantity`. - `variant_id` (objectId): ID of the bundle item variant. - `variant` (variant): Expandable link to the bundle item variant. - `delivery` (enum): 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 values: `shipment`, `giftcard`, `subscription`. Default: `{"$formula":"if(product_id, product.delivery)"}`. - `description` (string): A long-form description of the product. Can contain HTML or other markup languages. - `discount_each` (currency): Total discount amount divided by quantity. - `discount_total` (currency): Total discount applied to the item. - `metadata` (object): Arbitrary item data, typically set in a checkout flow to store custom values. See [Storefront API](https://developers.swell.is/frontend-api/introduction) for details. - `orig_price` (currency): Displays the original item list price and does not reflect discounts or sale pricing. - `product_id` (objectId): ID of the bundle item product. - `product_name` (string): This field is a copy of the item's `product.name`. Default: `{"$formula": "if(product_id, product.name, null)"}`. - `product` (product): Expandable link to the bundle item product. - `quantity` (int): Quantity of the bundle item being ordered. Defaults to 1. Default: `1`. - `shipment_location` (string): ID of location from `/settings/shipping/locations`. If specified, shipping is calculated from this location. Otherwise, the store's default location will be used. - `shipment_weight` (float, auto): Shipping weight taken automatically from `product.shipment_weight`, if applicable. - `tax_each` (currency): Total tax amount divided by quantity. - `tax_total` (currency): Total tax applied to the item. - `taxes` (array of object): List of tax rules applied to the item based on tax settings or custom logic. - `id` (string): Unique identifier for the object. Refers to one of the IDs in the cart `taxes` object. - `amount` (currency): Fixed tax amount. - `trial_price_total` (currency): Total of all trial prices on the order. - `variant_id` (objectId): ID of the bundle item variant. - `variant` (variant): Expandable link to the bundle item variant. - `metadata` (object): Arbitrary data, typically set in a checkout flow to store custom values. See [Frontend API](https://developers.swell.is/frontend-api/introduction) for more details. - `notes` (string): Internal admin notes. These are not visible to the customer. - `number` (string, auto): Unique incremental cart number, assigned automatically using a format configured in general settings. - `order` (Order): Expandable link to the converted order, if applicable. - `order_id` (objectId): ID of the the converted order, if applicable. - `promotion_ids` (array of child_scalar): List of promotion IDs applied to the cart. - `promotions` (Promotion): Expandable list of promotions applied to the cart. - `purchase_link_ids` (array of string): Unique identifiers for the purchase links. - `purchase_links` (Purchase Link): Expandable links to the purchase links added to the cart. - `purchase_links_errors` (array of object): List of purchase link errors applied to the cart. Added when clicking on the purchase link, if any resources are blocking the creation of the cart. - `id` (objectId): Unique identifier for the purchase link errors. - `error` (object, required): A purchase link error object. - `code` (string, required): A distinct code indicating the cause of the purchase link error. - `message` (string, required): A human-readable description of the purchase link error. - `resource` (object, required): An object describing the resource that blocked the creation of the cart. - `id` (objectId): Resource ID for the error. - `model` (string): Resource model. For example: `products` or `promotions`. - `name` (string): A human-readable resource name. - `purchase_link` (purchase_link): Expandable link to the purchase link. - `purchase_link_id` (string, required): Unique identifier for the purchase link to which the error relates. - `recovered` (boolean): Indicates the cart was recovered and converted to an order after being abandoned. - `trial` (boolean): Indicates the cart contains at least one item with a trial period. - `schedule` (object): Schedule for a recurring order. - `interval` (enum): Interval of recurring orders. Can be `weekly`, `daily`, `monthly`, `yearly`. Possible values: `monthly`, `daily`, `weekly`, `yearly`. - `interval_count` (int): Interval multiplier for scheduled orders. For example, an `interval_count=2` paired with an `interval=monthly` would recur twice a month. - `shipment_delivery` (boolean): Indicates the cart has at least one line item with `delivery=shipment`. - `shipment_discount` (currency): Shipping discount applied by [coupons](https://developers.swell.is/backend-api/coupons), [promotions,](https://developers.swell.is/backend-api/promotions) or custom logic. - `shipment_price` (currency): Total shipping price before discounts. - `shipment_rating` (object): Object describing the shipping services and rates available for the cart. Shipping `country` must be set before retrieving shipping rates. - `date_created` (date, auto): Date and time the object was created. - `services` (array of object): List of shipping services and rates available. - `id` (string): Unique identifier for the object. - `name` (string): Name of the shipment service. - `carrier` (string): Name of the third party carrier offering the service, if applicable. - `price` (currency): Price of given shipment service. - `pickup` (boolean): Indicated whether the shipment service is local pick-up. - `tax_code` (string): Applicable tax code for shipment service. - `errors` (array of object): List of errors generated while retrieving rates, if any. When using third-party shipping services, any system errors will be listed here. - `message` (string): Brief description of the error. - `code` (string): Unique error code for reference. - `shipment_tax` (currency): Shipping tax amount, if applicable. - `shipment_tax_included` (boolean): Indicates shipping total includes taxes, if applicable. - `shipment_total` (currency): Total shipping price after discounts. - `shipping` (object): The customer's shipping details. Defaults to `account.shipping`. Updating shipping will also update the corresponding account shipping object. - `name` (string): Shipping full name. If `first_name` or `last_name` are updated, then `name` will be automatically updated as a combination of first/last. - `first_name` (string): Shipping first name. If `name` is updated, then `first_name` will be automatically updated as the first word of the name. - `last_name` (string, required): Shipping last name. If `name` is updated, then `last_name` will be automatically updated as the last words of the name. - `address1` (string): Shipping address line 1: (street address/PO box/company name). - `address2` (string): Shipping address line 2: (apartment/suite/unit/building). - `city` (string): Shipping city/district/suburb/town/village. - `state` (string): Shipping state/county/province/region. - `zip` (string): Shipping zip/postal code. - `country` (string): Two-letter ISO country code. - `phone` (string): Shipping phone number. - `service` (string): ID of a shipping service as configured in shipment settings. Normally, this would be applied after [retrieving shipping rates](https://developers.swell.is/backend-api/shipments/retrieve-a-shipment) by using one of the `shipment_rating.services.id` values. - `service_name` (string, required): Name of the shipping service. Defaults to `shipment_rating.services.name` chosen by setting `service`. - `price` (currency, required): Price of the shipping service. Defaults to `shipment_rating.services.price` chosen by setting `service`. - `default` (boolean, required): Indicates shipping details represent the customer's default shipping address. - `account_address_id` (objectId, required): ID of the customer's address on file. - `account_address` (account_address): Expandable link to the customer's address on file. - `pickup` (boolean): Indicates whether shipping for local pick-up. - `status` (enum, auto): Current status of the cart. Can be `active`, `converted`, `abandoned`, or `recovered`. Possible values: `converted`, `recovered`, `abandoned`, `active`. Default: `"active"`. - `sub_total` (currency): Sum of all line items before discounts, taxes and shipping. - `trial_sub_total` (currency): Subtotal of items with a trial period, charged when their trials end. - `subscription` (Subscription): Expandable link to the subscription that spawned the order, if applicable. - `subscription_delivery` (boolean): Indicates the cart has at least one line item with `delivery=subscription`. - `subscription_id` (objectId): ID of the subscription that spawned the order, if applicable. - `target_order` (Order): Expands into the order that the cart was converted into. - `target_order_id` (objectId): When a cart is converted to an order, this field represents the corresponding `order_id`. - `tax_included_total` (currency): Total with shipping and item taxes included. Allows for an alternate display style, as normally `sub_total` and `tax_total` are shown separately. - `trial_tax_included_total` (currency): Total of items with a trial period including taxes, if applicable. - `tax_total` (currency): Total tax amount applied to the cart including line items and shipping. - `taxes` (array of object): List of taxes applied to the cart. - `id` (string): Unique identifier for the object. - `name` (string): Name of the tax rule. For example, "NY Sales Tax". - `amount` (currency): Fixed tax amount. - `priority` (int): 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. - `rate` (float): Tax percentage used in calculating the fixed amount. - `shipping` (boolean): Indicates the tax applies to shipping. - `taxes_fixed` (boolean): Indicates the order is tax-exempt. Taxes will not be calculated or applied when true. - `webhook_attempts_failed` (int): Number of failed order webhook attempts, if applicable. Value is unset after an order webhook is successfully returned for the record. - `webhook_response` (string): Text response of the last failed order webhook attempt, if applicable. Value is unset after an order webhook is successfully returned for the record. - `webhook_status` (int): HTTP response status of the last failed order webhook attempt, if applicable. Value is unset after an order webhook is successfully returned for the record. ### Example response ```json { "id": "60f199509111e7000000000e", "abandoned": false, "account_id": "60f199509111e7000000000f", "account_info_saved": true, "account_logged_in": true, "billing": { "name": "Uriel Septim VII", "first_name": "Uriel", "last_name": "Septim", "address1": "Imperial City Palace", "city": "Imperial City", "state": "NY", "zip": 11201, "country": "US", "phone": "(555) 555-5555", "method": "card", "card": { "token": "card_1Ds1K7E30PFlZWil6Q7bJ1PD", "test": true, "last4": "4242", "brand": "Visa", "address_check": "unchecked", "zip_check": "unchecked", "cvc_check": "unchecked", "exp_month": 1, "exp_year": 2029, "fingerprints": "3e63991847bbdaafdbc5c8f110ad803f" }, "account_card_id": "5c3ac9870b3b171a7dfaf089" }, "checkout_id": "e785b5ac4355ceef41ae2fd1c47df4bc", "checkout_url": "https://example.swell.store/checkout/e785b5ac4355ceef41ae2fd1c47df4bc", "comments": null, "coupon_code": "DREAMS", "coupon_id": "60f199509111e70000000010", "currency": "USD", "date_created": "2021-07-16T14:36:00.057Z", "date_updated": "2021-07-16T14:36:00.057Z", "date_webhook_first_failed": null, "discount_total": 5, "discounts": [ { "id": "coupon-0", "type": "coupon", "amount": 5, "rule": { "type": "product", "value_type": "fixed", "value_amount": 2.5, "product_id": "5c524166f4e8f3446a10331b" } } ], "gift_message": null, "giftcards": [ { "id": "5841c5691c64c63e75d29e43", "amount": 25, "code": "B6UQY3DHRCM4BQYU", "code_formatted": "B6UQ Y3DH RCM4 BQYU", "last4": "BQYU" } ], "gift": true, "giftcard_total": 25, "grand_total": 41.98, "guest": false, "item_discount": 5, "item_quantity": 2, "item_shipment_weight": 2, "item_tax": 2, "items": [ { "id": "5ca537326a0ec32a521139dd", "product_id": "5c524166f4e8f3446a10331b", "variant_id": "5c524166f4e8f3446a10331f", "quantity": 2, "price": 19.99, "price_total": 38.98, "orig_price": 19.99, "delivery": "shipment", "shipment_weight": 1, "options": [ { "id": "5becb84fac207653a4816ee5", "name": "Size", "value": "Small", "variant": true }, { "id": "5becb84fac207653a4816ee6", "name": "Color", "value": "Yellow", "variant": true } ], "discounts": [ { "id": "coupon-0", "amount": 5 } ], "discount_each": 2.5, "discount_total": 5, "taxes": [ { "id": "sales-tax", "amount": 2 } ], "tax_each": 1, "tax_total": 2 } ], "notes": null, "number": 2039476, "order_id": "60f199509111e70000000011", "promotion_ids": null, "shipment_delivery": true, "shipment_discount": 0, "shipment_price": 5, "shipment_rating": { "fingerprint": "71e03117e684192f4f33569dab1c74ee", "services": [ { "id": "standard", "name": "Standard Shipping", "price": 5 }, { "id": "express", "name": "Express Shipping", "price": 10 }, { "id": "next_day", "name": "Next Day Shipping", "price": 20 } ], "errors": null }, "shipment_tax": 0, "shipment_tax_included_total": 5, "shipment_total": 5, "shipping": { "name": "Uriel Septim VII", "first_name": "Uriel", "last_name": "Septim", "address1": "Imperial City Palace", "city": "Imperial City", "zip": 11201, "country": "US", "phone": "(555) 555-5555", "price": 5, "service": "standard", "service_name": "Standard", "account_address_id": "5c12c5fdfcd74b34e19cf659" }, "status": "converted", "sub_total": 38.98, "tax_included_total": 2, "tax_total": 2, "taxes": [ { "id": "sales-tax", "name": "Sales tax", "priority": 1, "rate": 0.1, "amount": 2 } ], "webhook_attempts_failed": null, "webhook_response": null, "webhook_status": 200 } ``` ## Create a cart Create a new cart. > **Tip:** When adding `shipping.services` to a cart, you must first add the products to the cart. ### Arguments - `account_id` (objectId): ID of the customer's account. - `billing` (object): The customer's billing details. Defaults to `account.billing`. Updating billing will also update the corresponding account billing object. - `account_card_id` (objectId): ID of the customer's credit card on file, if applicable. - `account_card` (account_card): Expandable link to the customer's credit card on file, if applicable. - `address1` (string): Billing address line 1: street address/PO box/company name. - `address2` (string): Billing address line 2: apartment/suite/unit/building. - `amazon` (object): Amazon billing details used when `billing.method=amazon`. - `access_token` (string): Amazon access token provided when a customer authorizes payment in a storefront. - `order_reference_id` (string): Amazon order reference ID created when a customer initiates payment in a storefront. - `checkout_session_id` (string) - `card` (object): Credit card billing details used when `billing.method=card`. - `token` (string): Token generated by Swell Checkout or Stripe.js. - `exp_month` (int): Two-digit number representing the credit card expiration month. - `exp_year` (int): Four-digit number representing the credit card expiration year. - `brand` (string): Credit card brand. Can be `American Express`, `Diners Club`, `Discover`, `JCB`, `MasterCard`, `UnionPay`, `Visa`, or `Unknown`. - `last4` (string): Last four digits of the card number. - `gateway` (string): ID of the payment gateway that should be used to process payments. - `test` (boolean): Indicates this is a test card. - `address_check` (string): When used with a payment gateway that performs address checks and `address1` was provided, can be `pass`, `fail`, `unavailable`, or `unchecked`. - `zip_check` (string): When used with a payment gateway that performs address checks and `zip` was provided, can be `pass`, `fail`, `unavailable`, or `unchecked`. - `cvc_check` (string): When used with a payment gateway that performs CVC code checks and `cvc` was provided, can be `pass`, `fail`, `unavailable`, or `unchecked`. - `city` (string): Billing city/district/suburb/town/village. - `country` (string): Two-letter ISO country code. - `default` (boolean): Indicates billing details represent the customer's default payment method. - `first_name` (string): Billing first name. If `name` is updated, then `first_name` will be automatically updated as the first word of the name. - `last_name` (string): Billing last name. If `name` is updated, then `last_name` will be automatically updated as the last words of the name. - `method` (string): Method of payment. Can be`card`, `account`, `amazon`, `paypal`, or any one of the manual methods defined in payment settings. - `name` (string): Billing full name. If `first_name` or `last_name` are updated, then `name` will be automatically updated as a combination of first/last. - `paypal` (object): PayPal billing details used when `billing.method=paypal`. - `payer_id` (string): PayPal payer ID provided when a customer authorizes payment in a storefront. - `payment_id` (string): PayPal payment ID created when a customer initiates payment in a storefront. - `order_id` (string) - `phone` (string): Billing phone number. - `state` (string): Billing state/county/province/region. - `zip` (string): Billing zip/postal code. - `intent` (object): Stores the necessary information about the payment. This is typically the payment ID returned by the gateway after payment is initialized. - `affirm` (object): Affirm billing details used when `billing.method=affirm`. - `resolve` (object): Resolve billing details used when `billing.method=resolve`. - `charge_id` (string): Charge ID returned by the payment gateway for the payment. - `klarna` (object): Klarna billing details used when `billing.method=klarna`. - `source` (string): Payment information returned by the gateway during payment initialization. - `ideal` (object): Ideal billing details used when `billing.method=ideal`. - `token` (string): Token used to communicate payment information to the gateway. - `bancontact` (object): Bancontact billing details used when `billing.method=bancontact`. - `source` (string): Payment information returned by the gateway during payment initialization. - `google` (object): Google Pay billing details used when `billing.method=google`. - `nonce` (string): One-time use reference element used to communicate payment information to a payment gateway. - `gateway` (string): Gateway used to facilitate the transaction. For example, `gateway=braintree`. - `apple` (object): Apple Pay billing details used when `billing.method=apple`. - `nonce` (string): One-time use reference element used to communicate payment information to a payment gateway. - `coupon_code` (string): Coupon code applied to the cart. See [coupons](https://developers.swell.is/backend-api/coupons) for details. - `items` (array of object): List of line items describing the products ordered. - `bundle_items` (array of object): List of items offered as a bundle. Defaults to `product.bundle_items`. - `id` (objectId): ID of the bundle item product. - `product_id` (objectId, required): ID of the bundle item product. - `product` (product): Expandable link to the bundle product. - `quantity` (int): Quantity of the bundle item being ordered. Defaults to 1. Default: `1`. - `shipment_weight` (float, auto): Weight to be used in shipping calculation, if applicable. - `variant_id` (objectId): ID of the bundle item variant. - `variant` (variant): Expandable link to the bundle variant. - `delivery` (enum): Method of delivery taken automatically from `product.delivery`. Possible values: `shipment`, `giftcard`, `subscription`. Default: `{"$formula":"if(product_id, product.delivery)"}`. - `options` (array of object): 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. - `id` (string): Unique identifier for the object. - `name` (string): Human-friendly name of the option. - `value` (string): 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. - `variant` (boolean): Indicates the option refers to a variant aspect. - `price` (currency): Additional price added onto the base price of the product. - `shipment_weight` (float): Additional shipping weight added onto the base weight of the product. - `value_id` (objectId) - `quantity_total` (int): Total quantity of the bundle item to be fulfilled, calculated as `item.quantity * bundle_item.quantity`. - `product_name` (string): Default: `{"$formula":"if(product_id, product.name, null)"}`. - `description` (string): Description used for custom line items, when product is not defined. - `metadata` (object): Arbitrary item data, typically set in a checkout flow to store custom values. See [Storefront API](https://developers.swell.is/frontend-api/introduction) for details. - `delivery` (enum): Method of delivery taken automatically from `product.delivery` Possible values: `shipment`, `giftcard`, `subscription`. Default: `{"$formula":"if(product_id, product.delivery)"}`. - `product_id` (objectId): ID of the item product. - `product` (product): Expandable link to the product, if applicable. - `quantity` (int): Quantity of the item being ordered. Defaults to 1. Default: `1`. - `shipment_weight` (float, auto): Weight to be used in shipping calculation, if applicable. - `taxes` (array of object): List of tax rules to apply to the item. Normally populated by tax settings. - `id` (string, required): Unique identifier for the object. Should refer to one of the IDs in the cart `taxes` object. - `amount` (currency, required): Fixed tax amount. - `variant_id` (objectId): ID of the item variant, if applicable. - `variant` (variant): Expandable link to the variant, if applicable. - `id` (objectId, auto): Unique identifier for the item. - `discount_each` (currency): Total discount amount divided by quantity. - `discount_total` (currency): Total discount applied to the item. - `orig_price` (currency): Displays the original item list price and does not reflect discounts or sale pricing. - `shipment_location` (string): ID of location from `/settings/shipping/locations`. If specified, shipping is calculated from this location. Otherwise, the store's default location will be used. - `tax_each` (currency): Total tax amount divided by quantity. - `tax_total` (currency): Total tax applied to the item. - `trial_price_total` (currency): Total of all trial prices on the order. - `product_name` (string): This field is a copy of the item's `product.name`. Default: `{"$formula":"if(product_id, product.name, null)"}`. - `trial` (boolean) - `trial_auth_total` (currency) - `purchase_option` (object) - `type` (enum): Possible values: `standard`, `subscription`, `trial`. - `id` (objectId) - `name` (string) - `price` (currency) - `auth_amount` (currency) - `trial_days` (int) - `plan_id` (objectId) - `plan_name` (string) - `plan_description` (string) - `billing_schedule` (object) - `interval` (enum): Possible values: `monthly`, `daily`, `weekly`, `yearly`. - `interval_count` (int) - `trial_days` (int) - `limit` (int) - `order_schedule` (object) - `interval` (enum): Possible values: `monthly`, `daily`, `weekly`, `yearly`. - `interval_count` (int) - `limit` (int) - `trial_discount_total` (currency) - `trial_tax_total` (currency) - `shipping` (object): The customer's shipping details. Defaults to `account.shipping`. Updating shipping will also update the corresponding account shipping object. - `account_address_id` (objectId): ID of the customer's address on file. - `account_address` (account_address): Expandable link to the customer's address on file. - `address1` (string): Shipping address line 1: (street address/PO box/company name). - `address2` (string): Shipping address line 2: (apartment/suite/unit/building). - `city` (string): Shipping city/district/suburb/town/village. - `country` (string): Two-letter ISO country code. - `default` (boolean): Indicates shipping details represent the customer's default shipping address. - `first_name` (string): Shipping first name. If `name` is updated, then `first_name` will be automatically updated as the first word of the name. - `last_name` (string): Shipping last name. If `name` is updated, then `last_name` will be automatically updated as the last words of the name. - `name` (string): Shipping full name. If `first_name` or `last_name` are updated, then `name` will be automatically updated as a combination of first/last. - `phone` (string): Shipping phone number. - `price` (currency): Price of the shipping service. Defaults to `shipment_rating.services.price` chosen by setting `service`. - `service` (string): 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.` - `service_name` (string): Name of the shipping service. Defaults to `shipment_rating.services.name` chosen by setting `service`. - `state` (string): Shipping state/county/province/region. - `zip` (string): Shipping zip/postal code. - `abandoned` (boolean): Indicates the cart was abandoned after 3 hours of inactivity. After being marked as abandoned, this field is automatically set back to `false` after an update to items, billing, or shipping info. - `abandoned_notifications` (int): Number of abandoned cart notifications sent to the customer. - `account` (Account): Expandable link to the customer's account. - `account_credit_amount` (currency): Amount of customer's account credit applied for initial payment, if applicable. - `account_credit_applied` (boolean): Indicates the customer's account credit is applied to the initial payment. - `account_info_saved` (boolean): Set `true` when the customer has indicated they want to save shipping and billing information to their account for future use. - `account_logged_in` (boolean): Indicates the customer was logged into their account when placing the order. - `active` (boolean): Indicates the cart has been updated by a customer within the last 3 hours. Default: `true`. - `checkout_id` (string): Customer-facing unique identifier for the cart used in URLs and for abandoned cart recovery. Default: `{"$formula":"md5(alphanum(128))"}`. - `checkout_url` (string): URL to checkout for the cart, set automatically when the cart has at least `items`, `shipping`, or `billing` details set. Can also be set explicitly when creating or updating the cart for custom checkouts. - `comments` (string): Customer notes provided when placing the order, if any. - `coupon` (Coupon): Expandable link to the coupon applied to the cart. - `coupon_id` (objectId): ID of the coupon applied to the cart. - `currency` (string): Three-letter ISO currency code in uppercase. Defaults to the store's base currency. - `currency_rate` (float): Currency percentage used in calculating the fixed amount. - `date_abandoned` (date): Date the cart was or will be marked as abandoned. - `date_abandoned_next` (date): Next date the cart will be marked as abandoned when using a series of abandoned cart recovery notices (advanced cart recovery). - `date_webhook_first_failed` (date): Date the order webhook first failed, if applicable. Value is unset after an order webhook is successfully returned for the record. - `date_webhook_last_succeeded` (date): Date the order webhook last succeeded, if applicable. Value is unset after an order webhook fails to return for the record. - `discount_total` (currency): Total discount amount. - `discounts` (array of object): List of discounts applied to the cart. - `id` (string): Unique identifier for the object. - `amount` (currency): Fixed discount amount. - `rule` (object): Object describing the discount rule details. Custom discounts don't require this value. - `type` (string): Type of discount. Can be `coupon` or `promo-` referring to the source of the discount. Custom discounts don't require this value. - `display_currency` (string): Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) representing the user's preferred display currency, if applicable. - `display_locale` (string): Locale code representing the user's preferred display locale, if applicable. - `draft_subscription` (boolean): Indicates cart is a draft subscription. - `gift` (boolean): Indicates the order is intended as a gift for the recipient. - `gift_message` (string): Optional message to include with the order when shipping to the recipient. - `giftcard_delivery` (boolean): Indicates the cart has at least one line item with `delivery=giftcard`. - `giftcard_total` (currency, auto): Total payment amount applied to the order from `giftcards`. - `giftcards` (array of object): List of gift cards applied to the cart. - `amount` (currency): Amount of the gift card balance to spend on this order. Defaults to `giftcard.balance`. - `code` (string): 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. - `id` (objectId): Unique identifier for the object. - `code_formatted` (string): Fully formatted gift card code for display purposes. - `giftcard` (giftcard): Expandable link to the gift card record. - `last4` (string): Last four digits of the gift card code. - `grand_total` (currency, auto): Grand total including items, shipping, and taxes. - `guest` (boolean): Indicates the customer was not logged in when placing the order. Default: `(formula)`. - `item_discount` (currency): Total discount applied to line items. - `item_quantity` (int, auto): Total quantity of all line items. - `item_shipment_weight` (float, auto): Total shipping weight of all line items. - `item_tax` (currency, auto): Total taxes applied to line items. - `item_tax_included` (boolean): Indicates line item prices include taxes. - `metadata` (object): Arbitrary data, typically set in a checkout flow to store custom values. See [Storefront API](https://developers.swell.is/frontend-api/introduction) for more details. - `notes` (string): Internal admin notes. These are not visible to the customer. - `number` (string, auto): Unique incremental cart number, assigned automatically using a format configured in general settings. - `order` (Order): Expandable link to the converted order, if applicable. - `order_id` (objectId): ID of the the converted order, if applicable. - `orig_price` (currency): Reflects the automatic price of an item, and indicates whether it's on sale or not, so as to determine if the price was customized by an API call. - `promotion_ids` (array of child_scalar): List of promotion IDs applied to the cart. - `promotions` (Promotion): Expandable list of promotions applied to the cart. - `purchase_link_ids` (array of child_scalar): Unique identifiers for the purchase links. - `purchase_links` (Purchase Link): Expandable links to the purchase links added to the cart. - `purchase_links_errors` (array of object): List of purchase link errors applied to the cart. Added when clicking on the purchase link, if any resources are blocking the creation of the cart. - `id` (objectId, auto): Unique identifier for the purchase link errors. - `error` (object, required): A purchase link error object. - `code` (string, required): A distinct code indicating the cause of the purchase link error. - `message` (string, required): A human-readable description of the purchase link error. - `resource` (object, required): An object describing the resource that blocked the creation of the cart. - `id` (objectId): Resource ID for the error. - `model` (string): Resource model. For example: `products` or `promotions`. - `name` (string): A human-readable resource name. - `purchase_link` (purchase_link): Expandable link to the purchase link. - `purchase_link_id` (string, required): Unique identifier for the purchase link to which the error relates. - `recovered` (boolean): Indicates the cart was recovered and converted to an order after being abandoned. - `schedule` (object): Schedule for a recurring order. - `interval` (enum): Interval of recurring orders. Can be `weekly`, `daily`, `monthly`, `yearly`. Possible values: `monthly`, `daily`, `weekly`, `yearly`. - `interval_count` (int): Interval multiplier for scheduled orders. For example, an `interval_count=2` paired with an `interval=monthly` would recur twice a month. - `shipment_delivery` (boolean): Indicates the cart has at least one line item with `delivery=shipment`. - `shipment_discount` (currency): Shipping discount applied by [coupons](https://developers.swell.is/backend-api/coupons), [promotions,](https://developers.swell.is/backend-api/promotions) or custom logic. - `shipment_price` (currency): Total shipping price before discounts. - `shipment_rating` (object): Object describing the shipping services and rates available for the cart. Shipping `country` must be set before retrieving shipping rates. - `fingerprint` (string): Unique fingerprint identifying the parameters used to calculate shipping rates. Rates should always be the same given the same parameters and shipping settings. - `services` (array of object): List of shipping services and rates available. - `id` (string): Unique identifier for the object. - `name` (string): Name of the shipment service. - `carrier` (string): Name of the third party carrier offering the service, if applicable. - `price` (currency): Price of given shipment service. - `pickup` (boolean): Indicated whether the shipment service is local pick-up. - `tax_code` (string): Applicable tax code for shipment service. - `errors` (array of object): List of errors generated while retrieving rates, if any. When using third-party shipping services, any system errors will be listed here. - `message` (string): Brief description of the error. - `code` (string): Unique error code for reference. - `shipment_tax` (currency): Shipping tax amount, if applicable. - `shipment_tax_included` (boolean): Indicates shipping total includes taxes, if applicable. - `shipment_tax_included_total` (currency): Total of taxes applied separately from line items. - `shipment_total` (currency): Total shipping price after discounts. - `status` (enum, auto): Current status of the cart. Can be `active`, `converted`, `abandoned`, or `recovered`. Possible values: `converted`, `recovered`, `abandoned`, `active`. Default: `"active"`. - `sub_total` (currency): Sum of all line items before discounts, taxes and shipping. - `subscription` (Subscription): Expandable link to the subscription that spawned the order, if applicable. - `subscription_delivery` (boolean): Indicates the cart has at least one line item with `delivery=subscription`. - `subscription_id` (objectId): ID of the subscription that spawned the order, if applicable. - `target_order` (Order): Expands into the order that the cart was converted into. - `target_order_id` (objectId): When a cart is converted to an order, this field represents the corresponding `order_id`. - `tax_included_total` (currency): Total with shipping and item taxes included. Allows for an alternate display style, as normally `sub_total` and `tax_total` are shown separately. - `tax_total` (currency): Total tax amount applied to the cart including line items and shipping. - `taxes` (array of object): List of taxes applied to the cart. - `id` (string): Unique identifier for the object. - `amount` (currency): Fixed tax amount. - `name` (string): Name of the tax rule. For example, "NY Sales Tax". - `priority` (int): 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. - `rate` (float): Tax percentage used in calculating the fixed amount. - `shipping` (boolean): Indicates the tax applies to shipping. - `taxes_fixed` (boolean): Indicates the order is tax-exempt. Taxes will not be calculated or applied when true. - `webhook_attempts_failed` (int): Number of failed order webhook attempts, if applicable. Value is unset after an order webhook is successfully returned for the record. - `webhook_response` (string): Text response of the last failed order webhook attempt, if applicable. Value is unset after an order webhook is successfully returned for the record. - `webhook_status` (int): HTTP response status of the last failed order webhook attempt, if applicable. Value is unset after an order webhook is successfully returned for the record. ### Example request `POST /carts` **cURL** ```bash $ curl https://api.swell.store/carts \ -u store-id:secret-key \ -d items[0][product_id]=5cad15bc9b14d1990724663a \ -d items[0][quantity]=2 \ -d coupon_code=FREESHIPPING ``` **Node** ```javascript 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', }); ``` **PHP** ```php post('/carts', [ 'items' => [ [ 'product_id' => '5cad15bc9b14d1990724663a', 'quantity' => 2, 'options' => [...] ] ], 'billing' => [ ... ], 'shipping' => [ ... ], 'coupon_code' => 'FREESHIPPING', ]); ``` ### Example response ```json { "id": "5cad15bc9b14d1990724663a", "active": true, "billing": {...}, "shipping": {...}, "items": [ { "id": "5a9ea7ba3f95740a914267f2", "product_id": "5cad15bc9b14d1990724663b", "quantity": 2, "price": 9.99, "price_total": 18.98, "shipment_weight": 1.5, ... } ], "coupon_code": "FREESHIPPING", "currency": "USD", "date_created": "2019-04-01T00:00:00.000Z", "discount_total": 0, "grand_total": 18.98, "item_quantity": 2, "item_shipment_weight": 3.0, "item_tax": 0, "number": "100101", "shipment_price": 0, "shipment_total": 0, "status": "active", "sub_total": 0, "tax_total": 0, ... } ``` ## Retrieve a cart Retrieve an existing cart using the ID that was returned when created. ### Arguments - `id` (objectId, required): The id of the cart to retrieve. - `expand` (string): Expanding link fields and child collections is performed using the expand argument. - For example, `expand=account` would return a related customer account if one exists. When the field represents a collection, you can specify the query limit. - For example, `expand=variants:10` would return up to 10 records of the variants collection. See [expanding ](https://developers.swell.is/backend-api/querying/expanding)for more details. - `fields` (string): Return only the specified fields in the result. For example `fields=name,slug` would return only the fields `name` and `slug` in the response. Supports nested object and array fields using dot-notation, for example, `items.product_id`. The category `id` is always returned. - `include` (string): Include one or more arbitrary queries in the response, possibly related to the main query. See [including ](https://developers.swell.is/backend-api/querying/including)for more details. ### Example request `GET /carts/:id` **cURL** ```bash $ curl https://api.swell.store/carts/5cad15bc9b14d1990724663a \ -u store-id:secret-key ``` **Node** ```javascript const { swell } = require('swell-node'); swell.init('store-id', 'secret-key'); await swell.get('/carts/{id}', { id: '5cad15bc9b14d1990724663a', }); ``` **PHP** ```php get('/carts/{id}', [ 'id' => '5cad15bc9b14d1990724663a', ]); ``` ### Example response ```json { "id": "5cad15bc9b14d1990724663a", "active": true, "billing": {...}, "shipping": {...}, "items": [ { "id": "5a9ea7ba3f95740a914267f2", "product_id": "5cad15bc9b14d1990724663b", "quantity": 2, "price": 9.99, "price_total": 18.98, "shipment_weight": 1.5, ... } ], "coupon_code": "FREESHIPPING", "currency": "USD", "date_created": "2019-04-01T00:00:00.000Z", "discount_total": 0, "grand_total": 18.98, "item_quantity": 2, "item_shipment_weight": 3.0, "item_tax": 0, "number": "100101", "shipment_price": 0, "shipment_total": 0, "status": "active", "sub_total": 0, "tax_total": 0, ... } ``` ## Update a cart Update an existing cart using the ID that was returned when created. Updating performs a merge operation. To explicitly override values such as arrays, use the `$set` operator. ### Arguments - `id` (objectId, required): Unique identifier for the cart. - `account_id` (objectId): ID of the customer's account. - `billing` (object): The customer's billing details. Defaults to `account.billing`. Updating billing will also update the corresponding account billing object. - `account_card_id` (objectId): ID of the customer's credit card on file, if applicable. - `account_card` (account_card): Expandable link to the customer's credit card on file, if applicable. - `address1` (string): Billing address line 1: street address/PO box/company name. - `address2` (string): Billing address line 2: apartment/suite/unit/building. - `amazon` (object): Amazon billing details used when `billing.method=amazon`. - `access_token` (string): Amazon access token provided when a customer authorizes payment in a storefront. - `order_reference_id` (string): Amazon order reference ID created when a customer initiates payment in a storefront. - `checkout_session_id` (string) - `card` (object): Credit card billing details used when `billing.method=card`. - `token` (string): Token generated by Swell Checkout or Stripe.js. - `exp_month` (int): Two-digit number representing the credit card expiration month. - `exp_year` (int): Four-digit number representing the credit card expiration year. - `brand` (string): Credit card brand. Can be `American Express`, `Diners Club`, `Discover`, `JCB`, `MasterCard`, `UnionPay`, `Visa`, or `Unknown`. - `last4` (string): Last four digits of the card number. - `gateway` (string): ID of the payment gateway that should be used to process payments. - `test` (boolean): Indicates this is a test card. - `address_check` (string): When used with a payment gateway that performs address checks and `address1` was provided, can be `pass`, `fail`, `unavailable`, or `unchecked`. - `zip_check` (string): When used with a payment gateway that performs address checks and `zip` was provided, can be `pass`, `fail`, `unavailable`, or `unchecked`. - `cvc_check` (string): When used with a payment gateway that performs CVC code checks and `cvc` was provided, can be `pass`, `fail`, `unavailable`, or `unchecked`. - `city` (string): Billing city/district/suburb/town/village. - `country` (string): Two-letter ISO country code. - `default` (boolean): Indicates billing details represent the customer's default payment method. - `first_name` (string): Billing first name. If `name` is updated, then `first_name` will be automatically updated as the first word of the name. - `last_name` (string): Billing last name. If `name` is updated, then `last_name` will be automatically updated as the last words of the name. - `method` (string): Method of payment. Can be`card`, `account`, `amazon`, `paypal`, or any one of the manual methods defined in payment settings. - `name` (string): Billing full name. If `first_name` or `last_name` are updated, then `name` will be automatically updated as a combination of first/last. - `paypal` (object): PayPal billing details used when `billing.method=paypal`. - `payer_id` (string): PayPal payer ID provided when a customer authorizes payment in a storefront. - `payment_id` (string): PayPal payment ID created when a customer initiates payment in a storefront. - `order_id` (string) - `phone` (string): Billing phone number. - `state` (string): Billing state/county/province/region. - `zip` (string): Billing zip/postal code. - `coupon_code` (string): Coupon code applied to the cart. See [coupons](https://developers.swell.is/backend-api/coupons) for details. - `items` (array of object): List of line items describing the products ordered. - `bundle_items` (array of object): List of items offered as a bundle. Defaults to `product.bundle_items`. - `id` (objectId): ID of the bundle item product. - `product_id` (objectId, required): ID of the bundle item product. - `product` (product): Expandable link to the bundle product. - `quantity` (int): Quantity of the bundle item being ordered. Defaults to 1. Default: `1`. - `shipment_weight` (float, auto): Weight to be used in shipping calculation, if applicable. - `variant_id` (objectId): ID of the bundle item variant. - `variant` (variant): Expandable link to the bundle variant. - `delivery` (enum): Method of delivery taken automatically from `product.delivery`. Possible values: `shipment`, `giftcard`, `subscription`. Default: `{"$formula":"if(product_id, product.delivery)"}`. - `options` (array of object): 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. - `id` (string): Unique identifier for the object. - `name` (string): Human-friendly name of the option. - `value` (string): 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. - `variant` (boolean): Indicates the option refers to a variant aspect. - `price` (currency): Additional price added onto the base price of the product. - `shipment_weight` (float): Additional shipping weight added onto the base weight of the product. - `value_id` (objectId) - `quantity_total` (int): Total quantity of the bundle item to be fulfilled, calculated as `item.quantity * bundle_item.quantity`. - `product_name` (string): Default: `{"$formula":"if(product_id, product.name, null)"}`. - `description` (string): Description used for custom line items, when product is not defined. - `metadata` (object): Arbitrary item data, typically set in a checkout flow to store custom values. See [Storefront API](https://developers.swell.is/frontend-api/introduction) for details. - `delivery` (enum): Method of delivery taken automatically from `product.delivery` Possible values: `shipment`, `giftcard`, `subscription`. Default: `{"$formula":"if(product_id, product.delivery)"}`. - `product_id` (objectId): ID of the item product. - `product` (product): Expandable link to the product, if applicable. - `quantity` (int): Quantity of the item being ordered. Defaults to 1. Default: `1`. - `shipment_weight` (float, auto): Weight to be used in shipping calculation, if applicable. - `taxes` (array of object): List of tax rules to apply to the item. Normally populated by tax settings. - `id` (string, required): Unique identifier for the object. Should refer to one of the IDs in the cart `taxes` object. - `amount` (currency, required): Fixed tax amount. - `variant_id` (objectId): ID of the item variant, if applicable. - `variant` (variant): Expandable link to the variant, if applicable. - `id` (objectId, auto): Unique identifier for the item. - `discount_each` (currency): Total discount amount divided by quantity. - `discount_total` (currency): Total discount applied to the item. - `orig_price` (currency): Displays the original item list price and does not reflect discounts or sale pricing. - `shipment_location` (string): ID of location from `/settings/shipping/locations`. If specified, shipping is calculated from this location. Otherwise, the store's default location will be used. - `tax_each` (currency): Total tax amount divided by quantity. - `tax_total` (currency): Total tax applied to the item. - `trial_price_total` (currency): Total of all trial prices on the order. - `product_name` (string): This field is a copy of the item's `product.name`. Default: `{"$formula":"if(product_id, product.name, null)"}`. - `purchase_option` (object) - `type` (enum): Possible values: `standard`, `subscription`, `trial`. - `id` (objectId) - `name` (string) - `price` (currency) - `auth_amount` (currency) - `trial_days` (int) - `plan_id` (objectId) - `plan_name` (string) - `plan_description` (string) - `billing_schedule` (object) - `interval` (enum): Possible values: `monthly`, `daily`, `weekly`, `yearly`. - `interval_count` (int) - `trial_days` (int) - `limit` (int) - `order_schedule` (object) - `interval` (enum): Possible values: `monthly`, `daily`, `weekly`, `yearly`. - `interval_count` (int) - `limit` (int) - `shipping` (object): The customer's shipping details. Defaults to `account.shipping`. Updating shipping will also update the corresponding account shipping object. - `account_address_id` (objectId): ID of the customer's address on file. - `account_address` (account_address): Expandable link to the customer's address on file. - `address1` (string): Shipping address line 1: (street address/PO box/company name). - `address2` (string): Shipping address line 2: (apartment/suite/unit/building). - `city` (string): Shipping city/district/suburb/town/village. - `country` (string): Two-letter ISO country code. - `default` (boolean): Indicates shipping details represent the customer's default shipping address. - `first_name` (string): Shipping first name. If `name` is updated, then `first_name` will be automatically updated as the first word of the name. - `last_name` (string): Shipping last name. If `name` is updated, then `last_name` will be automatically updated as the last words of the name. - `name` (string): Shipping full name. If `first_name` or `last_name` are updated, then `name` will be automatically updated as a combination of first/last. - `phone` (string): Shipping phone number. - `price` (currency): Price of the shipping service. Defaults to `shipment_rating.services.price` chosen by setting `service`. - `service` (string): 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.` - `service_name` (string): Name of the shipping service. Defaults to `shipment_rating.services.name` chosen by setting `service`. - `state` (string): Shipping state/county/province/region. - `zip` (string): Shipping zip/postal code. - `account_credit_amount` (currency): Amount of customer's account credit applied for initial payment, if applicable. - `account_info_saved` (boolean): Set `true` when the customer has indicated they want to save shipping and billing information to their account for future use. - `account_logged_in` (boolean): Indicates the customer was logged into their account when placing the order. - `account` (Account): Expandable link to the customer's account. - `comments` (string): Customer notes provided when placing the order, if any. - `coupon_id` (objectId): ID of the coupon applied to the cart. - `date_abandoned` (date): Date the cart was or will be marked as abandoned. - `date_abandoned_next` (date): Next date the cart will be marked as abandoned when using a series of abandoned cart recovery notices (advanced cart recovery). - `discounts` (array of object): List of discounts applied to the cart. - `id` (string): Unique identifier for the object. - `amount` (currency): Fixed discount amount. - `rule` (object): Object describing the discount rule details. Custom discounts don't require this value. - `type` (string): Type of discount. Can be `coupon` or `promo-` referring to the source of the discount. Custom discounts don't require this value. - `display_currency` (string): Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) representing the user's preferred display currency, if applicable. - `display_locale` (string): Locale code representing the user's preferred display locale, if applicable. - `gift_message` (string): Optional message to include with the order when shipping to the recipient. - `giftcards` (array of object): List of gift cards applied to the cart. - `amount` (currency): Amount of the gift card balance to spend on this order. Defaults to `giftcard.balance`. - `code` (string): 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. - `id` (objectId): Unique identifier for the object. - `code_formatted` (string): Fully formatted gift card code for display purposes. - `giftcard` (giftcard): Expandable link to the gift card record. - `last4` (string): Last four digits of the gift card code. - `gift` (boolean): Indicates the order is intended as a gift for the recipient. - `guest` (boolean): Indicates the customer was not logged in when placing the order. Default: `(formula)`. - `item_tax_included` (boolean): Indicates line item prices include taxes. - `metadata` (object): Arbitrary data, typically set in a checkout flow to store custom values. See [Storefront API](https://developers.swell.is/frontend-api/introduction) for more details. - `notes` (string): Internal admin notes. These are not visible to the customer. - `promotion_ids` (array of child_scalar): List of promotion IDs applied to the cart. - `recovered` (boolean): Indicates the cart was recovered and converted to an order after being abandoned. - `shipment_discount` (currency): Shipping discount applied by [coupons](https://developers.swell.is/backend-api/coupons), [promotions,](https://developers.swell.is/backend-api/promotions) or custom logic. - `shipment_tax` (currency): Shipping tax amount, if applicable. - `shipment_tax_included` (boolean): Indicates shipping total includes taxes, if applicable. - `taxes` (array of object): List of taxes applied to the cart. - `id` (string): Unique identifier for the object. - `amount` (currency): Fixed tax amount. - `name` (string): Name of the tax rule. For example, "NY Sales Tax". - `priority` (int): 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. - `rate` (float): Tax percentage used in calculating the fixed amount. - `shipping` (boolean): Indicates the tax applies to shipping. - `abandoned` (boolean): Indicates the cart was abandoned after 3 hours of inactivity. After being marked as abandoned, this field is automatically set back to `false` after an update to items, billing, or shipping info. - `abandoned_notifications` (int): Number of abandoned cart notifications sent to the customer. - `active` (boolean): Indicates the cart has been updated by a customer within the last 3 hours. Default: `true`. - `checkout_id` (string): Customer-facing unique identifier for the cart used in URLs and for abandoned cart recovery. Default: `{"$formula":"md5(alphanum(128))"}`. - `checkout_url` (string): URL to checkout for the cart, set automatically when the cart has at least `items`, `shipping`, or `billing` details set. Can also be set explicitly when creating or updating the cart for custom checkouts. - `coupon` (Coupon): Expandable link to the coupon applied to the cart. - `currency` (string): Three-letter ISO currency code in uppercase. Defaults to the store's base currency. - `currency_rate` (float): Currency percentage used in calculating the fixed amount. - `date_webhook_first_failed` (date): Date the order webhook first failed, if applicable. Value is unset after an order webhook is successfully returned for the record. - `discount_total` (currency): Total discount amount. - `giftcard_delivery` (boolean): Indicates the cart has at least one line item with `delivery=giftcard`. - `giftcard_total` (currency, auto): Total payment amount applied to the order from `giftcards`. - `grand_total` (currency, auto): Grand total including items, shipping, and taxes. - `item_discount` (currency): Total discount applied to line items. - `item_shipment_weight` (float, auto): Total shipping weight of all line items. - `item_tax` (currency, auto): Total taxes applied to line items. - `item_quantity` (int, auto): Total quantity of all line items. - `number` (string, auto): Unique incremental cart number, assigned automatically using a format configured in general settings. - `order_id` (objectId): ID of the the converted order, if applicable. - `order` (Order): Expandable link to the converted order, if applicable. - `promotions` (Promotion): Expandable list of promotions applied to the cart. - `shipment_delivery` (boolean): Indicates the cart has at least one line item with `delivery=shipment`. - `shipment_price` (currency): Total shipping price before discounts. - `shipment_rating` (object): Object describing the shipping services and rates available for the cart. Shipping `country` must be set before retrieving shipping rates. - `services` (array of object): List of shipping services and rates available. - `id` (string): Unique identifier for the object. - `name` (string): Name of the shipment service. - `carrier` (string): Name of the third party carrier offering the service, if applicable. - `price` (currency): Price of given shipment service. - `pickup` (boolean): Indicated whether the shipment service is local pick-up. - `tax_code` (string): Applicable tax code for shipment service. - `errors` (array of object): List of errors generated while retrieving rates, if any. When using third-party shipping services, any system errors will be listed here. - `message` (string): Brief description of the error. - `code` (string): Unique error code for reference. - `shipment_total` (currency): Total shipping price after discounts. - `status` (enum, auto): Current status of the cart. Can be `active`, `converted`, `abandoned`, or `recovered`. Possible values: `converted`, `recovered`, `abandoned`, `active`. Default: `"active"`. - `sub_total` (currency): Sum of all line items before discounts, taxes and shipping. - `subscription` (Subscription): Expandable link to the subscription that spawned the order, if applicable. - `subscription_delivery` (boolean): Indicates the cart has at least one line item with `delivery=subscription`. - `subscription_id` (objectId): ID of the subscription that spawned the order, if applicable. - `tax_included_total` (currency): Total with shipping and item taxes included. Allows for an alternate display style, as normally `sub_total` and `tax_total` are shown separately. - `tax_total` (currency): Total tax amount applied to the cart including line items and shipping. - `webhook_attempts_failed` (int): Number of failed order webhook attempts, if applicable. Value is unset after an order webhook is successfully returned for the record. - `webhook_response` (string): Text response of the last failed order webhook attempt, if applicable. Value is unset after an order webhook is successfully returned for the record. - `webhook_status` (int): HTTP response status of the last failed order webhook attempt, if applicable. Value is unset after an order webhook is successfully returned for the record. - `target_order_id` (objectId): When a cart is converted to an order, this field represents the corresponding `order_id`. - `target_order` (Order): Expands into the order that the cart was converted into. - `taxes_fixed` (boolean): Indicates the order is tax-exempt. Taxes will not be calculated or applied when true. - `schedule` (object): Schedule for a recurring order. - `interval` (enum): Interval of recurring orders. Can be `weekly`, `daily`, `monthly`, `yearly`. Possible values: `monthly`, `daily`, `weekly`, `yearly`. - `interval_count` (int): Interval multiplier for scheduled orders. For example, an `interval_count=2` paired with an `interval=monthly` would recur twice a month. - `account_credit_applied` (boolean): Indicates the customer's account credit is applied to the initial payment. - `date_webhook_last_succeeded` (date): Date the order webhook last succeeded, if applicable. Value is unset after an order webhook fails to return for the record. - `purchase_links` (Purchase Link): Expandable links to the purchase links added to the cart. - `purchase_link_ids` (array of child_scalar): Unique identifiers for the purchase links. - `purchase_links_errors` (array of object): List of purchase link errors applied to the cart. Added when clicking on the purchase link, if any resources are blocking the creation of the cart. - `id` (objectId, auto): Unique identifier for the purchase link errors. - `error` (object, required): A purchase link error object. - `code` (string, required): A distinct code indicating the cause of the purchase link error. - `message` (string, required): A human-readable description of the purchase link error. - `resource` (object, required): An object describing the resource that blocked the creation of the cart. - `id` (objectId): Resource ID for the error. - `model` (string): Resource model. For example: `products` or `promotions`. - `name` (string): A human-readable resource name. - `purchase_link` (purchase_link): Expandable link to the purchase link. - `purchase_link_id` (string, required): Unique identifier for the purchase link to which the error relates. ### Example request `PUT /carts/:id` **cURL** ```bash $ curl https://api.swell.store/carts/5cad15bc9b14d1990724663a \ -u store-id:secret-key \ -d name="Jon Snow" \ -d address1="1 Main Street" \ -d city=Brooklyn \ -d state=NY \ -d zip=11201 \ -d country=US \ -d phone="(555) 555-5555" \ -X PUT ``` **Node** ```javascript 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', }, }); ``` **PHP** ```php 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' ] ]); ``` ### Example response ```json { "id": "5cad15bc9b14d1990724663a", "active": true, "billing": {...}, "shipping": { "name": "Jon Snow", "first_name": "Jon", "last_name": "Snow", "address1": "1 Main Street", "city": "Brooklyn", "state": "NY", "zip": "11201", "country": "US", "phone": "(555) 555-5555" }, "items": [ { "id": "5a9ea7ba3f95740a914267f2", "product_id": "5cad15bc9b14d1990724663b", "quantity": 2, "price": 9.99, "price_total": 18.98, "shipment_weight": 1.5, ... } ], "coupon_code": "FREESHIPPING", "currency": "USD", "date_created": "2019-04-01T00:00:00.000Z", "date_updated": "2019-04-01T00:00:00.000Z", "discount_total": 0, "grand_total": 18.98, "item_quantity": 2, "item_shipment_weight": 3.0, "item_tax": 0, "number": "100101", "shipment_price": 0, "shipment_total": 0, "status": "active", "sub_total": 0, "tax_total": 0, ... } ``` ## Convert carts to orders Create a new order from an active cart. This call will map items and other properties from a cart while creating the order and mark the cart as converted. Returns an error if any of the required order properties are missing from the cart, or if product stock is unavailable. ### Arguments - `cart_id` (objectId): ID of the cart to convert. ### Example request `POST /orders` **cURL** ```bash $ curl https://api.swell.store/orders \ -u store-id:secret-key \ -d cart_id=5cad15bc9b14d1990724663a ``` **Node** ```javascript const { swell } = require('swell-node'); swell.init('store-id', 'secret-key'); await swell.post('/orders', { cart_id: '5cad15bc9b14d1990724663a', }); ``` **PHP** ```php post('/orders', [ 'cart_id' => '5cad15bc9b14d1990724663a', ]); ``` ### Example response ```json { "id": "5cad15bc9b14d1990724663b", "account_id": "5a9ea7ba3f95740a914267f1", "billing": {...}, "cart_id": "5cad15bc9b14d1990724663a", "shipping": {...}, "items": [ { "id": "5a9ea7ba3f95740a914267f2", "product_id": "5cad15bc9b14d1990724663b", "quantity": 2, "price": 9.99, "price_total": 18.98, "shipment_weight": 1.5, ... } ], "coupon_code": "FREESHIPPING", "currency": "USD", "date_created": "2019-04-01T00:00:00.000Z", "delivered": false, "discount_total": 0, "grand_total": 18.98, "item_quantity": 2, "item_shipment_weight": 3.0, "item_tax": 0, "number": "100101", "paid": false, "payment_balance": -18.98, "payment_total": 0, "refund_total": 0, "refunded": false, "shipment_price": 0, "shipment_total": 0, "status": "payment_pending", "sub_total": 0, "tax_total": 0, ... } ``` ## List all carts Return a list of carts ### Arguments - `expand` (string): Expand link fields and child collections by using the expand argument. - For example, `expand=account` would return a related customer account if one exists. When the field represents a collection, you can specify the query limit. - For example, `expand=variants:10` would return up to 10 records of the variants collection. See [expanding](https://developers.swell.is/backend-api/querying/expanding) for more details. - `fields` (string): Returns only the specified fields in the result. - For example `fields=name,slug` would return only the fields `name` and `slug` in the response. Supports nested object and array fields using dot-notation. - For example, `items.product_id`. The product `id` is always returned. - `include` (object): Include one or more arbitrary queries in the response which are potentially related to the main query. See [including](https://developers.swell.is/backend-api/querying/including) for more details. - `limit` (int): Limit the number of records returned, ranging between `1` and `1000`. Defaults to `15`. Default: `15`. - `page` (int): The page number of results to return given the specified or default `limit`. - `search` (string): A text search is performed using the search argument. Searchable fields are defined by the model. - For example, `search=red` would return records containing the word "red" anywhere in the defined text fields. See [searching](https://developers.swell.is/backend-api/querying/searching) for more details. - `sort` (string): Expression to sort results by using a format similar to a SQL sort statement. - For example, `sort=name asc` would return records sorted by name ascending. See [sorting](https://developers.swell.is/backend-api/querying/sorting) for more details. - `where` (object): An object with criteria to filter the result. - For example, `active=true` would return records containing a field `active` with the value `true`. It's also possible to use query operators, for example, `$eq`, `$ne`, `$gt`, and more. See [querying](https://developers.swell.is/backend-api/querying) for more details. ### Example request `GET /carts` **cURL** ```bash $ curl https://api.swell.store/carts?where[active]=true&limit=25&page=1 \ -u store-id:secret-key \ -G ``` **Node** ```javascript const { swell } = require('swell-node'); swell.init('store-id', 'secret-key'); await swell.get('/carts', { where: { active: true }, limit: 25, page: 1, }); ``` **PHP** ```php get('/carts', [ 'where' => [ 'active' => true ], 'limit' => 25, 'page' => 1, ]); ``` ### Example response ```json { "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, "page_count": 3, "limit": 25, "pages": { "1": { "start": 1, "end": 25 }, "2": { "start": 26, "end": 50 }, "3": { "start": 51, "end": 51 } } } ``` ## Delete a cart ### Arguments - `id` (objectId, required): The id for the cart to delete. ### Example request `DELETE /carts/:id` **cURL** ```bash $ curl https://api.swell.store/carts/5cad15bc9b14d1990724663a \ -u store-id:secret-key \ -X DELETE ``` **Node** ```javascript const { swell } = require('swell-node'); swell.init('store-id', 'secret-key'); await swell.delete('/carts/{id}', { id: '5cad15bc9b14d1990724663a', }); ``` **PHP** ```php delete('/carts/{id}', [ 'id' => '5cad15bc9b14d1990724663a', ]); ``` ### Example response ```json { "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, ... } ```