Lab - Postman Quote and Order Workflow

Plan: B2B Developer

Lesson 15 of 19 · 45 min

Introduction

In this lab, you’ll construct a Postman workflow to simulate some of the common quote and order tasks a back-end integration might be concerned with.

Prerequisites

• A BigCommerce sandbox store or trial store, or a full production store
• B2B Edition enabled in your store
• Postman or a similar API client
• An existing Postman environment, collection, and headers preset as configured in previous labs
• An existing company and Admin or Senior Buyer user login
• Minimal quote/payment/shipping settings as described below

In this lab, you will:

• Create API requests to inspect and manage quotes and orders
• Implement Postman scripts to automate values used in API requests

Configure Shipping and Payments

In order to complete checkout, you’ll need to make sure you have the appropriate minimal store configuration in place for shipping and payments.

If you’ve previously configured shipping and payment options for your store, you won’t need to do any additional setup.

We won’t walk through the details of configuring your store settings, but make sure you have:

• A Shipping Zone that applies to any billing address you will use at checkout
• An enabled Shipping Method on the Shipping Zone
• An enabled test/sandbox Payment Method. (Check the “Enable test credit card payments” option in your Payments Methods settings for the simplest option.) This will be necessary once we get to paying invoices.
• The “Check” payment method enabled

Required B2B Quote/Payment Settings

The lab will involve logging in as a company user, creating, and submitting a quote-based order. The following minimal settings are required in the B2B Edition section of your control panel:

• In Settings > General, “Quotes” must be checked under “Feature Management.”
• In Settings > Quotes, “Allow Quote Request for” should have “Company user” checked, and “Enable add to quote button” should be checked.
• In Settings > Checkout, the “Purchase Order Payment Method” should be enabled.
• The Payments settings for the company you will use for the storefront must not have been customized to exclude “PO” as an available payment option.

Postman Recap

As a reminder, your work in previous labs should have resulted in the following Postman configuration, which will be important for the following exercise steps:

• An environment with variables set for v3_token, store_hash, and storefront_channel_id
• A B2B Edition REST collection
• A “B2B REST” headers preset with values for Accept, Content-Type, and authToken

Step 1: Submit a Quote Request

For the steps ahead, you’ll need the ability to log into your storefront with the credentials for an Admin user associated with a company.

If the only company users you have in your store so far are those you created via the API in previous labs, then these customers do not yet have a password set. (Typically, a password would be set by the customer after receiving a welcome email.) If this is the case, set a password in the control panel:

1. In the BigCommerce control panel, navigate to Customers and then to the customer associated with the email address of your company’s Admin user.

2. Set a password for the customer and save.

   You’ll also need to have quote requests submitted within the past 7 days. If your store doesn’t contain any such quote requests, submit a request now from your storefront:

3. Browse to your storefront URL and log in with the credentials of a company user.

4. Navigate to a product page and use the “Add to quote” button to add the product to your request.

5. Use the “Open Quote” link in the success message, or browse to Account > Quotes and select the draft quote.

6. Submit the quote.

Step 2: Get Recent Requests for Quote

In this step, you’ll create requests to fetch all requests for quote from within the last 7 days, as well as fetch the details of a specific quote.

1. Create a new HTTP request and save it to your collection with the name “Get Recent RFQs.”

2. Configure the request with the following details.

   Field	Value
   Method	GET
   URL	https://api-b2b.bigcommerce.com/api/v3/io/rfq
   Headers	”B2B REST” preset

3. In the Params tab, add the following Query Params.

   Variable Name	Value
   minCreated	{{quote_min_created_at}}
   status	0

   Make sure to include {{quote_ min_created_at}} exactly as it appears, including the braces. You may note that this references a variable that has not been created yet on the environment or collection. In this case, you’ll be creating a Pre-request script that will generate an appropriate “7 days ago” timestamp each time the request is run. The status filter param also ensures that only quote requests that are newly created and have not yet been acted on by a sales rep.

   Try out the effects of other filter params as well, including company, limit, offset, maxCreated, minExpired and maxExpired, minModified and maxModified, sortBy, orderBy, and quoteNumber.

4. In the Scripts tab, enter the following “Pre-request” code (not “Post-response” as usual).

   const days = 7;
   const d = new Date();
   d.setSeconds(d.getSeconds() - (days * 24 * 60 * 60));
   pm.collectionVariables.unset('quote_min_created_at');
   pm.collectionVariables.set('quote_min_created_at', Math.round(d.valueOf() / 1000));

   This script calculates a timestamp for 7 days before the current time and sets the quote_min_created_at variable you’ve already referenced in the request’s filters. Feel free to set a different number of days.

5. In the Scripts tab, enter the following “Post-response” code.

   pm.test('Response is not an error', () => {
       pm.response.to.not.be.error;
       pm.response.to.not.have.jsonBody("errors");
   });
   pm.test('Response is JSON with data', () => {
       pm.response.to.have.jsonBody("data");
   });
   const quotes = pm.response.json().data;
   pm.test('Response contains at least one quote', () => {
       pm.expect(
           quotes
       ).to.be.a('array');
       pm.expect(
           quotes?.length
       ).to.be.greaterThan(0);
   });
   pm.collectionVariables.unset('quote_id');
   if (Array.isArray(quotes) && quotes.length > 0) {
       pm.collectionVariables.set('quote_id', quotes[0].quoteId);
   }

   Note that in addition to tests, this script captures the ID of the first quote in the results set in the collection variable quote_id. This will be used to automatically set the context of subsequent requests.

6. Send the requests, verify that all tests succeed, and verify that the quote_id variable has been set on the collection.

   Next, you’ll create a request for the details of the first quote in the previous results set. (Alternatively, you can edit the quote_id variable directly on your collection to specify a different quote ID.)

7. Create a new HTTP request and save it to your collection with the name “Get Quote Details.”

8. Configure the request with the following details.

   Field	Value
   Method	GET
   URL	https://api-b2b.bigcommerce.com/api/v3/io/rfq/:quote_id
   Params	”quote_id” value: {{quote_id}}
   Headers	”B2B REST” preset

9. In the Scripts tab, enter the following “Post-response” code.

   pm.test('Response is not an error', () => {
       pm.response.to.not.be.error;
       pm.response.to.not.have.jsonBody("errors");
   });
   pm.test('Response is JSON with data', () => {
       pm.response.to.have.jsonBody("data");
   });
   const quote = pm.response.json().data;
   pm.test('Response includes quote with number', () => {
       pm.expect(
           quote?.quoteNumber
       ).to.be.a('string');
   });

10. Send the request and verify that all tests succeed.

At this step, you may choose to log into your BigCommerce control panel and edit the chosen quote in the B2B Edition admin - for example, to set a discount on one or more items in the quote. (Be sure to “Preview” and then “Submit” the quote.) A typical workflow would involve a sales rep making such edits before integration steps like the requests you’ll create next.

Try re-running the previous two requests to see the impact of edits to the data in the response. (Remember that the status filter on “Get Recent RFQs” must be removed to fetch a quote that has now been edited.)

Step 3: Export a Quote PDF

1. Create a new HTTP request and save it to your collection with the name “Export Quote PDF.”

2. Configure the request with the following details.

   Field	Value
   Method	POST
   URL	https://api-b2b.bigcommerce.com/api/v3/io/rfq/:quote_id/pdf-export
   Params	”quote_id” value: {{quote_id}}
   Headers	”B2B REST” preset

3. In the Scripts tab, enter the following “Post-response” code.

   pm.test('Response is not an error', () => {
       pm.response.to.not.be.error;
       pm.response.to.not.have.jsonBody("errors");
   });
   pm.test('Response is JSON with data', () => {
       pm.response.to.have.jsonBody("data");
   });
   const message = pm.response.json().meta?.message;
   pm.test('Operation was successful', () => {
       pm.expect(
           message
       ).to.be.eq('SUCCESS');
   });
   const pdfUrl = pm.response.json().data?.url;
   pm.test('Response included quote URL', () => {
       pm.expect(
           pdfUrl
       ).to.be.a('string');
   });

4. Send the request and verify that all tests succeed.

5. Copy the URL value from the response and enter it in a browser to verify that the URL results in downloading a PDF with the details of the quote.

Step 4: Generate a Quote Checkout URL

In this step, you’ll use an API request to generate a URL that will create a BigCommerce checkout from the chosen quote. While company users have the ability to check out with a quote from the front-end Buyer Portal at any time, this request would be useful for an integration in which you might be using a different communication channel to notify users with a quick checkout option.

1. Create a new HTTP request and save it to your collection with the name “Get Quote Checkout.”

2. Configure the request with the following details.

   Field	Value
   Method	POST
   URL	https://api-b2b.bigcommerce.com/api/v3/io/rfq/:quote_id/checkout
   Params	”quote_id” value: {{quote_id}}
   Headers	”B2B REST” preset

3. In the Scripts tab, enter the following “Post-response” code.

   pm.test('Response is not an error', () => {
       pm.response.to.not.be.error;
       pm.response.to.not.have.jsonBody("errors");
   });
   pm.test('Response is JSON with data', () => {
       pm.response.to.have.jsonBody("data");
   });
   const message = pm.response.json().meta?.message;
   pm.test('Operation was successful', () => {
       pm.expect(
           message
       ).to.be.eq('SUCCESS');
   });
   const checkoutUrl = pm.response.json().data?.checkoutUrl;
   pm.test('Response includes checkout URL', () => {
       pm.expect(
           checkoutUrl
       ).to.be.a('string');
   });

4. Send the request and verify that all tests succeed.

5. Log in to your storefront as a Senior Buyer or Admin user with the company associated with the quote.

6. Copy the URL from the response and enter it in a browser to verify that the checkout is initiated.

7. Complete the checkout and place an order from the quote, using the Purchase Order payment method.

The invoice workflow you’ll examine in the next lab is usually relevant for orders that have been paid with credit, so using the Purchase Order payment method will make sure you have an order that makes sense for that workflow.

Step 5: Get Recent Orders

Now that an order has been placed from your previous quote, let’s practice fetching orders data. You’ll start with an example of fetching all orders placed within the last 7 days, similar to the previous quotes example.

1. Create a new HTTP request and save it to your collection with the name “Get Recent Orders.”

2. Configure the request with the following details.

   Field	Value
   Method	GET
   URL	https://api-b2b.bigcommerce.com/api/v3/io/orders
   Headers	”B2B REST” preset

3. In the Params tab, add the following Query Param.

   Variable Name	Value
   minCreated	{{order_min_created_at}}

   Try out the effects of other filter params as well, including bcOrderId, companyId, limit, offset, maxCreated, minModified and maxModified, sortBy, and orderBy.

4. In the Scripts tab, enter the following “Pre-request” code.

   const days = 7;
   const d = new Date();
   d.setSeconds(d.getSeconds() - (days * 24 * 60 * 60));
   pm.collectionVariables.unset('order_min_created_at');
   pm.collectionVariables.set('order_min_created_at', Math.round(d.valueOf() / 1000));

5. In the Scripts tab, enter the following “Post-response” code.

   pm.test('Response is not an error', () => {
       pm.response.to.not.be.error;
       pm.response.to.not.have.jsonBody("errors");
   });
   pm.test('Response is JSON with data', () => {
       pm.response.to.have.jsonBody("data");
   });
   const orders = pm.response.json().data;
   pm.test('Response contains at least one order', () => {
       pm.expect(
           orders
       ).to.be.a('array');
       pm.expect(
           orders?.length
       ).to.be.greaterThan(0);
   });
   pm.collectionVariables.unset('order_id');
   pm.collectionVariables.unset('bc_order_id');
   if (Array.isArray(orders) && orders.length > 0) {
       pm.collectionVariables.set('order_id', orders[0].id);
       pm.collectionVariables.set('bc_order_id', orders[0].bcOrderId);
   }

   You can see that, just like with quotes, this script is capturing the first order in the results. In this case, you’ll eventually need both the B2B record ID and the BigCommerce order ID for different requests.

6. Send the request and verify that all tests succeed.

Step 6: Get Order Details

Next, you’ll create a pair of requests to fetch the details of a single order.

1. Create a new HTTP request and save it to your collection with the name “Get Order.”

2. Configure the request with the following details.

   Field	Value
   Method	GET
   URL	https://api-b2b.bigcommerce.com/api/v3/io/orders/:bc_order_id
   Params	”bc_order_id” value: {{bc_order_id}}
   Headers	”B2B REST” preset

3. In the Scripts tab, enter the following “Post-response” code.

   pm.test('Response is not an error', () => {
       pm.response.to.not.be.error;
       pm.response.to.not.have.jsonBody("errors");
   });
   pm.test('Response is JSON with data', () => {
       pm.response.to.have.jsonBody("data");
   });
   const order = pm.response.json().data;
   pm.test('Response contained an order with ID', () => {
       pm.expect(
           order?.id
       ).to.be.a('number');
   });

4. Send the request and verify that all tests succeed. The next request will get the order’s item details.

5. Create a new HTTP request and save it to your collection with the name “Get Order Products.”

6. Configure the request with the following details.

   Field	Value
   Method	GET
   URL	https://api-b2b.bigcommerce.com/api/v3/io/orders/:bc_order_id/products
   Params	”bc_order_id” value: {{bc_order_id}}
   Headers	”B2B REST” preset

7. In the Scripts tab, enter the following “Post-response” code.

   pm.test('Response is not an error', () => {
       pm.response.to.not.be.error;
       pm.response.to.not.have.jsonBody("errors");
   });
   pm.test('Response is JSON with data', () => {
       pm.response.to.have.jsonBody("data");
   });
   const items = pm.response.json().data;
   pm.test('Response contains at least one item with ID', () => {
       pm.expect(
           items
       ).to.be.a('array');
       pm.expect(
           items?.length
       ).to.be.greaterThan(0);
       const firstItem = Array.isArray(items) ? items[0] : null;
       pm.expect(
           firstItem?.id
       ).to.be.a('number');
   });

8. Send the request and verify that all tests succeed.

Resources

• Quote Management
• Order Management