taler-docs

get-private-orders.rst (4322B)

---

 .. http:get:: [/instances/$INSTANCE]/private/orders
 
   Returns known orders up to some point in the past.
 
   **Required permission:** ``orders-read``
 
   **Request:**
 
   *Accept*:
     The client may specify the desired MIME-type for the result.
     Supported are the usual "application/json", but also
     "application/vnd.ms-excel", "text/csv" and "application/pdf".
 
   :query paid: *Optional*. If set to yes, only return paid orders, if no only unpaid orders. Do not give (or use "all") to see all orders regardless of payment status.
   :query refunded: *Optional*. If set to yes, only return refunded orders, if no only unrefunded orders. Do not give (or use "all") to see all orders regardless of refund status.
   :query wired: *Optional*. If set to yes, only return wired orders, if no only orders with missing wire transfers. Do not give (or use "all") to see all orders regardless of wire transfer status.
   :query delta: *Optional*. takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` and ``date_s`` are returned.  Defaults to ``-20`` to return the last 20 entries (before ``start`` and/or ``date_s``).  Deprecated in protocol **v12**. Use *limit* instead.
   :query limit: *Optional*. At most return the given number of results. Negative for descending by row ID, positive for ascending by row ID. Default is ``20``.  Since protocol **v12**.
   :query date_s: *Optional.* Non-negative date in seconds after the UNIX Epoc. Only return orders created after the specified timestamp.
   :query max_age: *Optional.* Relative time. Only return orders younger than the specified age. Only applicable if *delta* is positive. If both *max_age* and *date_s* are given, the larger of the two applies. Since protocol **v27**.
   :query start: *Optional*. Row number threshold, see ``limit`` for its interpretation.  Defaults to ``INT64_MAX``, namely the biggest row id possible in the database. Deprecated in protocol **v12**. Use *offset* instead.
   :query offset: *Optional*. Starting ``row_id`` for an iteration.  Since protocol **v12**.
   :query timeout_ms: *Optional*. Timeout in milliseconds to wait for additional orders if the answer would otherwise be negative (long polling). Only useful if ``limit`` is positive. Note that the merchant MAY still return a response that contains fewer than ``limit`` orders.
   :query session_id: *Optional*. Since protocol **v6**. Filters by session ID.
   :query fulfillment_url: *Optional*. Since protocol **v6**. Filters by fulfillment URL.
   :query summary_filter: *Optional*. Only returns orders where the summary contains the given text as a substring. Matching is case-insensitive. Since protocol **v23**.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The response is an `OrderHistory`.
 
   **Details:**
 
   .. ts:def:: OrderHistory
 
     interface OrderHistory {
       // Timestamp-sorted array of all orders matching the query.
       // The order of the sorting depends on the sign of ``limit``.
       orders : OrderHistoryEntry[];
     }
 
 
   .. ts:def:: OrderHistoryEntry
 
     interface OrderHistoryEntry {
 
       // Order ID of the transaction related to this entry.
       order_id: string;
 
       // Row ID of the order in the database.
       row_id: Integer;
 
       // When the order was created.
       timestamp: Timestamp;
 
       // The amount of money the order is for. If the contract
       // has multiple choices and the user has not yet made a choice,
       // we return the amount of the first choice.
       amount: Amount;
 
       // The total amount of refunds granted by the merchant.
       // Includes refunds that the wallet did not yet pick up.
       // Only available if the order was paid.
       // Since **v24**.
       refund_amount: Amount;
 
       // The amount of refunds the customer's wallet did not yet
       // pick up.  Only available if the order was paid.
       // Since **v24**.
       pending_refund_amount: Amount;
 
       // The summary of the order.
       summary: string;
 
       // Whether some part of the order is refundable,
       // that is the refund deadline has not yet expired
       // and the total amount refunded so far is below
       // the value of the original transaction.
       refundable: boolean;
 
       // Whether the order has been paid or not.
       paid: boolean;
     }