# Create a cart

Source: https://developers.swell.is/backend-api/carts/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-<id>` 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
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->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,
  ...
}
```