Skip to end of metadata
Go to start of metadata

The use of OTAPI methods in the documentation is described for OT Box and mobile application for it as an example.

OTAPI methods can be used and varied in the operation of any sites on various CMS.

General work with OTAPI

All methods are available on documentation page:

Send GET/POST request to to get response from api in xml format.

Send GET/POST request to to get response from api in json format.

Add method name and parameters in GET/POST form to the address depending on query and its size. Some parameters may nootherwiset fit in GET query, so it is always easier to make POST.

The ErrorCode node necessarily comes in the response from api, if it is not equal to 'Ok' and not equal to 'BatchError' - it is necessary to process the error. Errors must be separated by value in the ErrorCode and / or SubErrorCode nodes.

Some ErrorCode that can be processed globally at the application level:

  • SessionExpired - buyer's or administrator's session has expired, it's necessary to offer user log in and repeat his actions.
  • AccessDenied - access to this method is forbidden for this user.
  • InstanceKeyBan - application key is blocked, contact managers in your skype chat for details. It's advisable to show "Technical work is done on the site" for application user.

In some cases, the error message must be shown to the user. It is stored in the Errordescription node and comes with the translation for the language specified when querying in the 'language' parameter.

Application start

You need to get application settings when you start it with parameter applicationType=MobileApplication.

Application should get a list of available languages from the settings and provide user with an interface to choose application language (if there is more than one language in the list). Further queries to api are called with this language. When starting, the application should take the first language from the list in the settings, check user session (anonymous or authorized) with this language and get application language from the user’s preferences (for more details see working with the user block).

It is also necessary to request a list of translations for application interface at the start with language and parameter passing applicationType=MobileApplication.

The list of successfully received settings must be cached. It is worth clearing settings cache in the background without slowing down application’s operation with this request. It’s worth clearing cache in background either every N hours or every time the application starts. Settings are the same for the entire application and do not differ for different users.

The first time mobile application starts, it must ask user for permission to receive push notifications. It is necessary to send application push token to the services if the user agreed to receive push notifications. Application should monitor relevance of the push token and update it if necessary in the future.

Receiving session (user authorization)

Working with the user - highlights

Some otapi methods require customer's session parameter. It's necessary to get a session before working with logic for users. Initially, you need to get an anonymous session using method so that the shopping cart, preferences (for example) and so on could be saved on it. All data will be automatically transferred if the previous anonymous session was transferred during authorization. Obtained session must be saved in the application memory and used later for all requests.

Any method using user session may return SessionExpired error, which means that session has expired. In this case you need to transfer user to authorization with the corresponding message, and return user to the place where the error occurred when new session is successfully received.

The easiest way to force session verification by method. It is the least time consuming.


User registration is carried out by method
Check input data before calling this method:

  • Email, Login, Password - obligatory parameters;
  • Password length must be at least 6 characters;
  • Email line is really an email address.

Additional obligatory flag field "I accept the user agreement" should be in the registration form. Registration without this flag is not allowed.

Check Result-> IsEmailVerificationUsed field in the response after successful registration using RegisterUser method. Show message to user "An email was sent to your mail with a link to activation to activate account" if IsEmailVerificationUsed = "true". You need to authorize user immediately (set a new SessionId for him received in response to services) if IsEmailVerificationUsed = "false".

Activation after registration

Together with the message that email was sent, you need to display input field for activation code. You should call when user checks email and enters the code in the application. There is a field Result->SessionId->Value in response ConfirmEmail which contains authorized user session. Based on this session, you must immediately authorize user in the application.


Users' authorization is carried out by method.
Authorization form should contain the following fields: login (userLogin), password (userPassword) and remember me flag (rememberMe). Check input data before calling Authenticate method:

  • userLogin, userPassword are obligatory parameters

sessionId parameter in Authenticate method is the session identifier of an unauthorized customer.

Login as well as user's email can be transferred as userLogin. Probably it is worthwhile to somehow suggest this in the interface.

Social networks authorization

Social Networks Authorization (OT API)

Get the list of available social networks in settings from GetCommonInstanceOptionsInfo depending on current language, since for example admin can leave VKontakte for Russian and remove for English. Check in TranslatableOptions->choice by language->ExternalAuthentications.

Password recovery

Password recovery is done by method.  
Field userIdentifier may contain user login or email. After calling RequestPasswordRecovery, show user the message "Further instructions were sent to your email" and display a form with confirmation code and two text fields for entering the password. User checks code in the email, returns to the application, enters the code and new password. If both fields with password match, then you need to call ConfirmNewPassword response has Result-> SessionId-> Value field that contains an authorized user session. Based on this session, you need to authorize user in the application immediately.

Application home page

Social networks authorization

Get collections

Use method to get collections. We pass the following parameters at the first request:

and parameter applicationType=MobileApplication. Received data for each collection has a serial number for sorting <Order> 0 </Order>, you need to display collections on the application screen according to this sorting. It is recommended to show collections only from cache. Collections in cache must be updated in background: every 60 minutes, request BatchSearchRatingLists method and save result in the cache. When receiving a response, you need to check HasTranslateErrors node (, if the node is "true", then you do not need to cache the response. You must check HasError node ( for each RatingList element in the response, if the node is true, then this collection item does not need to be cached.

Thus, we get a situation when buyer sees collections from cache. At the same time, collections in the cache have no errors. Situation is possible when we show user outdated information, while we are sure that this information is error-free.

Get banners

You can get a full list of banners configured for application by method, passing applicationType=MobileApplication parameter.

Each banner will have its name, image address, type of action, and action parameter. The current types of actions and the meaning of their parameters are listed below.

The current types of actions and their parameters purpose are listed below:

Action typeParameter


Absolute address of the link to open when you click banner


ID of the category that should be opened when clicking the banner

Short categories menu


Social networks


User Preferences

  • Currencies. The list of available currencies must be shown from application settings GetCommonInstanceOptionsInfo Currencies node.
  • Delivery country. The list of available countries must be shown from application settings GetCommonInstanceOptionsInfo DeliveryCountries node. The list of countries must be displayed taking into account current language of application (all translations can be found in TranslatableOptions node).
  • Application language. Show the list of available application languages from application settings GetCommonInstanceOptionsInfo Languages node.

Customer may have a number of preferences-settings on which otapi answers or behavior of the system / application depend on in the future.

You can get currently selected preferences using method.

User preference can be changed using method.

Application interface should allow users to change their preferences.

Categories list

Send a request first: - we get a list of website root categories. This list can be cached for 24 hours. Then make a separate request for attempt to expand each category - Each list can be also cached for 24 hours using parent category identifier in the key.

category contains other categories (that is it can be expanded) if the flag <IsParent> true </IsParent> has come for it.

Don't show category in catalog if it is hidden <IsHidden>true</IsHidden>.

Flag <IsVirtual>true</IsVirtual> means that category doesn't contain goods (only other subcategories).

Absolute image address for category can be returned (image is set by administrator in admin panel) in the optional <IconImageUrl> node </IconImageUrl>.

Recomended vendors page method, xmlSearchParameters=


FrameSize - number of vendors on the page, TotalCount will be returned in the response - the total number of recommended vendors. You can draw pagination based on TotalCount and FrameSize.

Recomended brands page method, xmlSearchParameters=


FrameSize - number of brands on the page, TotalCount will be returned in the response - the total number of recommended brands. You can draw pagination based on TotalCount and FrameSize.

Vendors display

The following properties should be used on recommended vendors page, in product card in vendor's block, for viewing all goods of vendor and for displaying information about the vendor:

Where to show
DisplayNamevendor nameeverywhere

Thanks to this, website admin will be able to change names later, but nothing will change in Mobile Application logic.

DisplayPictureUrlvendor imageeverywhere

Only if available, otherwise there is an image stub in recommended vendors, do not display in other places.

Thanks to this, website admin will be able to change images but nothing will change in Mobile Application logic.


Credit/Levelvendor rating from 1 to 20

in product card
on vendor's page

Only if available and more than 0, otherwise it does not need to be displayed.
Credit/TotalFeedbacksnumber of feedbacksin product card
on vendor's page
Only if available and more than 0, otherwise it does not need to be displayed.
Credit/PositiveFeedbacksnumber of positive feedbacksin product card
on vendor's page
Only if available and more than 0, otherwise it does not need to be displayed.
Display as% of total reviews if available.
Scores/DeliveryScoredelivery scrore from 1.0 to 5.0in product card
on vendor's page

Only if available and more than 0, otherwise it does not need to be displayed.

Scores/ItemScoreitem score from 1.0 to 5.0in product card
on vendor's page

Only if available and more than 0, otherwise it does not need to be displayed.

service score from 1.0 to 5.0
in product card
on vendor's page

Only if available and more than 0, otherwise it does not need to be displayed.

Basic documentation on search.

Use only one convenient search method to search for goods:

To open a category / seller / brand or search query for the first time, call BatchSearchItemsFrame method with the blockList parameter: SubCategories,HintCategories,Vendor,Brand,Category,RootPath,SearchProperties,AvailableSearchMethods. Send search parameters in xmlParameters (for example, category ID <CategoryId>otc-3</CategoryId> or search or search query <ItemTitle>dress</ItemTitle>). We recommend sending <UseOptimalFrameSize>true</UseOptimalFrameSize> with search parameters. This will allow to get optimal number of products per page for this request.

Display information received in the response.

AvailableSearchMethods node contains all search methods available for current query. Allow customer to change search method if there are more than one search methods.

Find detailed information about the current search method that the query is now made in Items node, using values from Provider and SearchMethod nodes (for example: <Provider> Taobao </Provider> <SearchMethod> Extended </SearchMethod>) in AvailableSearchMethods. Using this information we provide user with filters available on the current search page. The correspondence of fields from information about search method and search parameters can be found in basic documentation.

Show SubCategories (Subcategories), HintCategories (You may be interested) to user. Categories that match current search query (Specify category) come up in Items - Categories node. Show goods from Items - Items node. Check the flag IsSellAllowed = true and SellDisallowReason = "IsFiltered" for the product - then we show the stub for the product - product is not allowed for purchase. Show error: NotFound - product was deleted, NotAvailable - product is unavailable instead of product image if product ErrorCode is not equal to "OK". For all other error codes just show the word "Error".

It is a good practice to change display depending on which nodes are returned in response to BatchSearchItemsFrame request. If:

  • Vendor node has arrived, show user vendor's page with vendor description;
  • Brand node has arrived, show brand page with brand description;
  • Category node has arrived, show category page with category description;
  • Otherwise, a regular search page by phrase.

This approach will allow you to localize search logic and services will be responsible for page display logic.

Product card

Use when you open the card for the first time, it's necessary to send the following parameters: RootPath,Vendor,MostPopularVendorItems16,Description

Show product card:

  • Breadcrumbs categories for this product (RootPath).
  • Title (Item.Title).
  • Video (Item.Videos) and photo (photos are available in 3 sizes: small, middle, big), always show the first image from the list as the main photo.
  • Optionally, you can show product features (show all Item.Features that have DisplayName) and weight (Item.Weight).
  • Optionally, you can show vendor information Vendor and his several products VendorItems.
  • All product properties (Item.Properties) and product description (Description) occupy most of the screen, they are usually displayed at the bottom of the card.
  • Display a list of all product configurations (Item.Configurators, where Item.Configurators.Property is a property and Item.Configurators.Property.Value is the value of the property).
  • If there is MultiInputPropertyId attribute of Item.Configurators.Property node, this property must be presented as a table with the ability to select the amount of each value of this property, for example, .

Show product price:

use method, it's necessary to send the following parameters: AdditionalPrices (the first request can be made with an empty xmlRequest)

  • Check ability to buy this product and the reason to cancel purchase (Configuration.Availability). 
  • Note which properties are selected by user (Configuration.Configurators.Property.Value - Selected = "true"), and which are not available for selection (Configuration.Configurators.Property.Value - Disabled = "true").
  • Display dependence of price on quantity (if QuantityRanges node has arrived).
  • If MultiInputConfigurations node has arrived, then show price of each configuration from MultiInputConfigurations, otherwise show price from Current node:
    • Price - price for 1 item (show price range instead of one price if there are Min and Max attributes);
    • OldPrice - price without discount for 1 item (node is absent if there is no discount);
    • DiscountPercent - discount % for OldPrice (node is absent if there is no discount);
    • InternalDelivery - internal delivery price (don't show if there is no node);
    • AvailableQuantity - available quantity for purchase.
  • Display total cost from TotalCost node.
  • Add information about possible added price (AdditionalPrices).
Allow buyer to choose configuration and its quantity (input field is one if there is no MultiInputPropertyId, enter quantity for each value of MultiInputPropertyId property if there is MultiInputPropertyId). Send a new BatchGetSimplifiedItemConfigurationInfo request with selected configuration and quantity after each "property change" and "quantity change". Examples of xmlRequest:


 Customer did not choose anything
<Request />
equal to
    <Current />
equal to
    <Current Quantity="1" />
 Request with quantity in a product without options at all or without selected options
    <Current Quantity="5" />
Request to current options:
    <Current ConfigurationId="idconfiguration" />
    <Current ConfigurationId="idconfiguration" Quantity="5" />
        <Property Id="idcolor" ValueId="idRed"
        <Property Id="idcolor" ValueId="idRed"
        <Property Id="idSize" ValueId="idMiddle"
    <Current Quantity="5">
        <Property Id="colorid" ValueId="idRed"
        <Property Id="idSize" ValueId="idMiddle"
        <Property Id="idModel" ValueId="idSomeModel"
 Request with selected other configurations
    <Selected ConfigurationId="idConfiguration" Quantity="1" />
    <Selected ConfigurationId="idConfiguration" Quantity="2" />
    <Selected Quantity="1">
        <Property Id="idColor" ValueId="idRed"
        <Property Id="idSize" ValueId="idMiddle"
    <Selected Quantity="2">
        <Property Id="idColor" ValueId="idGreen"
        <Property Id="idSize" ValueId="idMiddle"

A query with everything together can be any combination of other types of queries, for example:
    <Current Quantity="5">
        <Property Id="idColor" ValueId="idRed"
    <Selected Quantity="2">
        <Property Id="idColor" ValueId="idGreen"
        <Property Id="idSize" ValueId="idMiddle"

What's Current/Selected - and what's correct? Current or Selected?

If you need only 1 simultaneously selected config, then you can not think about Selected at all.
If you need several (as in 1688), then in Selected send everything where the quantity is entered.


Favourite goods

Get list of items , blockList=Note.

Add item to favorites: , fieldParameters=<Fields/>

Remove item from favorites: , confirmation to delete is required before removing.

Move item into cart:

Change item quantity in favorites:

Change comment , <Fields><FieldInfo Name="Comment" Value="Text for comment"/></Fields>

Change item configuration:
1. you can get available configurations by the following methods and - similar to item card.
2. new configuration is saved by adding a new one and deleting the old one, i.e. consecutive calls (it is important to pass all fieldParameters from the old record into the method, otherwise you may lose some of information, for example, user’s comment on a product) and 

Favourite sellers

Vendors list: , blockList=FavoriteVendors

Add vendor to favorites: , fieldParameters=<Fields/>

Remove vendor from favorites: , confirmation to delete is required before removing.


Get list of items: , blockList=Basket.

The list of goods should be divided by providers, as you can order goods of only one provider in one order. User should be notified about minimum order amount (if it is set in configuration), you can get it using method (Result->Order->MinOrderCost)

Remove item from cart: , confirmation to delete is required before removing.

Empty cart , confirmation to delete is required before removing.

Move selected item from cart to favorites: several calls are made to transfer several marked products MoveItemFromCartToNote

Change quantity of items in the cart:

Add/edit comment to item: <Fields><FieldInfo Name="Comment" Value="Comment text"/></Fields>

Edit item weight: <Fields><FieldInfo Name="Weight" Value="New weight of an item"/></Fields>

Edit item configuration:
1. you can get available configurations by and methods - similar to item card.
2. new configuration is saved by adding a new one and deleting the old one, i.e. consecutive calls (it is important to pass all fieldParameters from the old record into the method, otherwise you may lose some of information, for example, user’s comment on a product) and 


Get basic information about user (name, email, etc.): , you can edit this information with method.

Delivery address. Delivery address is created and edited separately from basic information about the user. N delivery addresses are possible in total where N is taken from the setting UserProfile->MaxProfilesCount. Methods for working with delivery address:

Interface is required for user that allows to select default profile . Selected profile must be saved in user preferences: , ProfileId field.

Get a list of content pages for profile screen: , parameters:


Get list of countries for delivery: .

Get list of cities:  (while user enters characters to search for the city, i.e. QueryText parameter is empty, you need to send IsMainCity = true to get a list of default cities). When user selects city from the list, save it in the City profile and CityCode profile and automatically fill in the Region field.

Important: CountryCode - obligatory field for placing an order, CityCode - optional field, system must transfer the code to the services if user selected a city from the list. Save only City node if user entered city that is not in SearchCities list.

Orders list

Active: <OrderSearchParametersForUser><IsCancelled>false</IsCancelled><IsCompleted>false</IsCompleted></OrderSearchParametersForUser>

Cancelled: <OrderSearchParametersForUser><IsCancelled>true</IsCancelled></OrderSearchParametersForUser>

Completed: <OrderSearchParametersForUser><IsCompleted>true</IsCompleted></OrderSearchParametersForUser>

The list of fields to display:

  • Order ID passed in API into all possible methods: Id
  • Order number displayed to buyer: DisplayId
  • Order date: CreatedDateTime
  • Statusс: StatusName
  • Sum: TotalAmount
  • Already paid: TotalAmount minus RemainAmount
  • For payment: RemainAmount
  • Goods price: GoodsAmount
  • Items positions: do not show this field if there is no such information

Order. Detailed information

Get order information:

Display order information for user (OrderInfo node, details here, properties:

Display goods list in the order (SalesLinesList node, details about each line is here

Shippings list -

Order. Placing an order and choosing delivery method

You can place goods of only one provider into one order.

When placing an order, you will need a form for choosing delivery address or, if an address was previously created, a form for creating delivery address / s (delivery profile documentation anchor).

When placing an order, you will need to select a delivery method from provided list: request, xmlSearchParameters parameters:

  • ProviderType - provider ID;
  • Weight - goods weight, you will need to get a list of goods by method in case of making order from the cart, get the sum of each item weight (for each product you need to multiply item weight by ordered quantity);
  • CountryCode - delivery country code from selected delivery address;
  • CityCode - delivery city code from selected delivery address.

Parameters example: <DeliveryModeSearchParameters><CountryCode>RU</CountryCode><CityCode>7700000000000</CityCode><Weight>75.000</Weight><ProviderType>Taobao</ProviderType></DeliveryModeSearchParameters>.

IsPickupPointMode flag must be considered when displaying delivery methods.

  • Show user Delivery address and zip code fields (take field values from selected delivery address) if flag = false.
  • Take delivery address and zip code from selected pickup location if flag = true. Provide user with an interface for choosing a pick-up point: show all available pick-up points for current delivery method (by default, the pick-up point must be selected, which is stored in selected address / delivery profile).

Save ExternalDeliveryId to user preferences after successful order ( as well as update delivery address parameters, if the interface has not done it immediately (

From cart

"check" relevance of prices and possibility to buy before placing an order from the cart:

  • call method with selected cart identifiers after customer checked off goods that he wants to buy, we get and save "activity identifier" in response;
  • show overlay to client and a phrase "Please wait. Products in the cart are checked for availability. Verification time depends on quantity of goods in the cart" and progress bar;
  • call function passing  activity identifier to it;
    • show the progress to the customer from ProgressPercent node and call GetBasketCheckingResult method in one second again if there is no error in the response and IsFinished! = true;
    • show text and status (display status by changing line color, Ok - green, Warning - yellow, Error - red) from Messages node for necessary item in the cart 
    • if IsFinished == true hide progress bar and 
      • scroll the screen to the first error and allow customer to correct the error (for example, select different quantity of products and run checking the cart again) if there is at least one Error in Messages;
      • scroll the screen up to the first warning and allow customer to click "place order" button again if there are no errors, but there is at least one Warning. Clicking again should immediately start the process of placing an order without checking the cart again (important: cart checking process should start again if customer changed quantity, configuration or ticked other products);
      • immediately open checkout screen if there are no errors or warnings.

It is important to start cart checking again each time customer changes selected products, as well as re-display error / success messages from the services.

You can place an order "from the cart" calling method, passing:

Follow-up Order

Allow customer to make a follow-up order (if customer has such an opportunity) when making an order. Get orders that allow to make a follow-up order, call with parameters xmlSearchParameters= <OrderSearchParametersForUser><ProviderType>IDProvider(for example, Taobao)</ProviderType><IsAvailableForRecreation>true</IsAvailableForRecreation></OrderSearchParametersForUser>. Allow customer to choose if he makes a new order or a follow-up order if there are such orders. Call method for follow-up order.

Quick order

It is possible to make an order from item card by "Quick order" button. Call method sending:

  • a list of ordered goods (for quick ordering from card from, these are several products of different configurations). It is necessary to pass product ID, configuration ID and quantity for each product (no other parameters need to be passed);
  • delivery method
  • customer profle
  • optional: comment for the order.

Order payment and recharging personal account

If the order is not paid, be sure to offer customer to pay it. Call method if there are funds in customer's personal account, AvailableAmount node (definitely use CurrencySign for display), offer customer a button that will pay for the order from personal account. Write available payment amount on the button, this should be RemainAmount from order information (provided that personal account has more than RemainAmount) or AvailableAmount (provided that personal account is less than RemainAmount).

Call method when clicking the button and refresh order page.

Order can be paid through payment systems. Request a list of available payment systems: . Image of PS - AbsoluteImageUrl, name of PS - Name. Display "Pay" button after clicking payment system and display email input field if CustomField node == "Email", display phone number input field if CustomField node == "Phone".

Call after clicking "Pay" button. Pass the following parameters: Amount (RemainAmount from order information), CurrencyCode, PaymentSystemId, OrderId, SuccessUrl and FailUrl return addresses that application can intercept.

Form http-form based on received response, open it in browser and submit it:

  • RequestUrl - url to send the form to;
  • RequestMethod, if it doesn’t come, send a POST form (sometimes you have to send GET, according to parameter);
  • IsNewWindow - you need to open the form in a new window or in the current one, parameter is apparently not relevant for a mobile application - we always open request in a new browser window;
  • IsIFrame - display iframe src={RequestUrl}?{Parameters type param1=value1&param2=value2} in browser instead of form;
  • IsImmmediate - ignore in mobile application at the moment;
  • Parameters - list of payment parameters to be processed depending on property IsUserData7
    • parameter must be inserted into the form to pass to payment system if IsUserData==false;
    • display parameter on the screen if IsUserData==true.

Customer’s personal account will be replenished by Amount if you don't pass OrderId into GetPaymentParameters method.

Browser will return to one of the transmitted addresses after successful or unsuccessful payment, accordingly application should intercept them, close browser and show appropriate screen.

  • No labels