• Version: 1.2.0

Carts

Carts contain the products, variations, and custom items that a customer will purchase, but has not yet. You can supply a discount code to a cart in order to apply a promotion that uses a coupon code. Each cart maintains a running total of the value of all products it contains, both pre- and post-discount and pre- and post-tax, as well as the currency that the customer uses.

Carts are automatically created with customers and share ID numbers with those objects. You can, however, create additional carts by calling any of the statements shown below with a unique string - that is, a string not already used as an ID number or slug for any store object - as an ID number.

When a customer is ready to purchase the items in their cart, you can convert their cart into an order using the checkout endpoint.

Because carts are flows-based data structures, you can modify the data that they store on the fly. Customer flows have the following fields by default:

Key Type Required Unique Details
id Integer No Yes Automatically generated when you create the customer.
contents Array No No An array of all of the products that have been added to this cart.
discount_code String No No A string that will activate a promotion if it matches an existing discount code.
total_items Integer No No The total quantity of products, variations, and custom items that have been added to the cart.
total_unique_items Integer No No The number of discreet product, variation, and custom item types that have been added to the cart.
totals Array No No The value of the cart, pre_discount and post_discount, each of which are arrays that contain the price with_tax, the price without_tax, and the cost of the tax.
currency Array No No The currency to be used at checkout.

Before you can use this (or any endpoint), you need to authenticate to get a bearer token.

This topic will cover the following processes:

Retrieve Cart Information

You have two methods to retrieve cart information. The first requires that you know the ID number of the cart that you want, and it returns solely the information for that one cart. If you don’t know the cart ID number, you can return an array of all valid extensions of the carts endpoint, which includes all cart and customer IDs.

Retrieve a Single Cart by ID

You can GET information for a single cart by adding the customer’s ID number to the carts endpoint. No additional data fields are required.

curl -X GET https://api.molt.in/v1/carts/:cartIdent \
  -H "Authorization: Bearer XXXX"

A successful call returns a 200 OK HTML status and the cart information for the cart, including any products that it contains. The object it returns looks like this by default (the data will be different, of course):

{
  "status":true,
  "result":
  {
    "contents":[],
    "discount_code":null,
    "total_items":0,
    "total_unique_items":0,
    "totals":
    {
      "pre_discount":
      {
        "formatted":
        {
          "with_tax":"\u00a30.00",
          "without_tax":"\u00a30.00",
          "tax":"\u00a30.00"
        },
        "rounded":
        {
          "with_tax":0,
          "without_tax":0,
          "tax":0
        },
        "raw":
        {
          "with_tax":0,
          "without_tax":0,
          "tax":0
        }
      },
      "post_discount":
      {
        "formatted":
        {
          "with_tax":"\u00a30.00",
          "without_tax":"\u00a30.00",
          "tax":"\u00a30.00"
        },
        "rounded":
        {
          "with_tax":0,
          "without_tax":0,
          "tax":0
        },
        "raw":
        {
          "with_tax":0,
          "without_tax":0,
          "tax":0
        }
      }
    },
    "currency":
    {
      "id":"xxx",
      "code":"GBP",
      "format":"\u00a3{price}",
      "decimal":".",
      "thousand":",",
      "rounding":null,
      "exchange":0
    }
  }
}

Add a Product to a Cart

Your carts don’t do much for you if they don’t contain any products. To add products to a cart, POST the ID number of the product and the total quantity to the carts/{ID number} endpoint. This will return the selected product information, not the cart information.

curl -X POST https://api.molt.in/v1/carts/:cartIdent \
  -H "Authorization: Bearer XXXX" \
  -d "quantity=1" \
  -d "id=<productId>"

On success, this call returns a 201 Created HTML status code.

Add a Variation to a Cart

If you want to add a specific variation of a product, you’ll need to change how you call the endpoint some. For the variation, you need to pass a modifier ID and variation ID pair to the individual cart endpoint in addition to the product ID and quantity. In order to send the array values, you need to add the -g / –globoff switch to the statement so that the bracket characters pass through as array indicators correctly.

curl -X POST https://api.molt.in/v1/carts/:cartIdent \
  -H "Authorization: Bearer XXXX" \
  -g \
  -d "quantity=1" \
  -d "id=<productID" \
  -d "modifier[<modifierID>]=<variationID>"

Successful calls return 201 Created.

Check if Item is in a Cart

Moltin offers a simplified method to check if a cart already contains a specific product or variation. Use a GET call on the https://api.molt.in/v1/carts/{cart ID}/has/{product or variation ID} endpoint. This will return either true or false depending on if the item exists in the cart or not.

curl -X GET https://api.molt.in/v1/carts/:cartIdent/has/:productId \
  -H "Authorization: Bearer XXXX"

On success, this returns 200 OK.

Retrieve an Item from a Cart

Once you have verified that the item is in the cart, you can return its current information using a similar endpoint as in the section above, except replace “has” with “item”.

curl -X GET https://api.molt.in/v1/carts/:cartIdent/item/:itemIdent \
  -H "Authorization: Bearer XXXX"

On success, this returns 200 OK and the product or variation information with pricing data.

Update an Item in a Cart

You can modify some aspects of products and variations within a cart without changing the details of the product or variation itself. Use a PUT call on the endpoint from the previous section and the data fields that you want to change. You can update any of the data fields in the following table.

Key Type Details
name String The name of the item within the cart.
quantity Integer The new total number of items in the cart.
price decimal The base price of the item in the cart.
weight decimal -
height decimal -
width decimal -
depth decimal -
curl -X PUT https://api.molt.in/v1/carts/:cartIdent/item/:itemIdent \
  -H "Authorization: Bearer XXXX" \
  -d "name=Gift-wrapped Coffeemaker" \
  -d "price=45.00" \
  -d "weight=3.2"

On success, this returns 200 OK.

Delete an Item from Cart

To remove an item, use the same endpoint from the Update an Item in a Cart section with the DELETE method.

curl -X DELETE https://api.molt.in/v1/carts/:cartIdent/item/:itemIdent \
  -H "Authorization: Bearer XXXX"

On success, this returns 200 OK.

Delete a Cart and All Contents

If you want to get rid of an entire cart and its contents, you can call the carts/{cart ID} with the DELETE method. This will not affect any associated customer, but it will prevent you from creating an order from the cart using the checkout endpoint. Carts that have been converted into orders do not need to be deleted. This action cannot be undone. You can, however, create a new cart using the same ID number by using that ID number as the unique string within any of the above calls.

curl -X DELETE https://api.molt.in/v1/carts/:cartIdent \
  -H "Authorization: Bearer XXXX"

If successful, this call will return 200 OK and the following:

{
	"status":true,
	"message":"Cart destroyed successfully."
}