Create a cart

The Cart object is the fundamental building block for checking out with Rye. Carts hold products

Some key terms to understand when working with carts are:

• Buyer identity refers to the shipping address that the cart items should be delivered to.
• Cart items are products contained within a cart. The process of checking out a cart results in the shopper purchasing the cart items for that cart. Sometimes, the term “cart line” will also be used in this context.
• An offer represents pricing for an order with a store, including shipping info and tax.

​

Tutorial

​

Step 1: Create your first cart

Carts can be created with the createCart mutation.

The GraphQL operation below will create a cart containing an egg separator sold by Amazon:

mutation CreateFirstCart {
  createCart(
    input: {
      items: {
        amazonCartItemsInput: [{
          quantity: 1
          productId: "B00A2KD8NY"
        }]
      }
    }
  ) {
    cart {
      id # NOTE: This `id` is important!
      cost {
        isEstimated
        subtotal {
          currency
          displayValue
          value
        }
        shipping {
          currency
          displayValue
          value
        }
        total {
          currency
          displayValue
          value
        }
      }
      stores {
        ... on AmazonStore {
          cartLines {
            quantity
            product {
              id
              title
            }
          }
          errors {
            code
            message
          }
        }
      }
    }
    errors {
      code
      message
    }
  }
}

The id field returned under the cart object is very important. It is the identifier for the cart you created, and you must have it available if you want to use other cart management endpoints on this cart. In the next step, we’ll look at how we can use this cart identifier with the addCartItems mutation to add a second product.

Rye reports prices in terms of a currency’s “base unit.” For US dollars, the base unit is a cent. A value of 795 should therefore be interpreted as “795 cents” when working with USD. We report currencies in this way in order to avoid floating point arithmetic errors.

Note that it is possible for there to be top-level errors for the cart itself, and also for there to be more granular errors on the stores the cart relates to (in the form of AmazonStoreError or ShopifyStoreError). A robust integration with Rye should check both levels of the response, and handle errors if they exist.

​

Step 2: Adjust cart items

Most Rye integrations will let shoppers make adjustments to their cart before checking out. For example, it may be possible for the shopper to add or remove products after they have made their initial selection, or increase the quantity of a cart item.

Rye offers API operations which support all of these use cases. In this step, we’ll add another Amazon product to the cart we just made. Note that you will need to have the cart’s ID value handy for this.

The following mutation will add a two units of a cleanser from CeraVe to our cart:

mutation AddCeraVeCream {
  addCartItems(
    input: {
      # NOTE: Replace this value with your own cart's identifier!
      id: "TgDZ0GvuqZkVlmdhm94f"
      items: {
        amazonCartItemsInput: [{
          quantity: 2
          productId: "B08CQDF382"
        }]
      }
    }
  ) {
    cart {
      id
      # `cost` omitted for brevity
      stores {
        ... on AmazonStore {
          cartLines {
            quantity
            product {
              id
              title
            }
          }
          errors {
            code
            message
          }
        }
      }
    }
    errors {
      code
      message
    }
  }
}

In addition to addCartItems, you may want to look at the documentation for the following API operations as well:

• deleteCartItems: Used for removing cart items from the cart.
• updateCartItems: Used for updating the quantity of cart items. For instance, to support the user adding a third unit of cleanser to their cart.

​

Congratulations!

You’ve created your first Rye cart, and have been able to add an additional product to the cart afterwards. Creating a cart is the first step towards placing an order.

Note that on the example response there is no shipping price available. This is because when we created our cart, we didn’t tell it where we we’d like to ship the cart items to. We can fix this by attaching a buyer identity to our cart, which we will do in the next section.