CoursesB2B CoreModule 3: Company Management

Lab - Postman Company Management Workflow

Plan: B2B Developer

 Lesson 11 of 19 · 45 min

Introduction

In this lab, you’ll construct a Postman workflow to simulate the administration of companies, company addresses, and company users. This will include implementing automation to capture and re-use values from API responses.

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

In this lab, you will:

  • Create API requests to add and fetch companies, addresses, and users
  • Implement Postman scripts to automate values used in API requests

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: Create a Company

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

    It’s probably helpful to group the requests in your collection into folders, such as “Companies” for all company-related requests.

  2. Configure the request with the following details.

    FieldValue
    MethodPOST
    URLhttps://api-b2b.bigcommerce.com/api/v3/io/companies

  3. In the Headers tab, select the “B2B REST” preset from the Presets drop-down.

  4. In the Body tab, check “raw” and select “JSON” from the types drop-down.

  5. Enter the following request body. (Feel free to change the company/admin details.)

    {
        "companyName": "Jane's Widgets",
        "companyPhone": "111-222-3333",
        "companyEmail": "janedoe@example.com",
        "addressLine1": "987 Park Place",
        "city": "Austin",
        "state": "Texas",
        "country": "United States",
        "zipCode": "78726",
        "adminFirstName": "Jane",
        "adminLastName": "Doe",
        "adminEmail": "janedoe@example.com",
        "adminPhoneNumber": "222-333-4444",
        "channelIds": [{{storefront_channel_id}}]
    }

  6. In the Scripts tab, enter the following “Post-response” test 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 company = pm.response.json().data;
    pm.test('Response includes a company with ID', () => {
        pm.expect(
            company?.companyId
        ).to.be.a('number');
    });

    The test code above will run after the API response is received and will verify that the expected data is present, indicating that the company was successfully created.

  7. Send the request. You can observe the details in the Body tab of the response, as well as verify that all tests succeeded in the Test Results tab.

  8. Record the companyId value from the API response for use in the next requests.

In the B2B Edition section of your BigCommerce control panel, you should be able to observe your new company and its single Admin user. Note that the API-created company is automatically in the “Approved” status. If the email address you used did not match an existing customer record, you will also see that a one was automatically created in the Customers section of the control panel.

Step 2: Get Companies

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

  2. Configure the request with the following details.

    FieldValue
    MethodGET
    URLhttps://api-b2b.bigcommerce.com/api/v3/io/companies
    Headers”B2B REST” preset

  3. In the Scripts tab, enter the following “Post-response” test code, which will verify at least one company is returned.

    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 companies = pm.response.json().data;
    pm.test('Response includes at least one company', () => {
       pm.expect(
            companies
        ).to.be.a('array');
         pm.expect(
            companies?.length
        ).to.be.greaterThan(0);
    });

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

    You can record the ID of the company you created from this response if you didn’t already. Next, you’ll create a request for fetching the details of just this company.

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

  6. Configure the request with the following details.

    FieldValue
    MethodGET
    URLhttps://api-b2b.bigcommerce.com/api/v3/io/companies/:company_id
    Headers”B2B REST” preset

  7. In the Params tab, enter the ID of your newly created company as the value for the company_id Path Variable.

  8. In the Scripts tab, enter the following “Post-response” test 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 company = pm.response.json().data;
    pm.test('Response includes a company with ID', () => {
        pm.expect(
            company?.companyId
        ).to.be.a('number');
    });

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

Step 3: Add Automation

The previous step required that you manually record the ID of the company you created and enter it into the appropriate field of a subsequent request. This can get cumbersome in a manual API workflow, especially when the number of values you must track grows.

In a real software application, capturing and using these values would be automated, and we can do the same in Postman using scripts and variables.

  1. Open the “Create Company” request and add the following code after the previous code in the “Post-response” script.

    pm.collectionVariables.unset('company_id');
    pm.collectionVariables.set('company_id', company?.companyId);

    Now, when the “Create Company” request is run, the company_id collection variable will automatically be set with the ID value from the response.

    Collection variables are similar to environment variables and referenced in the same way. We’ve used an environment variable for connection information that would be common to any requests being sent to a specific environment, and we’re using collection variables for values relevant only to the workflow in this collection.

  2. Open the “Get Company” request and change the company_id value in the Params tab to value {{company_id}} (including the braces).

  3. Open the “Create Company” request, change the company/admin values in the Body tab to make sure the company name and email values don’t match existing entities, and send the request again.

  4. Select your collection and open the Variables tab.

  5. Verify that the collection variables include a value for company_id.

  6. Re-send the “Get Company” request.

Now that “Get Company” is automatically fetching the information for the most recent value of the company_id variable, you should observe the details of your most recently created company.

We’ll continue using this style of automation logic for subsequent requests.

For all collection variables, you can manually change the values if necessary in order to control the automation in your requests, without needing to change the request configuration itself. Select the collection, navigate to the Variables tab, and set the “Current value” for the variable. Don’t forget to save the collection.

Step 4: Update and Delete a Company

Next you’ll create a request for updating your existing company.

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

  2. Configure the request with the following details.

    FieldValue
    MethodPUT
    URLhttps://api-b2b.bigcommerce.com/api/v3/io/companies/:company_id
    Params”company_id” value: {{company_id}}
    Headers”B2B REST” preset
    Bodyraw / JSON

  3. In the Body tab, enter the following content.

    {
        "companyName": "Jane's Quality Widgets",
        "companyPhone": "444-555-6666",
        "addressLine1": "123 Park Central"
    }

  4. In the Scripts tab, enter the following “Post-response” test 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');
    });

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

    In the B2B Edition section of your control panel, you can observe the updated details of your company.

    Now let’s create a request to delete this company.

  6. Create andsave a new HTTP request called “Delete Company” with the following details.

    FieldValue
    MethodDELETE
    URLhttps://api-b2b.bigcommerce.com/api/v3/io/companies/:company_id
    Params”company_id” value: {{company_id}}
    Headers”B2B REST” preset

  7. In the Scripts tab, enter the following “Post-response” test 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');
    });
    pm.collectionVariables.unset('company_id');

    In addition to tests, this script also unsets the company_id collection variable now that the company no longer exists.

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

You can also verify in your control panel that the company has been deleted.

Step 5: Approve a Company

Next, we’ll explore using the REST API to manage company approval, practicing the filtering parameters of “Get Companies” in the process. Remember that the company you created with the API was automatically in “Approved” status so you’ll need an unapproved company before proceeding to the next API requests.

  1. If you don’t already have unapproved companies in your store, browse to your B2B-enabled storefront, make sure you are logged out, and register a new company account.

  2. Open the “Get Companies” request in Postman and add the following Query Param in the Params tab.

    Variable NameValue
    companyStatus0

    Note that this results in the query string ?companyStatus=0 being added to the URL.

  3. In the Scripts tab, add the following “post-response” code after the previous code.

    pm.collectionVariables.unset('pending_company_id');
    if (Array.isArray(companies)) {
        const pendingCompanies = companies.filter(company => company.companyStatus === 0);
        if (pendingCompanies.length > 0) {
            pm.collectionVariables.set('pending_company_id', pendingCompanies[0]?.companyId);
        }
    }

  4. Re-send the request, which should only return unapproved companies now, and verify that the pending_company_id variable now has a value in your collection’s Variables tab.

  5. Create and save a new HTTP request called “Approve Company” with the following details.

    FieldValue
    MethodPUT
    URLhttps://api-b2b.bigcommerce.com/api/v3/io/companies/:company_id/status
    Params”company_id” value: {{pending_company_id}}
    Headers”B2B REST” preset
    Bodyraw / JSON

  6. In the Body tab, enter the following content.

    {
        "companyStatus": 1
    }

  7. In the Scripts tab, enter the following “Post-response” test 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');
    });

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

You can now observe in your control panel that the identified company has been changed to “Approved.”

Try out additional “Query Params” in the Params tab of “Get Companies,” including limit, offset, sortBy, and orderBy. Test the effects of different values for these params.

Step 6: Create an Address

  1. Send the “Create Company” request again to create a new company and capture its company_id in the collection variable. Alternatively, you can simply select the ID of an existing company in the “Get Companies” response and manually set it as the current value of company_id in the collection’s Variables tab.

    After ensuring you have a valid current company_id, let’s add an address to this company.

  2. Create a new HTTP request and save it to your collection with the name “Create Address.”

  3. Configure the request with the following details.

    FieldValue
    MethodPOST
    URLhttps://api-b2b.bigcommerce.com/api/v3/io/addresses
    Headers”B2B REST” preset
    Bodyraw / JSON

  4. In the Body tab, enter the following content.

    {
        "addressLine1": "321 Park Place",
        "addressLine2": "Ste 3",
        "city": "Austin",
        "stateCode": "TX",
        "countryCode": "US",
        "zipCode": "78726",
        "firstName": "Jane",
        "lastName": "Doe",
        "isBilling": true,
        "isDefaultBilling": true,
        "isShipping": true,
        "isDefaultShipping": true,
        "phoneNumber": "888-777-6666",
        "companyId": {{company_id}},
        "label": "Main Address"
    }

    Make sure to include {{company_id}} exactly as it appears, including braces. This is a variable reference, exactly like when it was previously used in Path Variables.

  5. In the Scripts tab, enter the following “Post-response” test 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 address = pm.response.json().data;
    pm.test('Response included address with ID', () => {
        pm.expect(
            address?.addressId
        ).to.be.a('number');
    });
    pm.collectionVariables.unset('address_id');
    pm.collectionVariables.set('address_id', address?.addressId);

    This script both runs tests and captures the ID of the newly created address as an address_id collection variable.

  6. Send the request, verify that all tests succeed, and verify that the address_id variable was created on the collection.

In your control panel, you can observe the company’s newly created address, which should be set as both the default shipping and default billing address.

Step 7: Get Company Addresses

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

  2. Configure the request with the following details.

    FieldValue
    MethodGET
    URLhttps://api-b2b.bigcommerce.com/api/v3/io/addresses
    Headers”B2B REST” preset

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

    Variable NameValue
    companyId{{company_id}}

    With this filter param in place, your “Get Address Companies” request will return only addresses for the company you’re currently working with.

  4. In the Scripts tab, enter the following “Post-response” test 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 addresses = pm.response.json().data;
    pm.test('Response includes at least one address', () => {
        pm.expect(
            addresses
        ).to.be.a('array');
        pm.expect(
            addresses?.length
        ).to.be.greaterThan(0);
    });

  5. Send the request and verify that all tests succeed. You should observe that the results set includes the newly created address.

    Try adding other filtering Query Params to the “Get Company Addresses” request, including isBilling, isShipping, limit, offset, address, city, state, country, and/or zipCode.

    Lastly, let’s create a request to fetch individual details for the address you created.

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

  7. Configure the request with the following details.

    FieldValue
    MethodGET
    URLhttps://api-b2b.bigcommerce.com/api/v3/io/addresses/:address_id
    Params”address_id” value: {{address_id}}
    Headers”B2B REST” preset

  8. In the Scripts tab, enter the following “Post-response” test 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 address = pm.response.json().data;
    pm.test('Response included address with ID', () => {
        pm.expect(
            address?.addressId
        ).to.be.a('number');
    });

  9. Send the request and verify that all tests succeed. You should observe your newly created address in the response.

    Try out finishing your address workflow by creating similar requests for updating and deleting an address.

Step 8: Get Company Users

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

  2. Configure the request with the following details.

    FieldValue
    MethodGET
    URLhttps://api-b2b.bigcommerce.com/api/v3/io/users
    Headers”B2B REST” preset

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

    Variable NameValue
    companyId{{company_id}}

    As you did with “Get Company Addresses,” here you’re filtering the users request on a single company.

    Try adding other filtering Query Params to the “Get Company Users” request, including limit, offset, and roles.

  4. In the Scripts tab, enter the following “Post-response” test 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 users = pm.response.json().data;
    pm.test('Response contains at least one user', () => {
        pm.expect(
            users
        ).to.be.a('array');
        pm.expect(
            users?.length
        ).to.be.greaterThan(0);
    });

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

You should have at least one user assigned to this company already: the Admin user that was specified when the company was first created.

Step 9: Create a Junior Buyer

Let’s create a new user for the company with the Junior Buyer role.

Junior Buyer is one of the pre-built roles that is assigned a hard-coded role ID (0). While you could create your Junior Buyer user using role: 0, a more forward compatible approach is to use companyRoleId. This approach will also support any custom roles you may create.

In order to specify companyRoleId, you’ll first need to fetch the available company roles and find the record ID for “Junior Buyer.”

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

  2. Configure the request with the following details.

    FieldValue
    MethodGET
    URLhttps://api-b2b.bigcommerce.com/api/v3/io/companies/roles
    Headers”B2B REST” preset

  3. In the Scripts tab, enter the following “Post-response” test 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 roles = pm.response.json().data;
    pm.test('Response includes array of roles', () => {
        pm.expect(
            roles
        ).to.be.a('array');
        pm.expect(
            roles?.length
        ).to.be.greaterThan(0);
    });
    pm.collectionVariables.unset('junior_role_id');
    if (Array.isArray(roles)) {
        const juniorRole = roles.find(role => role?.name === 'Junior Buyer');
        pm.test('Junior role found', () => {
            pm.expect(
                juniorRole?.id
            ).to.be.a('number');
        });
        pm.collectionVariables.set('junior_role_id', parseInt(juniorRole?.id));
    }

    In addition to tests, this script captures the ID of the role that has the exact name “Junior Buyer” in a collection variable called junior_role_id.

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

    You should observe at least the Admin, Senior Buyer, and Junior Buyer roles in the response. If you have created any custom roles in your control panel, these should be present as well. Verify that an ID was set for junior_role_id in your collection variables.

    With this role ID captured, you’re ready to create the user.

  5. Create a new HTTP request and save it to your collection with the name “Create Junior Buyer User.”

  6. Configure the request with the following details.

    FieldValue
    MethodPOST
    URLhttps://api-b2b.bigcommerce.com/api/v3/io/users
    Headers”B2B REST” preset
    Bodyraw / JSON

  7. In the Body tab, enter the following content.

    {
        "companyId": {{company_id}},
        "email": "jilldoe@example.com",
        "firstName": "Jill",
        "lastName": "Doe",
        "phoneNumber": "444-777-9999",
        "companyRoleId": {{junior_role_id}},
        "channelIds": [{{storefront_channel_id}}]
    }

  8. In the Scripts tab, enter the following “Post-response” test 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 user = pm.response.json().data;
    pm.test('Response contains user with ID', () => {
        pm.expect(
            user?.userId
        ).to.be.a('number');
    });
    pm.collectionVariables.unset('user_id');
    pm.collectionVariables.set('user_id', user?.userId);

    This script captures the ID of the most recently created user in the collection variable user_id, for use in the next request.

  9. Send the request, verify that all tests succeed, and verify that the user_id variable exists on your collection.

  10. Re-send the “Get Company Users” request and verify that your new user now appears in the response.

Step 10: Get Individual User

Your final step will be to craft a request to fetch the most recently created user, utilizing the user id_collection variable that was auto-populated previously.

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

  2. Configure the request with the following details.

    FieldValue
    MethodGET
    URLhttps://api-b2b.bigcommerce.com/api/v3/io/users/:user_id
    Params”user_id” value: {{user_id}}
    Headers”B2B REST” preset

  3. In the Scripts tab, enter the following “Post-response” test 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 user = pm.response.json().data;
    pm.test('Response includes user with ID', () => {
        pm.expect(
            user?.id
        ).to.be.a('number');
    });

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

Try out finishing your user workflow by creating similar requests for updating and deleting a user. Also, consider trying fetching a user by customer ID instead of user ID.

Resources