Finding & connecting suppliers

To get value from Procurement, your customers will need to be connected to at least one supplier. Suppliers make products available for ordering, as well as supporting features like real-time price checking.

All suppliers can be accessed using the GET /suppliers endpoint, for example:

GET /api/v2/suppliers
Accept: application/json

HTTP 200 OK
[
  {
    "id": "b1475f65-236c-58b8-96e1-e1778b43beb7",
    "name": "Bounty Soap Inc.",
    "connected": false,
    ...
  }
]

Each supplier in the response includes a connected attribute - when true, this means that your customer is able to browse their products and place orders; when false, it means that the supplier is available to request a new connection.

The connection between your customer and a supplier is known as a contract, and so the process of creating this connection involves creating a contract request. This request includes contact information, as well as details of any existing relationship with them (if applicable). Suppliers can either accept or decline these requests.

To request a new connection, you will need to use the POST /contract_requests endpoint. The supplier ID goes in the URL - so for example, to connect with "Bounty Soap Inc." you would make the following request:

POST /api/v2/suppliers/b1475f65-236c-58b8-96e1-e1778b43beb7/contract_requests
Content-Type: application/json

{
  "contract_request": {
    "contact_first_name": "John",
    "contact_last_name": "Smith",
    "contact_email": "john.smith@example.com",
    "customer_number": "42"
  }
}

HTTP 201 Created
{
  "id": "6a03acb9-206d-5aa3-88d3-a41f60807f9e",
  ...
}

You can check the status of this request at any time individually, or see all of the active requests using the other contract request APIs.

Suppliers may take several days to respond, and they may get in touch with your customer outside of Procurement to confirm other details (e.g. contact information). Their response will be to either accept or decline the request, see the sections "Handling accepted requests" and "Handling declined requests" below.

Once there is a supplier available, we can start browsing their products.

Handling accepted requests

If the supplier accepts the request, two things will happen. First, we'll send an email to the customer notifying them that the request was accepted. Secondly, we'll send a Loom event (procurement_consumer.contract_request_accepted), that you might wish to handle (e.g. by adding the new supplier to an internal suppliers list).

Accepting the request automatically connects the customer with the supplier. From this point, you can now move on to browsing their products.

Handling declined requests

If the supplier declines the request, we'll do a similar thing as accepting - an email will be sent, and a procurement_consumer.contract_request_declined event will be sent. The supplier may get in touch with your customer outside of the Procurement system, and the usual course of action would be to re-submit the request, which can be done by modifying the request, for example:

PATCH /api/v2/contract_requests/6a03acb9-206d-5aa3-88d3-a41f60807f9e
Content-Type: application/json

HTTP 200 OK
{
  "contract_request": {
    "customer_number": "39"
  }
}