Issue a new order
How to issue a new purchase order as a buyer
As buyer you can send either a new or updated purchase order to your supplier.
Order process
The new order lines will have order process status Issued
and logistics status Open
Endpoints
Use the Send order endpoint when your ERP system supports a delivery schedule natively.
Or use the Send single delivery order endpoint for the single delivery per order line.
Please see this page to choose between the delivery schedule or single delivery per order line:
Delivery scheduleWhen sending an order the provided supplier account number will be verified.
Order
companyId
: the optional Tradecloud company identifier. You only have to provide a companyId when your integration user account has authorization for multiple companies.buyerParty
: the optional legal entity that purchases the goods or services. See Company party.buyerAccountingParty
: the optional legal entity that receives and handles the invoice. The supplier must send the invoice to the buyer accounting party when specified. See Company party.supplierAccountNumber
: the supplier account number as known in your ERP system.
The supplierAccountNumber
must be set in the Tradecloud connection in the portal, after the connection request has been accepted by the other party.
supplierParty
: the optional legal entity that sells the goods or services. See Company party.purchaseOrderNumber
: the purchase order number as known in your ERP system.
The purchaseOrderNumber
must not contain whitespace characters.
destination
: the delivery destination of this order as known in your ERP systemcontact.email
: the buyer employee responsible for this order. The user with this email address should be active in Tradecloud.supplierContact.email
: if known, the supplier employee responsible for this order. The user with this email address should be active in Tradecloud.
id
, supplierAccountNumber
, purchaseOrderNumber
, destination.code
and contact.email
should be unique within your company and never change. Never renumber or re-use identifiers, numbers or code's.
Company party
The optional buyer, buyer accounting or supplier company party:
id
: the optional identifier for the party, for example a GLN.idScheme
: the optional scheme, providing context to the identifier. Eg."KvK"
,"GLN"
, etc.names
: the legal names of the party. It is recommended to provide at least one name.addressLines
: the location address lines of the party. It is recommended to provide at least one address line.postalCode
: the location postal code of the party. Provide whenaddressLines
are provided.city
: the location city of the party. Provide whenaddressLines
are provided.countryCodeIso2
the ISO 3166-1 alpha-2 country code of the party. Provide whenaddressLines
are provided.countryName
the optional country name of the party.
Other order fields
description
: a free format additional description of this orderterms
: the order terms as agreed with your supplierindicators
: various order level indicators, see:
properties
: are key-value based custom fields. You can user as many as needed, but too many will clutter the portal. Use for a new line in the value.notes
: are simple custom fields. You can user as many as needed, but too many will clutter the portal. Use for a new line.labels
: value-added services labels on order level. Please note the practicable number of labels is dependent on the supplier.documents
: contain meta data and link of attached documents. The total number of documents is limited to 100 documents per order header. See:
orderType
: the order type, one ofPurchase
,Forecast
orRFQ
. DefaultPurchase
.
Lines
lines
: a purchase order contains one or multiple lines. The total number of lines is limited to 500 lines per order. It is structured as a JSON element in the lines
JSON array.
position
: the required line position identifier within the purchase orderrow
: the optional row label for this position. Only use a row when there is a distinction between position and row in your ERP system. Do NOT use row as identifier.
lines.position
should be unique within the order and never change. Never renumber or re-use position
numbers.
Item
lines.item
: the item (or article, goods) to be delivered
number
: the item code or number as known in your ERPrevision
: the revision (or version) of this item numbername
: the item short namepurchaseUnitOfMeasureIso
: the purchase unit according to ISO 80000-1, a typical example isPCE
supplierItemNumber
: the item code or number as known at the supplier. Required in case of wholesale suppliers.
item.number
should be unique within your company and never change. Never renumber or re-use item.number
s.
Item details
lines.itemDetails
: detailed part information initially provided by buyer.
The buyer may send item details to inform the supplier about part information.
The supplier may check, change and add item details if they are not correct or incomplete.
The webhook orderEvent.lines.itemDetails.mergedItemDetails
will contain the merged original item details added by the buyer merged with the changed or added item details by the supplier.
countryOfOriginCodeIso2
: The ISO 3166-1 alpha-2 country code of manufacture, production, or growth where an article or product comes from.combinedNomenclatureCode
: A tool for classifying goods, set up to meet the requirements both of the Common Customs Tariff and of the EU's external trade statistics.netWeight
: Net weight of one item.netWeightUnitOfMeasureIso
: Net weight unit according to ISO 80000-1.dangerousGoodsCodeUnece
: UN numbers or UN IDs are four-digit numbers that identify dangerous goods, hazardous substances and articles in the framework of international transport.serialNumber
: is an unique identifier assigned incrementally or sequentially to an item, to uniquely identify it.batchNumber
: is an identification number assigned to a particular quantity or lot of material from a single manufacturer
Requested planned delivery schedule
Use the lines.deliverySchedule
field when your ERP system supports a delivery schedule natively.
Or use the lines.scheduledDelivery
field when using single delivery per order line.
Please see this page to choose between the delivery schedule or single delivery per order line:
Delivery scheduleRequested prices
lines.prices
: the requested price. Advised is to provide only netPrice
for its simplicity, used by most buyers, or alternatively grossPrice
together with discountPercentage
.
grossPrice
: the gross price. Use together withdiscountPercentage
.discountPercentage
: the discount percentage. Use together withgrossPrice
.netPrice
: the net price.priceInTransactionCurrency
: at least provide a price in the transaction currency of the supplier, likeCNY
in China.value
: the price value has a decimal1234.56
format with any number of digits.currencyIso
: the 3-letter currency code according to ISO 4217, likeEUR
,USD
andCNY
.
priceInBaseCurrency
: provide a price in your base currency, likeEUR
in the EU.value
: the price value has a decimal1234.56
format with any number of digits.currencyIso
: the 3-letter currency code according to ISO 4217, likeEUR
.
priceUnitOfMeasureIso
: the price unit according to ISO 80000-1. The purchase unit and price unit may be different.priceUnitQuantity
: the item quantity at which the price applies. Typically this is 1 (unit price) or 100 (the price applies to 100 items)
Requested charge lines
lines.chargeLines
: the requested additional cost lines of an order line, independent of the order line prices, like transport, packing, administration, inspection and certification costs.
position
: the position used to identify a charge line.chargeTypeCode
: the mandatory charge reason code according to UNCL7161chargeDescription
: a mandatory free text description, like "Transport costs".quantity
: the mandatory quantity of this charge line.price
: the mandatory price of this charge line.priceInTransactionCurrency
: the mandatory price in the transaction currency of the supplier, likeCNY
in China.value
: the price value has a decimal1234.56
format with any number of digits.currencyIso
: the 3-letter currency code according to ISO 4217, likeEUR
,USD
andCNY
.
priceInBaseCurrency
: the optional price in your base currency, likeEUR
in the EU.value
: the price value has a decimal1234.56
format with any number of digits.currencyIso
: the 3-letter currency code according to ISO 4217, likeEUR
.
priceUnitOfMeasureIso
: the 3-letter price unit according to ISO 80000-1 which applies to the charge line price.
The single delivery variant, where charge lines are spread over multiple order lines having the same item, prices and terms, and each only one charge line, is not supported. Send a support request if you need it.
Other line fields
description
: a free format additional description of this lineterms
: the line terms as agreed with your suppliercontractNumber
: the agreed framework contract numbercontractPosition
: the related position within the framework contract
projectNumber
: Your project number referenceproductionNumber
: Your production number referencesalesOrderNumber
: Your sales order reference (not be confused with the supplier sales order number)indicators
: various line level indicators, see:
When a line has no goods to be delivered, for example a service, fee or text line:
No delivery expectedWhen your order process requires the buyer to always approve every line:
Propose when acceptedproperties
: are key-value based custom fields. You can use as many as needed, but too many will clutter the portal. Use for a new line in the value.documents
: contain attached documents. The total number of documents is limited to 100 documents per order line. See:
notes
: are simple custom fields.You can use as many as needed, but too many will clutter the portal. Use for a new line.labels
: value-added services labels on line level. Please note the practicable number of labels is dependent on the supplier.
New order meta data
erpIssueDateTime
: Date and time the order was originally issued in your ERP system.DateTime
has ISO 8601 local date/time formatyyyy-MM-ddThh:mm:ss
. See also Standards.erpIssuedBy
: the user email or user name as known in your ERP system who issued this order
Response
When the /api-connector/order
API method returns HTTP status code 200, the order was successfully queued for processing by Tradecloud. Processing takes usually less then a second, after which the order is available in the portal and is forwarded to the supplier ERP integration.
Last updated