listOrders method

Description

Getting a list of orders and their properties.

Address for calling the listOrders operation

https://server:port/webservice/mws/api/listOrders

Request parameters

Parameter

Type

Description

requestDT

dateTime

Date and time of the request according to time in the merchant's system. Required parameter.

outputFormat

normalizedString

Format for the request results. Acceptable values — XML or CSV.

Optional parameter; XML by default.

csvDelimiter

string, 1 character

Value delimiter for CSV format. Must not be the quotation mark character (").

Optional parameter: semicolon (;) by default.

shopId

long

ID of the store that the list of orders is being requested for.

If this parameter is omitted, orders are returned for the shopId that this MWS user has rights to get lists of orders for.

orderCreatedDatetimeGreaterOrEqual

dateTime

Lower bound of the order creation time.

Selects orders that were created at the time or later than the time set in this parameter.

orderCreatedDatetimeLessOrEqual

dateTime

Upper bound of the order creation time.

Selects orders that were created at the time or earlier than the time set in this parameter.

paid

boolean

If this parameter is set to true, only paid orders are returned.

If this parameter is set to false, only unpaid orders are returned.

If this parameter is omitted, both paid and unpaid orders are returned.

paymentDatetimeGreaterOrEqual

dateTime

Lower bound of the order payment time.

Selects orders that were paid at the time or later than the time set in this parameter.

paymentDatetimeLessOrEqual

dateTime

Upper bound of the order payment time.

Selects orders that were paid at the time or earlier than the time set in this parameter.

invoiceId

long

Unique transaction number in Yandex.Checkout.

orderNumber

string, maximum of 64 characters

Unique order number in the merchant's system.

This parameter can be used if Yandex.Checkout gets order numbers from the merchant and stores them.

outputFields

string, maximum of 4000 characters

List of order properties that should be output in the request execution results.

Names in the list are separated by a semicolon (;).

Default value:

shopId;shopName;articleId;articleName;invoiceId;orderNumber; paymentSystemOrderNumber; customerNumber; createdDatetime;paid;orderSumAmount; orderSumCurrencyPaycash;orderSumBankPaycash;paidSumAmount; paidSumCurrencyPaycash;paidSumBankPaycash;receivedSumAmount; receivedSumCurrencyPaycash;receivedSumBankPaycash; shopSumAmount;shopSumCurrencyPaycash;shopSumBankPaycash; paymentDatetime;paymentAuthorizationTime;payerCode; payerAddress;payeeCode;paymentSystemDatetime; avisoReceivedDatetime;avisoStatus;agentId;uniLabel;environment

The complete list of order properties is specified in the Response parameters table.

Restriction. 

At least one of the following conditions must be in the parameters of the request for the list of orders:

  • Transaction number (invoiceId) and the store ID (shopId).
  • Order number (orderNumber) and the store ID (shopId).
  • Time range of order creation (orderCreatedDatetimeGreaterOrEqual and/or orderCreatedDatetimeLessOrEqual);
  • Time range of order payment (paymentDatetimeGreaterOrEqual and/or paymentDatetimeLessOrEqual).

For requests by transaction number (invoiceId) or order number (orderNumber), the request must specify the store ID (shopId).

Note.  For requests that restrict the results by the time range of order creation or payment, the following rules apply:
  • If only one bound is set for the time range of order creation or payment, the default value is taken for the second one. The default value for the upper bound is the current time in the Yandex.Checkout service. The default value for the lower bound is the time of the upper bound specified in the request, minus 24 hours.
  • If the time range for order payment is set, the request must include the paid parameter set to true.
  • The length of a time range restricting the results must not be longer than 31 days.
  • The number of records in the results must not exceed 10,000.

Response parameters

Parameter

Type

Description

orderCount

int

Number of orders in the results.

Response header field. Present for a successful selection of the list of orders (listOrders).

shopId

long

Merchant ID issued by Yandex.Checkout during activation.

articleId

long

Yandex.Checkout product ID.

shopName

string, maximum of 64 characters

Store name.

articleName

string, maximum of 128 characters

Product name.

invoiceId

long

Unique transaction number in Yandex.Checkout.

orderNumber

string, maximum of 64 characters

The order number in the merchant's system.

If the Yandex.Checkout service gets order numbers from the merchant and stores them, this parameter contains the order number from the merchant's system. Otherwise, this property contains the Yandex.Checkout transaction number.

paymentSystemOrderNumber

string, maximum of 40 characters

Yandex.Checkout transfer ID.

Present only for paid orders.

customerNumber

string, maximum of 64 characters

The customer ID from the merchant's system (sent in the payment form).

This could be a unique username, mobile phone number, contract number, and so on, depending on the store.

createdDatetime

dateTime

Time when the order was registered in Yandex.Checkout.

paid

boolean

Set to true if the order was paid for, otherwise false.

paymentDatetime

dateTime

Time of order payment in Yandex.Checkout.

This value is included in the response only for paid orders.

paymentAuthorizationTime

long

Order number in the Yandex.Money processing center.

This value is included in the response only for paid orders.

payerCode

YMAccount

Payer's account number.

This value is included in the response only for paid orders.

payerAddress

string, maximum of 33 characters

Payer's IP address, if known.

This value is included in the response only for paid orders.

payeeCode

YMAccount

Account number of the transfer recipient when the order was paid.

This value is included in the response only for paid orders.

paymentSystemDatetime

dateTime

Time order payment was registered in Yandex.Money processing center.

This value is included in the response only for paid orders.

avisoReceivedDatetime

dateTime

Time order payment was registered in the merchant's system.

Present if the merchant received notification of this payment at the time of request.

avisoStatus

int

Status code for the Payment notification. List of status codes for notifications of payments

avisoRegistryId

long

Number of the report on accepted payments that contains this order. May be omitted in the response.

orderSumAmount

CurrencyAmount

Order amount.

orderSumCurrencyPaycash

CurrencyCode

Currency code for orderSumAmount.

orderSumBankPaycash

CurrencyBank

Code of the processing center for orderSumAmount.

contractAmount

CurrencyAmount

The amount of the payment in the currency of the payer's account. May be omitted in the response.

contractCurrency

CurrencyCode

Currency code of the payer's account. May be omitted in the response.

paidSumAmount

CurrencyAmount

The amount paid by the Payer.

This value is included in the response only for paid orders.

paidSumCurrencyPaycash

CurrencyCode

Currency code for paidSumAmount.

This value is included in the response only for paid orders.

paidSumBankPaycash

CurrencyBank

Code of the processing center for paidSumAmount.

This value is included in the response only for paid orders.

shopSumAmount

CurrencyAmount

The amount that is credited to the merchant's account: the order amount, minus the Yandex.Money commission.

shopSumCurrencyPaycash

CurrencyCode

Currency code for the amount that is credited to the merchant's account.

shopSumBankPaycash

CurrencyBank

Processing center code for the amount that is credited to the merchant's account.

receivedSumAmount

CurrencyAmount

The amount that Yandex.Money receives from the Payer.

This value is included in the response only for paid orders.

receivedSumCurrencyPaycash

CurrencyCode

Currency code for receivedSumAmount.

This value is included in the response only for paid orders.

receivedSumBankPaycash

CurrencyBank

Code of the Yandex.Money processing center for receivedSumAmount.

This value is included in the response only for paid orders.

paymentFormParams

string

Payment form parameters.

The value is shown in the response only for stores that have the "save payment form parameters" option set.

paymentType

normalizedString

Payment method

agentId

long

Yandex.Money internal parameter. May be omitted in the response.

uniLabel

string

Unified transaction label in the Yandex.Money service.

clearing string

Confirmation status of a payment deferred by the merchant. Possible values:

  • none — payment not confirmed
  • sale — payment confirmed
  • cancel — payment canceled.

This value is present in the response if the store is set up for deferred payments, and transmitting information about these payments is allowed in the response to listOrders.

environment string

Order status allows for distinguishing real and test operations. Possible values:

  • Live — real operation
  • Test — test operations.
Tip. If you want to get information about deferred payments in the request for the list of successful payments, contact a Yandex.Checkout manager.

Examples

Example of a successful response in XML format
<?xml version="1.0" encoding="utf-8"?>
<listOrdersResponse status="0" error="0"
                    processedDT="2011-08-02T14:50:25.089+03:00"
                    orderCount="2">
    <order shopId="1" articleId="2" invoiceId="2000024720731"
           shopName="Your Store"
           articleName="Ear-flapped hat"
           orderNumber="14828233603000"
           paymentSystemOrderNumber="483536611593030008"
           customerNumber="800350518"
           createdDatetime="2011-08-02T14:43:30.676+03:00"
           paid="true"
           orderSumAmount="17.28"
           orderSumCurrencyPaycash="643"
           orderSumBankPaycash="1003"
           paidSumAmount="17.28"
           paidSumCurrencyPaycash="643"
           paidSumBankPaycash="1003"
           receivedSumAmount="17.28"
           receivedSumCurrencyPaycash="643"
           receivedSumBankPaycash="1003"
           shopSumAmount="17.28"
           shopSumCurrencyPaycash="643"
           shopSumBankPaycash="1003"
           paymentDatetime="2011-08-02T14:43:31.593+03:00"
           paymentAuthorizationTime="483536611593030008"
           payerCode="41003422841475"
           payerAddress="192.168.1.127"
           payeeCode="41003131475668"
           paymentSystemDatetime="2011-08-02T14:43:31.593+03:00"
           avisoReceivedDatetime="2011-08-02T14:43:31.298+03:00"
           avisoStatus="1000"
           paymentType="AC"
           agentId="200002"
           uniLabel="1cd18622-0004-5000-8000-01d1aac3555b"
           environment="Live"    
            />
    <order shopId="1" articleId="2" invoiceId="2000024720733"
           shopName="Your Store"
           articleName="Ear-flapped hat"
           orderNumber="40522286348326"
           paymentSystemOrderNumber="483536613043117008"
           customerNumber="810844412"
           createdDatetime="2011-08-02T14:43:32.203+03:00"
           paid="false"
           orderSumAmount="2.08"
           orderSumCurrencyPaycash="643"
           orderSumBankPaycash="1003"
           paidSumAmount="2.07"
           paidSumCurrencyPaycash="643"
           paidSumBankPaycash="1003"
           environment="Live"    
            />
</listOrdersResponse>
Note. 

If the value of any property can't be defined (for example, the time of transfer for an unpaid order), the corresponding attribute will be omitted from the XML response.

Example of a successful response in CSV format
status=0;error=0;processedDT=2011-08-02T14:46:58.096+03:00;orderCount=2

shopId;shopName;articleId;articleName;invoiceId;orderNumber;paymentSystemOrderNumber;customerNumber;createdDatetime;paid;orderSumAmount;
orderSumCurrencyPaycash;orderSumBankPaycash;paidSumAmount;paidSumCurrencyPaycash;paidSumBankPaycash;receivedSumAmount;receivedSumCurrencyPaycash;
receivedSumBankPaycash;shopSumAmount;shopSumCurrencyPaycash;shopSumBankPaycash;paymentDatetime;paymentAuthorizationTime;payerCode;payerAddress;payeeCode;
paymentSystemDatetime;avisoReceivedDatetime;avisoStatus;paymentType;agentId;uniLabel;environment
 
1;"Your Store";2;"Ear-flapped hat";2000024717776;"2011.08.02 09:07:32";483512879684006008;97881;2011-08-02T08:07:59.148+03:00;true;10.15;643;1003;10.15;643;
1003;10.15;643;1003;10.15;643;1003;2011-08-02T08:07:59.684+03:00;483512879684006008;41003476047679;192.168.1.127;41003131475668;2011-08-02T08:07:59.684+03:00;
2011-08-02T08:07:59.660+03:00;1000;AC;200002;1cd12967-0001-5000-8000-000000034fd8;Live


1;"Your Store";2;"Ear-flapped hat";2000024717780;2000024717780;483512937773006008;770367;2011-08-02T08:08:57.175+03:00;true;10.00;643;1003;10.00;643;
1003;10.00;643;1003;10.00;643;1003;2011-08-02T08:08:57.773+03:00;483512937773006008;41003494819180;192.168.1.127;41003131475668;2011-08-02T08:08:57.773+03:00;
2011-08-02T08:08:57.730+03:00;1000;AC;200002;1cd129a4-0001-5000-8000-000000034fe1;Live
Example of error messages in XML format
<listOrdersResponse 
         status="3" error="111"
         processedDT="2011-07-02T20:38:01.000+04:00"
         techMessage="Invalid value for the requestDT parameter"
         />
Example of error messages in CSV format
status=3;error=111;processedDT=2011-07-21T13:20:14.869+04:00;”techMessage=Invalid value for the requestDT parameter”

See also