Guides

Managing suppliers

This page will show you how to manage suppliers

Suggest Edits

Both customers (buyers) and suppliers are represented by the traders resource in Yordex. This page will explain how to manage traders by API and has the following sections:

Traders can also be managed manually from the contacts section of our web app.

A trader will usually mean a supplier so on the rest of this page we will usually refer to suppliers.

Creating a new supplier

A supplier can be created like this:

curl {baseURL}/traders  
-H "Content-type: application/json"  
-H "Accept: application/json"  
-X POST  
-d '{ 
    "traderId": "your-trader-id",
    "user" :{
        "email":"[email protected]"
    },
    "companyTradingName": "Company name",
    "companyTradingAddress": {
      "address1": "16 Grosvenor Close",
      "postalCode": "W2 6GH",
      "city": "London",
      "state": "London",
      "countryCode": "GB"
    }
}'

The user and companyTradingName fields are mandatory. The address is optional. Providing your traderId will create the relation between you and the new supplier.

The response to this request will look like this:

{
  "id":"trader-id",
  "user" :{
      "email":"[email protected]",
  },
  "companyTradingName": "Company name",
  "companyTradingAddress": {
    "address1": "16 Grosvenor Close",
    "postalCode": "W2 6GH",
    "city": "London",
    "state": "London",
    "countryCode": "GB"
  }
}

Getting traders

You can get traders like this:

curl {baseURL}/traders?q=<company name>
-H "Authorization:your-api-key"  
-X GET

The following search parameters can be provided:

  • q=name: to search suppliers by name. The string should be at least three characters long
  • expand=trader.relation_status: when provided, the response will include the 'relation' object shown below. This object will show the supplier's approval status and any other custom supplier fields you require

The response will look as follows:

{ 
    "id": "trader-id",
    "companyTradingName": "Company name",
    "companyTradingAddress": {
      "address1": "16 Grosvenor Close",
      "postalCode": "W2 6GH",
      "city": "London",
      "state": "London",
      "countryCode": "GB"
    },
    "relation": {
      "id": "relation-id",
      "status": "relation-status",
      "traderId": "relation-trader-id",
      "approverUserId": "relation-approver",
      "ownerUserId": "relation-owner",
      "customerTraderId": "custom-supplier-id"
    }
}

Details of a single trader can be obtained as follows:

curl {baseURL}/traders/trader-id  
-H "Content-type: application/json"  
-X GET

Not all fields are shown here. A full list of fields is explained in the API reference.

Updating a trader

Updating a trader is done as follows:

curl {baseURL}/traders/trader-id  
-H "Authorization:your-api-key"  
-H "Content-type: application/json"  
-H "Accept: application/json"  
-X PUT  
-d '{ 
    "companyTradingName": "Company name",
    "companyTradingAddress": {
      "address1": "16 Grosvenor Close",
      "postalCode": "W2 6GH",
      "city": "London",
      "state": "London",
      "countryCode": "GB"
    }
}'

RequestOptions requestOptions = RequestOptions.builder().apiKey("apiKey").build();
Address tradingAddress = Address.builder().
        address1("address1").city("city").postalCode("postalCode").countryCode("GB").build();
Address registeredAddress = Address.builder().
        address1("address1").city("city").postalCode("postalCode").countryCode("GB").build();
Trader updatedTrader = Trader.builder().
        companyTradingName("tradingName").
        companyRegisteredName("registeredName").
        companyTradingAddress(tradingAddress).
        companyRegisteredAddress("registeredAddress").
        build();
updatedTrader = Trader.update(traderId, updatedTrader, requestOptions);

🚧

Specify all fields

We are using a PUT to update a trader. This means that fields that are not specified will be set to null. For example, if a trader was created with an companyTradingAddress but you do not provide provide that same companyTradingAddress when updating the trader, the address field will be set to null

All trader fields can be updated apart from id, partnerId/traderId and user.

Adding bank details

Bank details can be added like this

curl {baseURL}/traders
-H "Content-type: application/json"  
-H "Accept: application/json"  
-X POST  
-d '{ 
    "bankAccount": {
      "bankName": "Wells Fargo",
      "accountHolderName": "Company name",
      "accountNumber": "12345678",
      "routingNumber": "123456"
    },
  ... // all other fields required to create a trader
}'

The bankAccount fields required depend on the country. A full list of bankAccount fields is provided in our API reference.

Managing trader relations

To find out what your relation is to another trader, you should call this API

curl {baseURL}/relations?traderId=other-trader-id
-H "Authorization:your-api-key"  
-X GET

The response will look as follows.

{
  "id" : "relation-id",
  "approved" : false,
  "traderId" : "other-trader-id",
  "traderForm": {
    "key" : "value"
  },
  "approverUserId": "user-id",
  "ownerUserId": "user-id"
}

A relation will only exist if you created this other trader.

In this example, the trader is not yet approved. If the trader is approved, the approved field will be true.

The traderForm field is a free form object that you can use to store any data about this relation. For example, you can use it to store the id under which this other trader is known in your systems or you can store information from your custom supplier boarding form.

The ownerUserId and approverUserId are fields used by us to approve this trader.

Updated about 1 year ago

What’s Next