Price File (Catalog) integration for Suppliers

This page is intended for you if you are a supplier partner who is looking to automate the process of providing your price files to Buildxact builders.

Buildxact refers to price files as Catalogs. A "Catalog" is a set of prices which can be provided to one or more builders.

Buildxact supports the following types of catalogs:

  • Public (national or regional) catalogs

  • Private catalogs (specific to a particular builder or group of builders)

Typically, catalogs contain RRP pricing of items, which would be the highest price that the item is generally on sale for.

If you want to provide builder-specific pricing to include any discounts that the specific builder is entitled to, we recommend using our Live Pricing feature.

The Buildxact APIs offer a push-based mechanism for managing your catalogs. That is, you can call our API to create a new catalog, to upload prices, and to amend prices. The typical scenario would be for you to update the catalog with RRP prices on a monthly or quarterly basis, and use Live Pricing to provide real-time builder-specific pricing.

Fictional Supplier - ACME Trade Supplies

For the purposes of this article, we will refer to a fictional supplier called "ACME Trade Supplies". We will use this to demonstrate examples of how a supplier might integrate with Buildxact; all such examples should be reviewed depending on your business requirements.

Catalog types - Public, Managed and the ExternalRef

When creating a catalog, you specify whether the catalog should have a Scope of Public or Managed.

A public catalog is always visible to all builders who connect with you.

A managed catalog is only visible to builder(s) that you specify.

With managed catalogs, visibility is controlled via the ExternalRef field. This contains the builder's identifier with you, and is an alphanumeric string of up to 255 characters. Our fictional supplier, "ACME Trade Supplies" runs a "Power Pro" membership scheme where builders who are members can get 10% off all products. In this case, the ExternalRef would be the builder's "Power Pro Identifier" from their Power Pro ID card.

Access to managed catalogs can be granted using the POST /catalogues/{catalogueId}/accesscontrols endpoint. A single catalog can have as many Access Control entries as you like, so you can grant many builders access to the same catalog if you wish. ACME Trade Supplies does this to grant all of their "Power Pro" builders access to their main "Power Pro Pricing Catalog". But alternatively, ACME could choose to create a specific catalog for each builder, if they wanted to provide custom pricing for each builder.

Access Control can be set before or after that builder makes a connection request to you. If the Access Control is set up before the builder connects, and you specify isPreApproved = true, then any incoming connection request from a builder with that ExternalRef will be automatically approved.

Example - daily publish of public state-based pricing

In the diagram below, our fictional supplier ("ACME Trade Supplies") operates in five states, and decides to publish a catalog for each state, with prices updating daily. The catalogs are public and can be accessed by any interested builder.

In order to achieve this, ACME Trade Supplies builds an automated process into their systems which runs on a daily basis. It gathers the pricing information from various internal APIs, and produces data for five catalogs that can be uploaded to Buildxact.

It then calls the Buildxact Catalog APIs for each catalog to do the following:

  1. If the catalog does not yet exist in Buildxact, call POST /catalogues to create it

  2. Call the POST /catalogues/{catalogueId}/import/start endpoint (providing a unique batch ID) to start an import job

  3. Call the POST /catalogues/{catalogueId}/import/{batchId}/items endpoint, in batches of 1000 items, to upload/update the price file items into the catalog

  4. Poll the GET /catalogues/{catalogueId}/import/{batchId} endpoint to wait for the import to complete.

Reviewing and Approving builder connection requests

When a builder wants to access your catalogs, they submit a Connection Request to your supplier using Buildxact.

In order to determine if you have any connection requests pending from builders, you can either:

  • poll the GET /catalogues/incomingIntegrationConnections endpoint

  • register a webhook for the integration-connection.requested event in the Business Setup -> API -> Webhooks screen

The process is as follows:

  1. ACME Trade Supplies creates an automated system which periodically calls the GET /catalogues/incomingIntegrationConnections endpoint to check if any builder connection requests have been made (alternatively, they could register a webhook to be notified of new requests)

  2. If connection requests are pending, the details of those builders requesting access will be returned from the endpoint. This data allows you to verify the builder details and determine if you wish to grant them access to your catalogs, or which of your catalogs they should be able to access. The ExternalRef field described earlier often assists with builder verification.

  3. Once ACME Trade Supplies has determined whether to approve or reject the builder's connection request (this could be an automated or manual process at ACME), call the POST /catalogues/incomingIntegrationConnections/accept[?integrationConnectionId]endpoint to accept the connection (or the "reject" endpoint to reject it).

  4. If the connection is accepted, then next ACME can choose which of their catalogs to grant the builder access to.
    This step is only required if the catalog was created as a "Managed" catalog. Managed catalogs are only visible to builders who have been explicitly granted access to them. This step is not required for "Public" catalogs which are always visible to all connected builders.
    Call the POST /catalogues/{catalogueId}/accesscontrols endpoint to grant access to that catalog for this builder's ExternalRef.