REST API - Shopping Lists and Quotes

Shopping Lists

The following API endpoints allow you to view and manage shopping lists.

GET Shopping Lists

This query will return all shopping lists that are viewable based on the user permissions of the specified user ID. If the user is a junior buyer, the list will only contain the shopping lists that the specified user has created. If the user is a senior buyer or admin user, the list will contain all the company’s approved shopping lists and shopping lists that are ready for approval.

You can query based on the following parameters:

• channelId
• customerId - a BigCommerce customer ID
• userId - a B2B Edition buyer user ID

Example Request:

GET https://api-b2b.bigcommerce.com/api/v3/io/shopping-list?userId={userId}

If you need to see the data from a specific shopping list, use the following request URL and include the shoppingListId.

Example Request:

GET https://api-b2b.bigcommerce.com/api/v3/io/shopping-list/{shoppingListId}

Create a Shopping List

The following request URL will create a shopping list for a user (specified as a parameter, or in the request body).

Example Request:

POST https://api-b2b.bigcommerce.com/api/v3/io/shopping-list

Required fields for the request body include:

• name - the name of the shopping list
• userId (B2B Edition users) or customerId (BigCommerce users) - if not added as a query param, one of these must be in the request body
• status - 0: approved, 20: deleted, 30: draft, 40: ready for approval
• items - an array of product information
• productId
• variantId - if the product has options, variant ID is required, otherwise it can be left blank
• quantity

Example Body:

{
  "name": "my first shopping list",
  "userId": 0,
  "status": 0,
  "items": [
    {
      "productId": 123,
      "variantId": 321,
      "quantity": 5
    },
        {
      "productId": 123,
      "variantId": 321,
      "quantity": 5
    },
        {
      "productId": 123,
      "variantId": 321,
      "quantity": 5
    }
  ]
}

The response will return a “success” message and the shoppingListId for the newly created shopping list.

Update a Shopping List

This API request can be used to update a shopping list detail and items. The user ID is not required for this type of request, but can be passed in if needed. Both userId for B2B accounts and customerId for B2C accounts are supported. By sending them, it will validate that the user is allowed to update the shopping list.

Example Request:

PUT https://api-b2b.bigcommerce.com/api/v3/io/shopping-list/{shoppingListId}

The example request body below will update the name, status, and product quantities of the shopping list created in the previous example. Notice that you will need to include the shoppingListId in the request URL. See the Update a Shopping List API reference for a full list of fields that can be updated with this request.

Example Body:

{
  "name": "test",
  "description": "my first shopping list",
  "status": 40,
  "items": [
    {
      "id": 75693,
      "productId": 123,
      "variantId": 321,
      "quantity": 0
    },
    {
      "id": 85416,
      "productId": 123,
      "variantId": 321,
      "quantity": 5
    },
    {
      "id": 76533,
      "productId": 123,
      "variantId": 321,
      "quantity": 1
    }
  ]
}

The id field refers to a unique shopping list item. If no item id is passed but productId and variantId are, the item to update will be determined from those fields and the quantity will be updated. If the id field is not null, it will determine the actual item and you can change the productId andvariantIdfields.

Notice that one of the quantities in the above example was changed to 0. A zero quantity of a shopping list item will delete the item from the shopping list.

The response will return a confirmation of the shopping list identifier information like id, name, companyId, userId, etc.

Quotes

The following endpoints allow you to manage requests for quotes. These operations do not include or affect draft quotes that a company has started, only the ones that the company has submitted.

Get a List of Requests for Quotes (RFQs)

Use the endpoint below to get a list of all RFQs available for your store. Note that archived quotes will not be returned in the response.

Example Request:

GET https://api.bundleb2b.net/api/v3/io/rfq

You can filter the list of RFQs based on many parameters. See the Get a RFQ API reference for a full list of parameters. Some notable parameters are:

• company - the name of the company, not the companyId
• status - status of the quote, 0: New, 2: In Process, 3: Updated by customer, 4: Ordered

Create a RFQ

Every quote must have a RFQ. This form includes all of the quote details discussed with the customer.

Example Request:

POST  https://api.bundleb2b.net/api/v3/io/rfq

Required fields include:

• grandTotal - total price after discount
• discount
• totalAmount - total price after discount
• subtotal - total price
• userEmail - email that belongs to the sales rep
• expiredAt - expiration date must be in ‘%m/%D/%y’ format
• shippingAddress
• contactInfo
• productList - required product fields include sku, basePrice, discount, offeredPrice, quantity, and productId

The example request body below shows all of the required fields plus some others. See the Create a RFQ API reference for a list of all the possible fields.

Example Body:

{
  "grandTotal": 0,
  "discount": 0,
  "totalAmount": 0,
  "subtotal": 0,
  "userEmail": "string",
  "quoteTitle": "string",
  "expiredAt": "string",
  "shippingAddress": {
    "country": "string",
    "state": "string",
    "city": "string",
    "zipCode": "string",
    "address": "string",
    "apartment": "string"
  },
  "contactInfo": {
    "name": "string",
    "email": "string"
  },
  "productList": [
    {
      "sku": "string",
      "basePrice": 0,
      "discount": 0,
      "offeredPrice": 0,
      "quantity": 0,
      "productId": 0,
      "variantId": 0,
      "imageUrl": "string",
      "orderQuantityMaximum": 0,
      "orderQuantityMinimum": 0,
      "productName": "string",
      "options": [
        {
          "optionId": 0,
          "optionValue": 0,
          "optionLabel": "string",
          "optionName": "string"
        }
      ]
    }
  ]
}

Update a Quote

Use the endpoint below to update a quote’s details. Note that there is no way to assign or change the sales rep attached to the quote.

Example Request:

PUT  https://api.bundleb2b.net/api/v3/io/rfq/{quote_id}

The request body should include the information that you want to update on the quote form. To see a full list of fields you can update, see the Update a Quote API reference.

Create a Checkout Quote Form

Use the endpoint below when it is necessary to send a direct link to a checkout page or cart page. This operation is the same as the “create checkout redirect URL” operation for a cart in BigCommerce.

Example Request:

POST   https://api-b2b.bigcommerce.com/api/v3/io/rfq/{quote_id}/checkout

The response will include a link to the checkout page already populated with the quote items and prices that were agreed upon.

Send a Quote Email

Use the endpoint below to send an email that contains quote information.

Example Request:

POST   https://api-b2b.bigcommerce.com/api/v3/io/rfq/emails

The request body must contain the following fields:

• quoteId
• email - where you want to send the quote email
• withAttach - specify whether you want to send the quote PDF as an attachment with the email
• emailTemplate - specify what email template to use: Simple, Simple with Pictures, Waves with Pictures, Sky, or Dots

Example Body:

{
  "quoteId": "string",
  "email": "string",
  "withAttach": 0,
  "emailTemplate": "Simple",
  "ccTo": [
    "string"
  ],
  "emailLang": "en"
}

Export a Quote as a PDF

Use the endpoint below to create a downloadable PDF that contains quote details. The response will include a link, which will download a PDF when clicked.

Example Request:

POST  https://api-b2b.bigcommerce.com/api/v3/io/rfq/{quote_id}/pdf-export

In the request body, you can specify the currency and currencyExchangeRate if needed.

Example Body:

{
  "currency": {
    "currencyExchangeRate": "string"
  }
}

Resources

• Shopping Lists
• Quotes