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.

The order should only contain order lines that are new or changed. Sending an unchanged order line could trigger an unexpected line status change in Tradecloud.

Order process

As a buyer you can send a new purchase order to Tradecloud.

The new order lines will have order process status Issuedand logistics status Open

post
Send order by buyer

https://api.accp.tradecloud1.com/v2/api-connector/order
Request
Response
Request
Headers
Authorization
required
string
Bearer Access-Token
Content-Type
required
string
application/json
Body Parameters
body
required
object
Order JSON body
Response
200: OK

Order

  • companyId: the optional Tradecloud company identifier. You only have to provide a companyId when your integration user account has multiple company permissions.

  • supplierAccountNumber: the supplier account number as known in your ERP system

  • purchaseOrderNumber: the purchase order number as known in your ERP system.

The purchase order number must not contain whitespace characters

  • destination: the delivery destination of this order as known in your ERP system

  • contact: the employee responsible for this order. You can either send his/her email or userName as known in your ERP system

supplierAccountNumber, purchaseOrderNumber, destination.code, contact.email and contact.userName should be unique within your company and never change. Never renumber or re-use numbers or code's.

The supplierAccountNumber should be set on forehand in the Tradecloud connection with your supplier. You can set the account code when inviting a new connection or in the connection overview in the portal.

Other order fields

  • description: a free format additional description of this order

  • terms: the order terms as agreed with your supplier

  • indicators:

  • properties: are key-value based custom fields. You can user as many as needed, but too many will clutter the portal. Use \n 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 \n 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, see:

Lines

  • lines: a purchase order contains one or multiple lines

  • line: a purchase order line which contains at least the position, item and delivery schedule. It is structured as a JSON element in the lines JSON array.

  • position: the required line position identifier within the purchase order

  • row: 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

  • lines.item.number: the item code or number as known in your ERP

  • lines.item.revision: the revision (or version) of this item number

  • lines.item.name: the item short name

  • lines.item.purchaseUnitOfMeasureIso: the purchase unit according to ISO 80000-1, a typical example is PCE

  • lines.item.supplierItemNumber: the item code or number as known at the supplier. Advised in case of wholesale suppliers.

item.number should be unique within your company and never change. Never renumber or re-use item.numbers.

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

  • line.deliverySchedule: the requested planned delivery schedule. Provide at least one or multiple delivery schedule lines.

  • deliverySchedule.position: the optional position in the delivery schedule. Required when using status. Not to be confused with the line.position

  • deliverySchedule.date: the requested delivery date of this delivery schedule position. Date has ISO 8601 date yyyy-MM-dd format. See also Standards.

  • deliverySchedule.quantity: the requested quantity of this delivery schedule position. Quantity has a decimal 1234.56 format with any number of digits.

deliverySchedule.position should be unique within the delivery schedule and never change. Never renumber or re-use deliverySchedule.positions.

Requested 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.

  • priceInTransactionCurrency: at least provide a price in the transaction currency of the supplier, like CNY in China.

  • priceInBaseCurrency: provide a price in your base currency, like EUR in the EU.

  • value: the price value has a decimal 1234.56 format with any number of digits.

  • currencyIso: the 3-letter currency code according to ISO 4217, like EUR, USD and CNY

  • 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)

Other line fields

  • description: a free format additional description of this line

  • terms: the line terms as agreed with your supplier

  • terms.contractNumber: the agreed framework contract number

  • terms.contractPosition: the related position within the framework contract

  • projectNumber: Your project number reference

  • productionNumber: Your production number reference

  • salesOrderNumber: Your sales order reference (not be confused with the supplier sales order number)

  • indicators:

  • properties: are key-value based custom fields. You can use as many as needed, but too many will clutter the portal. Use \n for a new line in the value.

  • documents: contain attached documents, see:

  • notes: are simple custom fields.You can use as many as needed, but too many will clutter the portal. Use \n 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 format yyyy-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.