Three different types of fields are described on this page:
Orders fields
| Field | Description |
|---|---|
| id | String, Yordex generated UUID that is unique for this order |
| buyerOrderReference | String, optional The reference or ID under which this order is known in the systems of the buyer. The maximum length is 256 characters |
| sellerOrderReference | String, optional The reference or ID under which this order is known in the systems of the seller. The maximum length is 256 characters |
| status | String, Yordex generated The status of this order. Possible values are listed on the right |
| buyerId | String, mandatory The id for the trader who is the buyer in this order. This is the id used in the Traders API. This ID can also be found on the Contacts page for this trader |
| sellerId | String, mandatory The id for the trader who is the seller in this order. This is the id used in the Traders API. This ID can also be found on the Contacts page for this trader |
| buyerWatcherUserIds | String, Yordex generated The ids of everyone who has viewing access to the details of an order |
| buyerCompanyTradingName | String, Yordex generated The company trading name for the trader who is the buyer in this order. This name is inserted by us for convenience. We will obtain if from the Traders API but you can also set it directly. |
| sellerCompanyTradingName | String, Yordex generated The company trading name for the trader who is the seller in this order. This name is inserted by us for convenience. We will obtain if from the Traders API but you can also set it directly. |
| description | String, optional A description for this order. The maximum length for this field is 255 characters |
| orderAmountInCents orderAmountInCentsInBaseCurrency | Number, optional when creating order, mandatory when approving order The total value for this order expressed in cents of the orderCurrency including VAT or GST. For example, when the orderAmountInCents is 100 and the orderCurrency is USD, the order is for $1. This field is optional when creating the order but mandatory when approving the order |
| orderCurrency | String, optional when creating order, mandatory when approving order The currency for this order using the ISO-4217 standard. This field is optional when creating the order but mandatory when approving the order |
| orderCurrencyExponent | String, Yordex generated Indicates how many numbers at the end are reserved for cents. For most currencies this will be “2” : they have 2 digits so 100 cents. Some currencies have 0, 1 or 3 numbers. You will find a full list of supported currencies and their exponents here |
| vatAmountInCents | Number, Yordex generated The amount of VAT or GST included in the order amount in cents of the orderCurrency. This field will be calculated by Yordex if tax is included in the line items. |
| vatIncluded | Deprecated field, don't use |
| buyerUserId buyerUserEmail | String, optional The user id of the the employee on the buyer's side who owns this order. This field can only be set by the buyer and it is updated using a PATCH. |
| buyerUserName buyerUserFirstName buyerUserLastName | String, Yordex generated Name of the employee on the buyer's side who owns this order. |
| sellerUserId | String, optional The user id of the the employee on the seller's side who owns this order. This field can only be set by the seller and it is updated using a PATCH |
| buyerTags | Array, optional A set of user defined key:value pairs that can be used by the buyer to label the order. This field can only be set by the buyer and it is updated using a PATCH. Common buyerTags are: orderType: "PO" or "EXPENSE" POType: "RECURRING" |
| creationDate | String, Yordex generated The date on which this order was created using the ISO-8601 standard |
| creationTime | String, Yordex generated The time at which the order was created. |
| modificationDate | String, Yordex generated The date on which this order was last updated using the ISO-8601 standard |
| terms | String, optional The name of the terms to be used for this order. See the Terms API |
| events | Array, optional when creating order, mandatory when approving order An array representing the terms for this order. Every event represents a real-world event that can trigger a payment, e.g. “contract signed”, “goods ready for shipping” or “goods received”. The events fields are described below. The events array is optional when creating the order but mandatory when approving the order |
| lineItems | Array, optional An array representing the line items for this order. The line items fields are described below. |
| buyerCostAllocation | Array, optional An array of budget(s) that this order should be charged to for the buyer. When the order has no line items, this field can be set directly. When the order has line items, this field will be populated by the system as the weighted average of all cost allocations of the line items. |
| . budget | Object, mandatory when a buyerCostAllocation is provided The budget that this order is assigned to. Fields used within this object are customised to your account so not documented here. |
| . budgetValues | *Object, Yordex generated** The human readable names of the budget that this order is assigned to. Fields used within this object are customised to your account so not documented here. |
| . allocation | Object, mandatory when a buyerCostAllocation is provided The % of the order that is assigned to this budget. |
| . allocationAmountInCents | Number, Yordex generated The amount that is allocated to this cost allocation. It is the same as the orderAmountInCents times the allocation |
| . allocationVatAmountInCents | Number, Yordex generated The tax amount that is allocated to this cost allocation. It is the same as the orderVatAmountInCents of the order times the allocation |
| . budgetName . fullBudgetName | String, Yordex generated The name of the budget to be used for display and reporting purposes only |
| . glCode | String, Yordex generated The glCode of the budget to be used for display and reporting purposes only |
| . budgetLineOwner . budgetLineOwnerName | String, Yordex generated The id and name of the employee who is the budgetOwner for this cost allocation |
| inBudget | Boolean, Yordex generated Whether or not the expense is within the limits of the remaining budget. |
| services | String, optional The services used in this order. |
| . serviceName | String, mandatory for each service Name of the service: MASSPAY (payouts), YORDEX_CARD or OWN_PAYMENTS |
| . tags | Array, optional Array of key:value pairs. Both the key and the value can be set by the user. A maximum of 5 tags can be added for each service. Required for payouts: buyer_currency seller_currency |
| nextApprover | String, Yordex generated This is the traderId of either the buyer or the seller, depending on which of these two needs to approve the order next |
| approvals | Array, Yordex generated All approvals received for this order. An order is only approved by the buyer if all internalApprovals have been completed. For the seller, all approvals are recorded here |
| . approved | Boolean, mandatory Indicating approval (true) or rejection (false) of this order |
| . date | String, Yordex generated The date on which this order was approved using the ISO-8601 standard |
| . approverTraderId | String, Yordex generated Id of the trader who approved the order |
| . approver | String, Yordex generated Role of the party that approved. This can be SELLER, BUYER or SYSTEM |
| internalApprovals | Array, Yordex generated All internal approvals received for this order by the buyer. This object is only returned if the buyer gets the order |
| actions | Object, Yordex generated This array lists all the actions that are possible on this order and its events |
| Order status | Description |
|---|---|
| NOT_APPROVED | Order is not yet approved and can still be edited |
| TRADER_APPROVED | Both buyer and seller approved the order but Yordex is still reviewing it |
| APPROVED | Order is approved and the events are in progress |
| COMPLETED | Order is completed, all events and all payments have been completed |
| CLOSED | Order was cancelled by the seller. The order can be re-opened using the “Open order” method |
Events fields
| Field | Description |
|---|---|
| id | String, Yordex generated UUID that is unique for this event |
| eventName | String, mandatory The name of the real-world event. When this event has a payment associated with it, this will be the event that triggers the payment, e.g. "Order approved", "Goods ready for shipping" or "Goods received" |
| paymentName | String, optional The name of the payment for this event. For example, this could be "Deposit", "Partial payment" or "Full payment" |
| status | String, Yordex generated The status of this event. Possible values are listed on the right |
| spendStatus | String, Yordex generated The status that combines the order status and event status in a unique status name. Values are listed on the right |
| buyerAccountingSynced | String, Yordex generated Whether this event has been synced with the buyer's accounting system or not. This field can be toggled using a PATCH API |
| pctToBePaid | String, optional The percentage of the orderAmountInCents of the order that will be due for this event. For example, if 30% is due when the order is approved, the value for this field will be 30. The sum of pctToBePaid for all events has to be 100 but for an individual event this field can be 0 or not provided |
| paymentType | String, optional The type of payment for this event. Possible values are listed on the right. This field is mandatory if pctToBePaid is defined. |
| amountToBePaidInCents | String, Yordex generated This is pctToBePaid times the orderAmountInCents of the order. The currency is the same as the orderCurrency for the order. |
| vatAmountToBePaidInCents | String, Yordex generated This is tax (VAT) associated with this event. It is calculated as the vat times the amountToBePaidInCents of the event. The currency is the same as the orderCurrency for the order. |
| receivedAmountInCents | String, Yordex generated The amount that has been paid in for this order. The currency is the same as the orderCurrency for the order. |
| invoiceDate | String, Yordex generated The data of the invoice. The user specifies this field when uploading the invoice as a document and we will copy that field into this event |
| invoiceReference | String, Yordex generated The reference of the invoice. The user specifies this field when uploading the invoice as a document and we will copy that field into this event |
| confirmationDueDate | String, optional Date by when we expect this event to be confirmed. This is used to alert responsible users when the event isn't confirmed on time and also to estimate the paymentDueDate. When the order is created the paymentDueDate is estimated to be the confirmationDueDate plus the credit terms. |
| paymentDueDate | String, optional Date by which the buyer has to pay. When this date passes, the status of the event will automatically update from PAYMENT_DUE to PAYMENT_OVERDUE. It is possible to specify this date yourself, but if one or both of creditTerms or creditTermsFrom are set, the paymentDueDate will be overwritten based on the confirmationDueDate or invoiceDate. |
| recognitionMonths | Number, optional The number of months over which the costs for this event has to be recognised for accounting purposes. This field is only provided for orders with buyerTag POType:RECURRING |
| paymentRecognitionDates | Array, Yordex generated Date on which the costs for this event should be recognised for accounting purposes. This is based on the recognitionMonths field and the paymentDueDate. |
| creditTerms | String, optional Number of days that the buyer has to pay the invoice after the event is confirmed. For example, if the value for this field is 30 that means the buyer has 30 days to pay the invoice. The paymentDueDate will be set to be the confirmation date plus creditTerms when the event is confirmed. creditTerms has precedence, over the paymentDueDate so when both paymentDueDate and creditTerms have been set before the event is confirmed, the paymentDueDate will be overwritten when the event is confirmed. |
| creditTermsFrom | String, optional The start date for the creditTerms. The only possible value is EOM (End of Month). The default is the invoiceDate, but if EOM is specified, the creditTerms will start counting from the last date of the month of the invoice date. |
| eventNumber | String, optional for POST, mandatory for PUT Events are sequential and the eventNumber indicates the position of this event in the list of events. The first event has eventNumber 1 etc. If no eventNumber is specified when creating an event, it will automatically be added as the last event. It is mandatory to provide an eventNumber when updating an event |
| documentsRequired | Array, optional Documents that need to be uploaded before this event can be confirmed. An invoice would be a typical example of such a document, but other document types could include a bill of lading, an inspection report etc. It is up to the confirmers to verify these documents before confirming. The system will allow confirmation if the documents are not uploaded. The structure of a required document is described below. |
| earlyPaymentDiscount | Object, optional An early payment discount associated with this event. |
| . discountPct | Float, mandatory when an earlyPaymentDiscount is set The percentage discount offered, e.g. 2% |
| . expiryDays | Integer, optional The number of days after the invoice date after which the early payment discount expires. This field is not required for [dynamic discounting[(https://yordex.com/faqs/what-is-dynamic-discounting) when the early payment discount is added after the invoice is already provided. |
| . expiryDate | Date, mandatory once the event is confirmed The date on which the early payment discount will expire. |
| confirmers | Array, optional Possible values are BUYER, SELLER or PROVIDER of a service. Each party listed has to confirm this event before the payment becomes due. If there are no confirmers, the payment will automatically become due as soon as the previous event is completed or as soon as the order is approved in case this is the first event of the order |
| confirmed | Boolean, Yordex generated Indicates whether this event has been confirmed or not |
| confirmations | Array, Yordex generated An array with all confirmations received for this event. The structure of a confirmation is described below |
| . confirmerType | String, Yordex generated Actor who confirmed the event. This can be BUYER, SELLER or PROVIDER of a service |
| . date | String, Yordex generated The date on which this event was confirmed using the ISO-8601 standard |
| invoiceMandatory | Boolean, optional Indicates whether an invoice is mandatory for this event. If so, if the event has been fully paid, the status will become WAITING_FOR_INVOICE. Only when the invoice is provided will the status of the event become COMPLETED. The default value is false. |
| generateInvoice | Boolean, optional Indicates whether an invoice should be generated by Yordex for this event. The default is false |
| Event Status | Description |
|---|---|
| NOT_STARTED | Event was not yet started, either because the order was not yet approved or because the previous event was not yet completed |
| FOR_CONFIRMATION | Event has started and the next step is for the confirmers of this event to confirm the associated real-world event has happened |
| PAYMENT_DUE | Real-world event has been confirmed; the payment is now due |
| PAYMENT_OVERDUE | Real-world event has been confirmed; the paymentDueDate has passed so the payment is now overdue |
| WAITING_FOR_INVOICE | The event has been confirmed and paid but the invoice has not yet been provided. An event will only go into this state if the field invoiceMandatory has been set to true |
| COMPLETED | Event has been confirmed and paid |
| spendStatus | order.status | event.status |
|---|---|---|
| NOT_SUBMITTED | NOT_APPROVED, next approver is this user | Any, except COMPLETED |
| AWAITING_APPROVAL | NOT_APPROVED, next approver is another user | Any, except COMPLETED |
| CONFIRM | APPROVED | FOR_CONFIRMATION |
| AWAITING_PAYMENT | APPROVED | PAYMENT DUE, PAYMENT_OVERDUE |
| COMPLETED | APPROVED, NOT_APPROVED or COMPLETED | COMPLETED |
| AWAITING_INVOICE | APPROVED | WAITING_FOR_INVOICE |
| DISPUTED | APPROVED | DISPUTED |
| CANCELLED | CLOSED, last approval wasn’t a rejection | Any |
| REJECTED | CLOSED, last approval was a rejection | Any |
| Payment Type | Description |
|---|---|
| PAYMENT | Payments where the buyer pays the seller directly |
| PAYIN | Payments where the buyer pays a third party |
| PAYOUT | Payments where a third party pays the seller |
Line items fields
| Field | Description |
|---|---|
| id | String, Yordex generated UUID that is unique for this line item |
| orderId | String, Yordex generated The id of the order this line item belongs to |
| lineItemNumber | Number, mandatory Line items are in order. This is the rank order of the line item |
| type | String, mandatory Usually "PRODUCT" indicating this is a product line item. It can also be "COST" |
| master | Boolean, Yordex generated When created all line items are master line items. When partially receiving a line item, including for subscription, non-master line items are created. |
| name | String, mandatory The description of the line item |
| listPriceInCents | Number, mandatory The unit cost of the line item before tax and discounts in cents |
| quantity | Number, mandatory The quantity ordered |
| vat | Number, optional The sales tax to be applied to this line item in %. Only one off vat, vatAmountInCents or buyerTaxType can be provided |
| vatAmountInCents | Number, optional The sales tax to be applied to this line item as an amount in cents. Only one off vat, vatAmountInCents or buyerTaxType can be provided |
| buyerTaxType | String, optional The sales tax to be applied to this line item as a tax type string which are defined separately for each trader. Only one off vat, vatAmountInCents or taxCode can be provided |
| discount | Number, optional The discount to be applied to this line item in %. |
| lineItemAmountInCents | Number, Yordex generated The total amount for this line item in cents. This is equal to the listPriceInCents quantity (1-vat) * (1-discount) |
| buyerCostAllocation | Array, optional The same as the buyerCostAllocation of orders |
| buyerProductReference | String, optional A product number or other reference number for this line items as used by the buyer |
| sellerProductReference | String, optional A product number or other reference number for this line items as used by the seller |