Getting orders

This page explains how to get orders and has the following sections:

• Getting orders
• Getting a single order
• Getting receipts and invoices

Orders can also be viewed in our mobile app or in the orders section of our web app

The orders API in this tutorial returns all details for all orders using basic filters. You can also create custom reports with more complicated filters or only including the fields you need. How to do that is described in this tutorial.

Getting orders

Getting a list of all your orders is done as follows:

curl {baseURL}/aggregate/orders?orderStatus=APPROVED&eventStatus=PAYMENT_DUE&buyerUserId=user-id&buyerTagValues=EXPENSE&q=abc 
-H "Authorization:your-api-key"  
-X GET

The following parameters can be used in combination:

• orderStatus filters on order status, e.g. "?orderStatus=APPROVED" returns all approved orders
• eventStatus filters on order status, e.g. "?eventStatus=FOR_CONFIRMATION" returns all orders where at least one of the events is FOR_CONFIRMATION
• userId filters on orders where this user is the buyerUser or sellerUser
• buyerTagValues filter, e.g. "?buyerTagValues=EXPENSE" returns all expenses
• q: specifies a search query. The orderId, description, buyerOrderReference, sellerOrderReference, companyTradingName, buyerUserEmail and buyerCostAllocation.budgetName will be searched for the specified string

There are also filters that help with pagination:

• size specifies the number of results to be returned. The default is 10
• sort defines the sort order of the returned orders, e.g. "?sort=creationDate,desc" sorts orders by creation date in descending order. ''asc" is used for ascending order.
• page is the page number of the results to be returned, e.g. "?page=0" is the first page of the results

All parameters can be combined to return the orders you are looking for.

The response is as follows:

{
  "content": [
    { 
      "id" : "order-id",
      "buyerId" : "your-trader-id",
      "buyerCompanyTradingName": "Buyer Name",
      "sellerId" : "other-trader-id",
      "sellerCompanyTradingName": "Seller Name",
      "description": "My order",
      "orderAmountInCents": 100000,
      "orderCurrency": "USD",
      "orderCurrencyExponent": 2,
      "status": "NOT_APPROVED",
      "creationDate": "2016-11-06",
      "modificationDate": "2016-11-06",
      "events": [
        {
          "id": "event-id-1",
          "pctToBePaid": 100,
          "eventName": "Order approved",
          "paymentName": "Full payment",
          "eventNumber": 1,
          "amountToBePaidInCents": 30000,
          "status": "NOT_STARTED",
          "confirmers": [
             "BUYER"
          ],
          "confirmed": false,
          "documentsRequired": [
             "invoice"
          ]
        }
    }
  ]
}

What each of these fields means is described in the orders tutorial.

Getting a single order

Getting a single order can be done like this:

curl https://api.yordex.com/v1/aggregate/orders/order-id  
-H "Authorization:your-api-key"  
-X GET

Getting receipts and invoices

Receipts and invoices are always linked to events. See here for an explanation of what events are.

The best way to retrieve receipts is by going to the spend page in the web app, choosing "Export" and then choosing "Export invoice files".

If you wish to export receipts and invoices by API, you can call the following API:

curl {baseURL}/documents?orderId=:order-id
-H "Authorization:your-api-key"  
-X GET

The response will look like this:

{
    "documents": [
        {
            "id": "document-id",
            "location": "{baseURL}/documents/download/document-id",
            "fileName": "invoice.pdf",
            "type": "INVOICE",
            "orderId": "order-id",
            "eventId": "event-id",
            "documentDate": "2021-10-03",
            "customerDocumentId": "INV-001"
        }
    ]
}

This API call will return all invoices for that order. To get the invoice of just one event you can call the API with an eventId filter.