Guides

Managing traders

This page will show you how to manage traders

Suggest Edits

Traders can be suppliers, users and even yourself. An overview of users vs traders can be found here

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 trader

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 company name search string should be at least three characters long.

Details of a trader can be obtained as follows:

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

The response will look as follows:

{ 
    "id": "trader-id",
    "traderStatus": "REGISTERED",
    "companyTradingName": "Company name",
    "companyTradingAddress": {
      "address1": "16 Grosvenor Close",
      "postalCode": "W2 6GH",
      "city": "London",
      "state": "London",
      "countryCode": "GB"
    }
}

When you have created a trader yourself, their traderStatus will be "REGISTERED" and you will be able to update their details. A trader can always claim their own account on the Yordex website. Once they have done this, the trader status will become "CONFIRMED" and you will no longer be able to update their account.

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 9 months ago

What’s Next