Preliminary Order Calculation

Description

The preorder method allows you to perform a preliminary order calculation considering promotions and loyalty program member points.

The request result can be used to display final amounts, discounts, and write-offs before creating the final order.

tip

This method does not create an order in the system; it returns the calculated state of the order with applied market and loyalty rules. To create the calculated order after a successful preorder, use the preorder_commit method.

URL

Method: POST

https://example.com/api/v1.1/market/orders/preorder

Request Parameters

Parameter	Type	Example	Required	Description
token	string	"abcdefghijklmnqrstuvwxyz"	Yes	API token
external_id	string	"12"	Yes	External order ID
matching	string	"email" "phone" "profile_id" "custom"	Yes	Method for searching the loyalty program member profile
email	string	"example@example.com"	If matching = email	Member's email
phone	string	"+79000000000"	If matching = phone	Member's phone number
profile_id	string	"696e304f547840a7286619e0"	If matching = profile_id	Profile ID
data	JSON object	{    "endpoint": "site",    "status": "new",    "currency": "RUB",    "total_price": "139999.00",    "lines": [...] }	Yes	The data object contains order data

tip

The lines field is required and must contain at least one order item.

data object

Parameter	Type	Example	Required	Description
endpoint	string	"bot", "website"	Yes	Order source (touchpoint). Must be configured in the Market module
status	string	"new", "confirmed", "paid"	Yes	Order status. Uses statuses configured in the platform
currency	string	"RUB", "USD", "EUR"	Yes	Order currency (three-letter ISO code)
total_price	string	"2500.00"	Yes	Total order cost before discounts
final_total_price	string	"2150.00"	Yes	Final order cost after applying all discounts
delivery_cost	string	"300.00"	No	Delivery cost
create_time	string (ISO 8601)	"2026-02-18T13:01:05.141Z"	No	Order creation date and time. If not provided, the current server time is used
region	string	"region_moscow"	No	Region identifier for applying regional prices and promotions
lines	array	See "lines array" section below	Yes	Array of order items. Must contain at least 1 element
promocodes	array	See "promocodes array" section below	No	Array of promo codes applied to the order
applied_promotions	array	See "applied_promotions array" section below	No	Promotions applied to this order.
redeem_points	array	See "redeem_points array" section below	Yes, if type="redeem_points" is specified in applied_promotions	Array of point redemptions by point currency types
custom_fields	object	{ "field1": "value1", "field2": "value2" }	No	Order custom fields
tags	array	[ "summer_sale", "first_order" ]	No	Tags for labeling the order

lines array

The array contains information about the order items. Must contain at least 1 item.

Each item is a separate object within the array with the following parameters:

Parameter	Type	Example	Required	Description
external_id	string	"line_1"	Yes	External line ID in the client's system
product	string	"iphone17pmb256"	Yes*	Product identifier
sku	string	"IPHONE17-256-BLACK"	Yes*	SKU identifier
line_number	integer	1	No	Sequential line number in the order
count	integer	1	Yes	Quantity of the product
base_price_per_item	string	"139999.00"	Yes	Base price per unit
min_price_per_item	string	"130000.00"	No	Minimum allowable price per unit
final_price_per_item	string	"139500.00"	Yes	Final price per unit after applying all discounts
status	string	"new"	No	Order line status
custom_fields	object	{"color": "black", "size": "XL"}	No	Line custom fields
applied_promotions	array	See "applied_promotions array" section below	No	Promotions applied to this line.

* — one of the parameters is required: product or sku

promocodes array

The array contains objects with information about promo codes.

A full description of the promo code structure can be found in this article.

Parameter	Type	Example	Required	Description
code	string	"SUMMER20"	Yes	Promo code
pool_id	integer	42	Yes	Promo code pool identifier

redeem_points array

An array with information about loyalty point redemption. Each object describes a separate redemption.

A full description of the point redemption structure can be found in this article.

Parameter	Type	Example	Required	Description
points_currency_iid	integer	1	Yes*	Internal identifier of the point type
points_currency_eid	string	"bonus1"	Yes*	External identifier of the point type
name	string	"Bonus points"	No	Name of the point type
amount	integer	499	Yes	Number of points to redeem

* — one of the parameters is required: points_currency_iid or points_currency_eid

applied_promotions array

tip

The applied_promotions array can be contained both in the data object and in the lines array within that object. In the first case, the array will contain promotions applied to the order, in the second — promotions applied to the products/lines.

An array of promotions applied to the order. Each object in the array describes a separate promotion.

Parameter	Type	Example	Required	Description
type	string	"discount", "accrue_points", "redeem_points", "code_issue", "message"	Yes	Promotion type
promotion	object	"promotion": { "external_id": "promo_1", "name": "Summer Sale" }	Yes	Object with the promotion's identifier and name
amount	string	"150.00"	Yes, if type is discount, accrue_points, or redeem_points	Discount amount or number of points
points_info	object	"points_info": { "points_currency_iid": 1, "points_currency_eid": "bonus1", "name": "Bonus points", "amount": "50" }	Yes, if type is accrue_points or redeem_points	Object with point information

The structure of the points_info object is as follows:

Parameter	Type	Example	Required	Description
points_currency_iid	integer	1	Yes*	Internal identifier of the point type
points_currency_eid	string	"bonus1"	Yes*	External identifier of the point type
name	string	"Bonus points"	No	Name of the point type
amount	string	"6999"	Yes	Number of points
expiration_date	string (ISO 8601)	"2027-02-18T00:00:00.000Z"	No	Expiration date for accrued points

* — one of the parameters is required: points_currency_iid or points_currency_eid

Request Example

JSON

{
  "token": "abcdefghijklmnqrstuvwxyz",
  "external_id": "12",
  "matching": "email",
  "email": "example@example.com",
  "data": {
    "endpoint": "site",
    "status": "new",
    "delivery_cost": "0.00",
    "total_price": "139999.00",
    "currency": "RUB",
    "redeem_points": [
      {
        "points_currency_iid": 1,
        "amount": 499
      }
    ],
    "lines": [
      {
        "external_id": "line___ASTGRf",
        "product": "iphone17pmb256",
        "base_price_per_item": "139999.00",
        "min_price_per_item": "0.00",
        "final_price_per_item": "139999.00",
        "count": 1,
        "custom_fields": {},
        "currency": "RUB"
      }
    ]
  }
}

XML

<xml>
  <token>abcdefghijklmnqrstuvwxyz</token>
  <external_id>12</external_id>
  <matching>email</matching>
  <email>example@example.com</email>
  <data>
    <endpoint>site</endpoint>
    <status>new</status>
    <delivery_cost>0.00</delivery_cost>
    <total_price>139999.00</total_price>
    <currency>RUB</currency>
    <redeem_points>
      <points_currency_iid>1</points_currency_iid>
      <amount>499</amount>
    </redeem_points>
    <lines>
      <external_id>line___ASTGRf</external_id>
      <product>iphone17pmb256</product>
      <base_price_per_item>139999.00</base_price_per_item>
      <min_price_per_item>0.00</min_price_per_item>
      <final_price_per_item>139999.00</final_price_per_item>
      <count>1</count>
      <currency>RUB</currency>
    </lines>
  </data>
</xml>

Response Example

JSON

{
    "data": {
        "profile": {
            "profile_id": "696e304f547840a7286619e0"
        },
        "order": {
            "processing_target": "calculated",
            "total_price": "139999.00",
            "final_total_price": "139500.00",
            "delivery_cost": "0.00",
            "currency": "RUB",
            "lines": [
                {
                    "external_id": "line___ASTGRf",
                    "line_number": 0,
                    "count": 1,
                    "product": "iphone17pmb256",
                    "base_price_per_item": "139999.00",
                    "min_price_per_item": "0.00",
                    "final_price_per_item": "139500.00",
                    "custom_fields": {},
                    "applied_promotions": [
                        {
                            "type": "accrue_points",
                            "promotion": {
                                "external_id": "bonus",
                                "name": "Point Accrual"
                            },
                            "points_info": {
                                "points_currency_iid": 1,
                                "points_currency_eid": "bonus1",
                                "name": "Main Point",
                                "amount": "6999"
                            }
                        },
                        {
                            "type": "redeem_points",
                            "promotion": {
                                "external_id": "bonus",
                                "name": "Point Redemption"
                            },
                            "points_info": {
                                "points_currency_iid": 1,
                                "points_currency_eid": "bonus1",
                                "name": "Main Point",
                                "amount": "499"
                            }
                        }
                    ]
                }
            ],
            "custom_fields": {},
            "applied_promotions": [],
            "points_info": [
                {
                    "points_currency_iid": 1,
                    "points_currency_eid": "bonus1",
                    "name": "Main Point",
                    "status": "success",
                    "active_amount_for_current_order": "20999",
                    "accrue_points_amount_for_current_order": "6999",
                    "redeemed_points_amount_for_current_order": "499"
                }
            ],
            "promocodes_info": []
        }
    },
    "error": 0,
    "error_text": "Successful operation"
}

XML

<xml>
  <data>
    <profile>
      <profile_id>696e304f547840a7286619e0</profile_id>
    </profile>
    <order>
      <processing_target>calculated</processing_target>
      <total_price>139999.00</total_price>
      <final_total_price>139500.00</final_total_price>
      <delivery_cost>0.00</delivery_cost>
      <currency>RUB</currency>
      <lines>
        <external_id>line___ASTGRf</external_id>
        <line_number>0</line_number>
        <count>1</count>
        <product>iphone17pmb256</product>
        <base_price_per_item>139999.00</base_price_per_item>
        <min_price_per_item>0.00</min_price_per_item>
        <final_price_per_item>139500.00</final_price_per_item>
        <custom_fields/>
        <applied_promotions>
          <type>accrue_points</type>
          <promotion>
            <external_id>bonus</external_id>
            <name>Point Accrual</name>
          </promotion>
          <points_info>
            <points_currency_iid>1</points_currency_iid>
            <points_currency_eid>bonus1</points_currency_eid>
            <name>Main Point</name>
            <amount>6999</amount>
          </points_info>
        </applied_promotions>
        <applied_promotions>
          <type>redeem_points</type>
          <promotion>
            <external_id>bonus</external_id>
            <name>Point Redemption</name>
          </promotion>
          <points_info>
            <points_currency_iid>1</points_currency_iid>
            <points_currency_eid>bonus1</points_currency_eid>
            <name>Main Point</name>
            <amount>499</amount>
          </points_info>
        </applied_promotions>
      </lines>
      <custom_fields/>
      <applied_promotions/>
      <points_info>
        <points_currency_iid>1</points_currency_iid>
        <points_currency_eid>bonus1</points_currency_eid>
        <name>Main Point</name>
        <status>success</status>
        <active_amount_for_current_order>20999</active_amount_for_current_order>
        <accrue_points_amount_for_current_order>6999</accrue_points_amount_for_current_order>
        <redeemed_points_amount_for_current_order>499</redeemed_points_amount_for_current_order>
      </points_info>
      <promocodes_info/>
    </order>
  </data>
  <error>0</error>
  <error_text>Successful operation</error_text>
</xml>

Response Parameters

Parameter	Type	Description
data	object	Calculation result data
error	int	Error code
error_text	string	Error description

The data object has the following structure.

Parameter	Type	Description
profile	object	Member profile. Contains the profile identifier
order	object	Calculated order. More details