Skip to main content

Purchases and Main Methods for Working with Them

Purchase Creation​

Transmitting information about a client and a purchase to the Sailplay server is performed using the /api/v2/purchases/new/ method.

In addition to authorization data, the following must be passed in the request:

  • JSON object cart with the cart composition or
  • cart identifier cart_id obtained at the promotion calculation stage (see the "Promotion Calculation for Cart" page),
  • your unique internal order number — order_num.

If business logic involves making anonymous purchases, passing a client identifier in the request is not required.

The number of bonus points for deduction in a purchase is passed in the discount_points_writeoff parameter.

Important

If a client identifier with a value that is not in the database is passed in the purchase creation request, the client will be created during purchase creation only with this identifier. Similarly, it will happen with a product: if there is a product SKU in the purchase creation request that is not in the database, the product will be created with the purchase using this SKU.

Purchase Creation in Another Department​

The /api/v2/purchases/new/ method allows creating a purchase in a department different from the one specified in store_department_id.

To do this, one of the parameters must be passed in the request:

  • target_dep_id — department identifier in Sailplay;
  • target_dep_origin_id — your internal department identifier specified during its creation.

Retrieving a Purchase​

To retrieve information about created purchases, the /api/v2/purchases/get/ method is used.

The response contains:

  • cart composition;
  • information about applied promotions;
  • client data;
  • information on bonus points accrual and deduction.

The method can be used both to get a list of purchases and for subsequent editing or partial return.

Editing a Purchase​

In case of order changes after its placement (for example, adding new positions), the purchase must be edited in Sailplay using the /api/v2/purchases/edit/ method.

The method also allows:

  • binding an anonymous purchase to a client;
  • rebinding a purchase from one client to another.

To do this, the client identifier must be passed in the request without cart or cart_id parameters.

Purchase Confirmation​

The Sailplay API supports two purchase states:

  • unconfirmed;
  • confirmed.

Actual bonus points accrual and deduction occurs at the moment of purchase confirmation.

To confirm, you must call the /api/v2/purchases/confirm/ method.

Partial Order Return​

After placing an order, a client may refuse some positions without adding new ones.
In this case, the corresponding positions must be marked as returned in Sailplay.

General Return Process​

  1. Retrieve the purchase by order_num using the /api/v2/purchases/get/ method.
  2. Get the full order composition with position numbering.
  3. Identify the positions to be returned.
  4. Send a request to exclude positions using the /api/v2/purchases/returns/create/ method, specifying the return_cart JSON object (position number, exclusion flag, quantity, comment).
  5. Positions receive a returned attribute.
  6. The purchase amount and the client's total purchase amount are reduced by the amount of the returned positions.
Important
  • Bonuses accrued and deducted for a position are adjusted by a separate transaction if the purchase was confirmed.
  • If the purchase was not confirmed, the number of points for the purchase is edited.
  • If the client has already spent the points, deduction is made within the available balance (up to zero).

Purchase Deletion and Restoration​

In case of complete customer refusal of a purchase, it must be deleted using the /api/v2/purchases/delete/ method, passing the order number order_num.

Actual deletion of the record from the Sailplay database does not occur. If necessary, a purchase can be restored using the /api/v2/purchases/restore/ method.