Live Pricing for Suppliers

Live Pricing allows the builder to get access to up-to-the-minute pricing for your catalog, including any discounts and promotions that they are entitled to.

Discuss your implementation options with your Buildxact Enterprise Account Manager, as we may be able to provide recommendations on a partner to assist with implementation if required.

In order to provide Live Pricing for your catalogs in Buildxact, your system needs to implement some API endpoints with the following URLs and schemas.

NOTE: Live Pricing still requires you to upload a catalog, which the builder can search through to find items. You must publish a catalog first, which contains a list of all the items that the user can pick from, before the user is able to make a Live Pricing request. See the Price File Integration page for more information.

Where you see https://supplier-api-base-urlin the text below, this will be replaced by a base URL on your system, that you will need to provide to your Buildxact Account Manager once the implementation is ready (we prefer both a Staging, and Production, version of this URL to assist with testing).

There is a set of four endpoints that you must implement, detailed below:

  1. Authentication (OAuth2 token endpoint)

  2. Get nearest stores to a given location (used by Buildxact to allow the user to search for a store near their location)

  3. Get store information by ID (used by Buildxact to fetch information on an already-selected store)

  4. Request pricing (used by Buildxact to find out the current live pricing for a set of items)

OAuth 2 token endpoint

The first thing the Buildxact system will do is request an OAuth Bearer Access Token. To achieve this, you need to provide an endpoint that implements the OAuth Client Credential Flow.

Overview

  • Endpoint: POST https://supplier-api-base-url/connect/token

  • Description: This API allows clients to obtain a new authentication token using the client_credentials grant type.

 

Request parameters

The following request parameters and values must be supplied when making a call to the OAuth endpoint to retrieve a token.

cUrl Example

Sample Token Response

Your system MUST provide the following three fields in the response. expires_in tells us the number of seconds that the access token is valid for.

Error Responses

  • 400 Bad Request: If the request is malformed or missing required parameters.

    • Example:

  • 401 Unauthorized: If the client_id or client_secret is invalid.

    • Example:

500 Internal Server Error: If there is an issue on the server side.

Get Store List endpoint

Retrieves nearest stores by latitude, longitude and diameter in kilometres.

Overview

  • Endpoint: GET https://supplier-api-base-url/stores/nearest

  • Description: This API allows Buildxact to obtain a list of the nearest stores by providing latitude, longitude, and a radius in kilometres.

Request parameters

The following parameters will be provided by Buildxact when making the request:

cUrl Example

Response

Array of stores.

  • Schema:

  • Store Schema

  • TradingHours Schema

  • DailyTradingHours Schema

  • OpeningHours Schema

  • PublicHoliday Schema

Sample Response

Notes:

  • Return an empty list of stores if there are no stores within the search range.

Get a store by Id

Retrieves store information by store ID value

Overview

  • Endpoint: GET https://supplier-api-base-url/stores/{id}

  • Description: This endpoint retrieves the details of a specific store by its unique identifier.

Path parameters

cUrl Example

Response

Store object.

  • Schema:

Sample Response

Error Responses:

  • 404 Not Found: If the store with the specified ID does not exist.

Get Pricing

  • Retrieves the price for the requested items

    Overview

    • Endpoint: POST https://supplier-api-base-url/request-prices

    • Description: This API endpoint allows clients to obtain special pricing for items by providing the optional member number and a list of items with their respective store ID and quantities.

Request body schema

PriceItemRequest schema:

cUrl Example

Response:

  • Array of price items.
    Schema

  • Price item Schema:

Note: When there is an error, the unitPrice, discount and totalPrice field could be null.

The following list represents possible error codes returned when live pricing information cannot be retrieved. The defined error codes and their descriptions are as follows:

Sample Response

In the following response sample:

The unit price of item '1230123' is $25.54 before tax. The quantity of this item in the checkout is 10, and the discount on these 10 items is $12.77, making the final total price $25.54 * 10 - $12.77 = $242.63.

The item '1230456' is not in range at the specified store (store ID provided in the request), so the response includes an error code and error message.