Contents

GET [/instances/$INSTANCE]/private/orders#

Returns known orders up to some point in the past.

Required permission: orders-read

Request:

Query Parameters:

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

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

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

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

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

  • date_s – Optional. Non-negative date in seconds after the UNIX Epoc. Only return orders created after the specified timestamp.

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

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

  • offset – Optional. Starting row_id for an iteration. Since protocol v12.

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

  • session_id – Optional. Since protocol v6. Filters by session ID.

  • fulfillment_url – Optional. Since protocol v6. Filters by fulfillment URL.

  • summary_filter – Optional. Only returns orders where the summary contains the given text as a substring. Matching is case-insensitive. Since protocol v23.

Response:

200 OK:

The response is an OrderHistory.

Details:

interface OrderHistory {
  // Timestamp-sorted array of all orders matching the query.
  // The order of the sorting depends on the sign of limit.
  orders : 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;
}
Contents