The business partner
A business partner is one company, however many ways the tenant deals with it. A garden-tools company that both supplies your stores and manufactures some of the goods it supplies is one record with two roles, not two records.
The id
businessPartnerId is your ERP's id for the partner: 1 to 64 characters, with no spaces and none of
/, ?, # or %. It is taken from the URL of the PUT, so the request body does not repeat it.
It is the same id that Goods Received, Stock Transaction Processing, Stock Count and Stock Corrections
already carry as businessPartnerId. Those services accept the id as it is sent and do not require the
partner to be registered here first, so registering partners never holds up a delivery. It does mean that
the ids must match: a partner registered under one id and delivering under another is two unconnected
records.
displayId is optional. Use it when the number your staff see differs from the id in your ERP's
interfaces.
Roles
Each partner holds at least one role, and each role at most once.
| Role | The partner… | Carries |
|---|---|---|
SUPPLIER | sells goods to you, so you order from it and it delivers | the default lead time and a reliability score, both optional. See Supplier terms |
MANUFACTURER | makes goods that you sell, whoever supplies them | nothing beyond the role. The supplier terms are refused on this role, even as null |
Each role has its own isActive flag. A partner you have stopped buying from, but whose products are
still on your shelves, keeps both roles with SUPPLIER set to isActive: false. Hii Retail stores and
publishes the flag; it does not act on it.
⚠ Expect more roles. Only SUPPLIER and MANUFACTURER exist today. Other roles, such as carriers or
logistics providers, may be added as values of role without a new version of the API or the events.
Code that reads roles should skip a role it does not recognise rather than reject the partner.
Status
status is the partner's lifecycle status as your ERP keeps it.
| Value | Hii Retail's handling |
|---|---|
Active, Passive, Expired, Discontinued, Replaced | stored and published as sent. The partner is listed, read and matched like any other |
Deleted | set by DELETE. The partner is left out of the list unless you ask for deleted partners, but it can still be read by its id, and a later PUT restores it |
Apart from Deleted, Hii Retail does not interpret the status. Use the value that matches your ERP's
own status, so that consumers of the events see the same lifecycle that you do.
A partner with a status other than Deleted is still matched when Goods Received looks up a shipper's
GLN. The goods have physically arrived, and a delivery on an order placed before the partner was retired
still has to be received.
The GLN
gln is the partner's GS1 Global Location Number: exactly 13 digits, with a valid GS1 check digit.
It is optional; leave it out, or send null, when the partner has none.
🛑 If your suppliers identify themselves on despatch advices by GLN only, register their GLN here and keep
each GLN on one partner. Goods Received matches a shipper that carries only a GLN against your own
business units first, then against your business partners. A GLN that matches one partner (not
Deleted) is recorded as that partner. A GLN that matches no partner, or more than one, fails the import.
Business Partner itself does not stop two partners from sharing a GLN, so keeping them unique is up to the
system that sends them. See GS1 import.
Addresses
addresses holds at most one address of each type:
addressType | Used for |
|---|---|
Visit | where the partner can be visited |
Postal | where post is sent |
Delivery | where goods are delivered to the partner, which is the address returned goods are sent to |
Invoice | where invoices are sent |
These are the same four types Business Unit Management uses for your own business units.
Every address needs a zipCode and a city. countryCode, when sent, is an ISO 3166-1 alpha-2 code such
as SE. The other fields (careOf, street, county, country, phone, mobile, email,
contactPerson) are optional. addresses itself is required but may be empty.
Your own properties
additionalProperties carries fields that Hii Retail has no column for but you want to travel with the
partner, such as payment terms or a purchasing contact. Each entry has an id, a name, a dataType
and a value, which is always a string (or null), with an optional code and description.
{ "id": "paymentTerms", "name": "Payment terms", "code": "PT30", "description": null,
"dataType": "STRING", "value": "30 days net" }
dataType says how to read the string: BOOL, INT, LONG, DECIMAL, DOUBLE, STRING, DATE,
DATETIME, CURRENCY, IMAGE, BINARY, LINK, ARRAY, JSON, XML or UNKNOWN. Hii Retail stores
and publishes the list as sent and does not act on it. additionalProperties is required but may be empty.
One partner for the whole tenant
A partner is registered once for the tenant and applies in every country and every store. There is no assignment of a partner to a store or a store group, and no setting per business unit.
Which partner supplies which article to which store, for example different suppliers in Norway and in Sweden within one tenant, is not a property of the partner. Nor is a minimum order quantity: a minimum is agreed per article and pack, so it cannot be one number for everything a supplier sells. Both belong to Ordering Options, a separate service that says what is bought, from which source, in which pack, and for which stores.