> ## Documentation Index
> Fetch the complete documentation index at: https://docs-test.rye.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sell Anything API

> In this tutorial, you'll understand how to use Rye's Sell Anything API to create a cart, add products to it, and submit it for checkout.

### Requirements

* You have created a [Rye Developer Account](https://console.rye.com/account).
* You have access to your API key [(Follow these steps if not)](https://docs-test.rye.com/docs/quick-start#1-grab-your-api-key).

***

### Let's begin!

**1. Initialize GQL client with your API key**

Use your API Key to initialize authorization headers for your GQL client.

```javascript theme={null}
import { GraphQLClient, gql } from 'graphql-request'

const endpoint = 'https://graphql.api.rye.com/v1/query'
const client = new GraphQLClient(endpoint)
const headers = {
  // Tip: You can get these from the Rye Console, under the "Account" tab.
  'Authorization': 'Basic <API Key Here>',
  'Rye-Shopper-IP': 'xxx.xxx.xxx.xxx',
}
```

**2. Add external product to Rye inventory**

Adding product data to inventory may take a few seconds, but the product ID will be returned immediately. You can then use this product ID to fetch product data in the next step.
You can also do this via the Rye Console, under the "Requests" tab.

```javascript theme={null}
async function requestProduct() {
  const variables = {
    "input": {
      "url": "https://www.amazon.com/Verity-Colleen-Hoover-ebook/dp/B09H6T8LTR"
    }
  };
  const query = gql`
    mutation RequestAmazonProductByURL(
      $input: RequestAmazonProductByURLInput!
    ) {
      requestAmazonProductByURL(input: $input) {
        productId
      }
    }
  `;
  const data = await client.request(query, variables, headers)
  console.log(JSON.stringify(data, undefined, 2))
}

await requestProduct();
```

**3. Fetch product data from Rye inventory**

The product ID can be found in the response to the [`requestAmazonProductByURL`](https://docs-test.rye.com/docs/api-reference/requestamazonproductbyurl) mutation's response.

```javascript theme={null}
async function fetchProduct() {
  const variables = {
    "input": {
      "id": "B09H6T8LTR",
      "marketplace": "AMAZON"
    }
  };

  const query = gql`
    query DemoAmazonProductFetch($input: ProductByIDInput!) {
      product: productByID(input: $input) {
        title
        vendor
        url
        isAvailable
        images {
          url
        }
        price {
          displayValue
        }
        ... on AmazonProduct {
          ASIN
        }
      }
    }
  `;

  const data = await client.request(query, variables, headers)
  console.log(JSON.stringify(data, undefined, 2))
}

await fetchProduct();
```

**4. Create a cart**

We can create a cart containing the Amazon product we just requested.

```javascript theme={null}
const CREATE_CART_QUERY = gql`
  mutation createCart($input: CartCreateInput!) {
    createCart(input: $input) {
      cart {
        id
        stores {
          ... on AmazonStore {
            store
            cartLines {
              quantity
              product {
                id
              }
            }
            offer {
              subtotal {
                value
                currency
                displayValue
              }
              margin {
                value
                currency
                displayValue
              }
              notAvailableIds
              shippingMethods {
                id
                label
                taxes {
                  value
                  currency
                  displayValue
                }
                price {
                  value
                  currency
                  displayValue
                }
                total {
                  value
                  currency
                  displayValue
                }
              }
            }
          }
        }
      }
      errors {
        code
        message
      }
    }
  }
`;

const createCartWithProducts = (product) => {
  const input = {
    items: {}
  };

  if (product.marketplace === 'AMAZON') {
    input.items.amazonCartItemsInput = [
      { productId: product.id, quantity: 1 },
    ];
  }

  if (product.marketplace === 'SHOPIFY') {
    input.items.shopifyCartItemsInput = [
      { variantId: product.id, quantity: 1 },
    ];
  }

  input.buyerIdentity = {
    city: 'city',
    countryCode: 'countryCode',
    provinceCode: 'provinceCode',
    postalCode: 'postalCode',
  };

  const response = await client.request(
    CREATE_CART_QUERY,
    variables,
    headers,
  );
  return response.data!.createCart.cart!;
}

const cart = await createCartWithProducts({
  id: 'B09H6T8LTR',
  marketplace: 'AMAZON',
})
```

**5. Use a fragment**

In the previous step our GraphQL document was extremely long. We can cut down on duplication by extracting our selected fields out as a reusable fragment, like so:

```javascript theme={null}
const CartFragment = gql`
  fragment CartFragment on Cart {
    id
    stores {
      ... on AmazonStore {
        store
        cartLines {
          quantity
          product {
            id
          }
        }
        offer {
          subtotal {
            value
            currency
            displayValue
          }
          margin {
            value
            currency
            displayValue
          }
          notAvailableIds
          shippingMethods {
            id
            label
            taxes {
              value
              currency
              displayValue
            }
            price {
              value
              currency
              displayValue
            }
            total {
              value
              currency
              displayValue
            }
          }
        }
      }
    }
  }
`;

// Use `CartFragment` to keep `CREATE_CART_QUERY` lean
const CREATE_CART_QUERY = gql`
  ${CartFragment}

  mutation createCart($input: CartCreateInput!) {
    createCart(input: $input) {
      cart {
        ...CartFragment
      }
      errors {
        code
        message
      }
    }
  }
`;

// ...
```

**6. Add more products to your cart**

Add more products to your cart with the product IDs and the cart ID of the desired cart, using the [`addCartItems`](https://docs-test.rye.com/docs/api-reference/addcartitems) mutation.

```javascript theme={null}
const ADD_CART_ITEMS_QUERY = gql`
  ${CartFragment}

  mutation addCartItems($input: CartItemsAddInput!) {
    cart {
      ...CartFragment
    }
    errors {
      code
      message
    }
  }
`;

const addProductsToCart = (cartId, product) => {
  const input = {
    id: cartId,
    items: {},
  };

  if (product.marketplace === 'AMAZON') {
    input.items.amazonCartItemsInput = [
      { productId: product.id, quantity: 1 },
    ];
  }

  if (product.marketplace === 'SHOPIFY') {
    input.items.shopifyCartItemsInput = [
      { variantId: product.id, quantity: 1 },
    ];
  }

  const variables = { input };

  await client.request(
    ADD_CART_ITEMS_QUERY,
    variables,
    headers,
  );
}

await addProductsToCart(
  // We returned the `cart` object from the `createCartWithProducts` function
  // in the previous step.
  cart.id,
  'B01ANEHLXG',
);
```

**7. Fetch cart shipping methods and cost**

Check if your cart looks good, and fetch the estimated checkout cost and available shipping methods for the cart.

```javascript theme={null}
const GET_CART_QUERY = gql`
  ${CartFragment}

  query cart($id: ID!) {
    getCart(id: $id) {
      ...CartFragment
    }
  }
`;

// Fetch latest cart
const updatedCart = await client.request(GET_CART_QUERY, { id: cart.id }, headers);

// Use `latestCart`
```

**8. Update buyer identity**

Update buyer identity information if it was not provided during cart creation as it is required to be able to submit the cart.

```javascript theme={null}
export const UPDATE_CART_BUYER_IDENTITY_QUERY = gql`
  ${CartFragment}

  mutation updateCartBuyerIdentity($input: CartBuyerIdentityUpdateInput!) {
    updateCartBuyerIdentity(input: $input) {
      cart {
        ...CartFragment
      }
      errors {
        code
        message
      }
    }
  }
`;

const input = {
  id: cartId,
  buyerIdentity: {
    city,
    address1,
    address2,
    firstName,
    lastName,
    email,
    phone,
    postalCode,
    provinceCode,
    countryCode,
  },
};

await client.request(
  UPDATE_CART_BUYER_IDENTITY_QUERY,
  { input },
  headers,
);
```

**9. Submit your cart**

```javascript theme={null}
const SUBMIT_CART_MUTATION = gql`
  mutation submitCart($input: SubmitCartInput!) {
    submitCart(input: $input) {
      cart {
        id
        stores {
          store
          isSubmitted
          orderId
          errors {
            code
            message
          }
        }
      }
      errors {
        code
        message
      }
    }
  }
`;

const submitCart = async (cartId) => {
  const input = {
    id: cartId,  // IMPORTANT! Make sure the cartId is valid
  };

  const variables = { input };

  const { submitCart: submitCartResult } = await client.request(
    SUBMIT_CART_MUTATION,
    variables,
    headers,
  );

  if (submitCartResult?.errors?.length) {
    throw new Error(
      `Cart submission failed: ${JSON.stringify(submitCartResult.errors)}`,
    );
  }

  return submitCartResult.cart;
};

// Example usage
const submittedCart = await submitCart("your-cart-id-here");
console.log("Submitted cart:", submittedCart);
```

**10. Display the results of the transaction**

```javascript theme={null}
const CHECKOUT_BY_CART_ID_QUERY = gql`
  query checkoutByCartID($cartID: ID!) {
    checkoutByCartID(cartID: $cartID) {
      cart {
        id
      }
      status
      orders {
        id
        status
      }
    }
  }
`;

const TERMINAL_STATUSES = [
  "SUCCEEDED",
  "FAILED",
  "CANCELLED",
  "PARTIALLY_SUCCEEDED",
  "MIXED",
];

const pollCheckoutStatus = async (cartID, intervalMs = 5000, timeoutMs = 60000) => {
  const start = Date.now();

  while (Date.now() - start < timeoutMs) {
    const variables = { cartID };

    try {
      const response = await client.request(CHECKOUT_BY_CART_ID_QUERY, variables, headers);
      const checkout = response.checkoutByCartID;

      if (!checkout) {
        throw new Error("No checkout data returned.");
      }

      console.log("Current checkout status:", checkout.status);

      if (TERMINAL_STATUSES.includes(checkout.status)) {
        return checkout;
      }
    } catch (err) {
      console.error("Error polling checkout:", err.message);
      throw err;
    }

    await new Promise((resolve) => setTimeout(resolve, intervalMs));
  }

  throw new Error("Polling timed out before checkout reached a terminal state.");
};

// Example usage
const cartID = "your-cart-id-here";

try {
  const checkout = await pollCheckoutStatus(cartID);
  console.log("Final checkout data:", checkout);
} catch (error) {
  console.error("Checkout polling failed:", error);
}
```

After submitting your cart, you can either poll the `checkoutByCartID` endpoint, or listen for Rye's order update webhooks. In some cases there may have been some errors during the submission of the cart, and these can be inspected on the `result` object.

Errors can occur on the Cart level and the Store level:

* For the cart level: `result.errors` will provide an array of errors related to submitting the cart with appropriate error messages and codes
* For the store level: `result.cart.stores[idx].errors` will provide an array of errors related to submitting the order to the store with appropriate error messages and codes

It is important to remember that **submitting a cart is an async operation**. It is possible for errors to occur *after* you have submitted the cart. Read more about checkout lifecycle [here](https://docs-test.rye.com/docs/payments-and-ordering/payment-flows).

**11. Cart management**

* To update the number of existing products in the cart, use the [`updateCartItems`](https://docs-test.rye.com/docs/api-reference/updatecartitems) mutation.
* To remove existing products from the cart, use the [`deleteCartItems`](https://docs-test.rye.com/docs/api-reference/deletecartitems) mutation.
* To remove the entire cart, use the [`removeCart`](https://docs-test.rye.com/docs/api-reference/removecart) mutation.

## Next steps

***

* We looked at [`requestAmazonProductByURL`](https://docs-test.rye.com/docs/api-reference/requestamazonproductbyurl) in this guide, but [`requestShopifyProductByURL`](https://docs-test.rye.com/docs/api-reference/requestshopifyproductbyurl) and [`requestStoreByURL`](https://docs-test.rye.com/docs/api-reference/requeststorebyurl) can also be used to add products to our product data catalog.
* Check out our "[starting an integration](https://docs-test.rye.com/docs/get-started/adding-products/overview)" guide to get started with building out your real API integration.
* Experiment with our API using one of the following playgrounds:
  * [Rye Console sandbox](https://console.rye.com/graphql)
  * [Postman workspace](https://www.postman.com/rye-team/workspace/rye/overview)
  > [!WARNING]
  >
  > Before you can make GraphQL requests, you will need to set the correct HTTP headers. Check out our [Authorization guide](https://docs-test.rye.com/docs/authorization-headers) for details.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.