Updating orders
This page will show you how to edit orders
As explained here, we distinguish between orders and payments. We refer to both as "transactions", the only difference is that payments only contain information provided by the banking partner while orders contain additional information.
In the scheduling payouts page we discussed how to create orders. On this page we explain how to edit orders. It has the following sections:
- Updating the description
- Adding a receipt or invoice
- Updating the payment due date
- Updating the cost allocation
- Updating the taxes
Orders can also be managed manually from our mobile app and the spend section of our web app.
Updating the description
You can update the description of the order like this:
curl {baseURL}/orders/:order-id/description
-H "Authorization:your-api-key"
-H "Content-type: application/json"
-X PATCH
-d '{
"description":"Your description"
}'
Adding a receipt or invoice
You can add a receipt or invoice as follows:
curl {baseURL}/documents
-H "Authorization:your-api-key"
-H "Content-type: application/json"
-X POST
-d '{
"orderId": "order-id",
"eventId": "event-id",
"base64EncodedContent": "content,
"documentDate": "2022-03-26",
"fileName": "invoice.pdf",
"type": "INVOICE"
}'
Receipts and invoices are added to events. The invoice or receipt should be provided as base64 encoded content and the type should always be INVOICE to distinguish them from ATTACHMENT documents.
Every event can only have one receipt or invoice. Providing a new one will overwrite the old one.
Once provided, the receipt or invoice will be associated with the specified event. When getting the order, the response will look as follows:
{
"id": "order-id",
...
"events": [
{
"id": "event-id",
...
"documents": [
{
"id": "document-id",
"location": "https://test.yordex.com/documents/download/document-id",
"fileName": "invoice.pdf",
"type": "INVOICE",
"orderId": "order-id",
"eventId": "event-id",
"documentDate": "2022-03-26"
}
]
}
]
}
You can remove a receipt or invoice as follows:
curl {baseURL}/documents/:document-id
-H "Authorization:your-api-key"
-X DELETE
Updating the payment due date
The payment due date can be updated like this:
curl {baseURL}/orders/:order-id/events/:event-id/paymentduedate
-H "Authorization:your-api-key"
-H "Content-type: application/json"
-X PATCH
-d '{
"paymentduedate": "2021-10-10"
}'
Updating the cost allocation
Cost allocations are set at the line item level.
To update the classification, you therefore first need to get the line item by getting the order. The response will look like this:
{
...
"lineItems": [
{
"id": "lineitem-id",
"lineItemNumber": 1,
"name": "Expense",
"listPriceInCents": 2090,
"quantity": 1,
"lineItemAmountInCents": 2090,
"buyerCostAllocation": [
{
"budget": {
"budgetLine": "budgetline-class-id"
},
"budgetValues": {
"budgetLine": "Cost of Sales"
},
"allocation": 100,
"budgetName": "Cost of Sales"
}
]
}
]
}
This order already has a classification, it was fully allocated to Cost of Sales
To update the classification, you can call this API:
curl {baseURL}/orders/:order-id/lineitems/buyerCostAllocations
-H "Authorization:your-api-key"
-H "Content-type: application/json"
-X PATCH
-d '{
"lineItems": [
{
"lineItemId": "lineitem-id",
"buyerCostAllocation": [
{
"allocation": 100,
"budget": {
"budgetLine": "budgetline-class-id"
}
}
],
...
}
]
}'
Cost classifications are a hierarchy. If you have more than one level in your hierarchy, you can update the cost classification like this:
"buyerCostAllocation": [
{
"allocation": 100,
"budget": {
"department": "department-class-id",
"budgetLine": "budgetline-class-id"
}
}
]
This example shows 2 levels but you can have up to 10 levels. To set up your cost allocation hierarchy, please contact us.
You can also split the cost between different cost classifications like this:
"buyerCostAllocation": [
{
"allocation": 50,
"budget": {
"budgetLine": "budgetline-class-id-1"
}
},
{
"allocation": 50,
"budget": {
"budgetLine": "budgetline-class-id-2"
}
}
]
In this case the costs were split 50:50 but you can split it any way you like. Again, you can split it by up to 10 cost classifications.
To update cost allocations you need to know the cost allocation id. You can get them like this:
curl {baseURL}/budgets?name=budgetLine
-H "Authorization:your-api-key"
-X GET
The response will look like this:
{
"content": [
{
"id": "budgetline-class-id",
"name": "budgetLine",
"value": "Cost of Sales",
"budgetOwner": "[email protected]",
"budgetOwnerName": "Jane Washington",
"currency": "GBP"
}
]
}
Filters you can send in the header are:
- name : the name you have given to your classification(s)
- parentId : if the classifications are a hierarchy such as the department and budgetLine shown above, this is the id of the parent budget
- budgetOwner : the owner of this budget
Updating the taxes
Similar to cost allocations, taxes are set at the line item level:
{
...
"lineItems": [
{
"id": "lineitem-id",
"lineItemNumber": 1,
"name": "Expense",
"listPriceInCents": 2000,
"vat": 20,
"quantity": 1,
"lineItemAmountInCents": 2400
}
]
}
vat is a % so in this case it is 20%. You can also specify the vat as an amount:
curl {baseURL}/orders/:order-id/lineitems/buyerCostAllocations
-H "Authorization:your-api-key"
-H "Content-type: application/json"
-X POST
-d '{
...
"lineItems": [
{
"id": "lineitem-id",
"listPriceInCents": 2000,
"vatAmountInCents": 400,
"quantity": 1
}
]
}'
Or as a tax type:
curl {baseURL}/orders/:order-id/lineitems/buyerCostAllocations
-H "Authorization:your-api-key"
-H "Content-type: application/json"
-X POST
-d '{
...
"lineItems": [
{
"id": "lineitem-id",
"listPriceInCents": 2000,
"buyerTaxType": "20% VAT on Expenses",
"quantity": 1
}
]
}'
Please contact us to set up your tax types
Amount including or excluding tax
When using POST or PUT we will update the lineItemAmountInCents. This means that the listPriceInCents shown above should be provided excluding tax. If you want to provide the amount incl. tax, please use PATCH as shown below
In this example, the line item amount already includes tax
{
...
"lineItems": [
{
"id": "lineitem-id",
"lineItemNumber": 1,
"name": "Expense",
"listPriceInCents": 2400,
"quantity": 1,
"lineItemAmountInCents": 2400
}
]
}
And you want to update the tax without changing the total amount of the line item, you can do this using PATCH:
curl {baseURL}/orders/:order-id/lineitems/:lineitem-id/vatAmountInCents
-H "Authorization:your-api-key"
-H "Content-type: application/json"
-X PATCH
-d '{
"vatAmountInCents": 400
}'
After this call, the lineItemAmountInCents will remain unchanged and only the listPriceInCents and vat will be updated:
{
...
"lineItems": [
{
"id": "lineitem-id",
"lineItemNumber": 1,
"name": "Expense",
"listPriceInCents": 2000,
"vat": 20,
"quantity": 1,
"lineItemAmountInCents": 2400
}
]
}
You can achieve the same by using a PATCH on buyerTaxCode
Updated about 1 year ago