Knowledge Base
Softline Checkout
Up
Knowledge Base
Softline CheckoutIntegrationDynamic Product Checkout API
Generate Checkout Link

Generate Checkout Link

Request Description

POST /v1/generate_buy_link

The request allows getting a link using which:

  • The customer gets redirected to the checkout page.
  • All products having dynamic information and transferred in the request are added to the cart.
  • Customer data required for placing an order is overwritten with the data transferred in the request.

Request contains:

Connection Data

Header Parameters

content-type
string
required
MIME-type.
It must be equal to "application/json".
AuthorizationJWT
required
Authorization token.
  • Format: Bearer [token]
  • Where [token] is substituted by the token value obtained through the authentication API

Body Parameters

currency
string
required
Checkout currency code
The available currencies are configured upon in accordance with the agreement.
  • Format: ISO 4217 alpha-3, 3 characters
  • For the value options, see the reference guide
products
array [objects]
required
Contains a list of dynamic products to be added to the cart.
products / [object]
/
id
number
required
Original product ID
You received this ID when connecting to the API. If the request contains several products, then their id must not match. It means that one request cannot contain two products having dynamic information and being based on the same original product.
products / [object]
/
sku
string
Product SKU on your end
Recommended to be used to transfer the product article according to the your price list.

Maximum of 40 characters.
products / [object]
/
vendor_code
string
Product ID on your end

Maximum of 255 characters.
products / [object]
/
name
string
required
Product name
products / [object]
/
name_for_invoice
string
Product name for closing documents
Used in closing documents of the 1C program when requested (e.g., invoice, delivery note). The customer receives these documents in a corresponding email.
products / [object]
/
price
string
required
Price per product item excluding discount
  • Format: Numeral with 2 decimal places, separator - dot. Transferred as a string.
  • It can be equal to zero. If the case, the request must contain at least one product item with a non-zero value considering a discount. Zero price is used to add a gift to the cart
  • Sale of trial products at a zero price is currently not available through this API
products / [object]
/
discount_percent
number
Product percentage discount
  • Format: Numeral, up to 6 decimal places, separator - dot
  • 0 < discount_percent <= 100
  • If discount_percent = 100, then the request must contain at least one product which has a discounted price that is greater than zero. The 100% discount price is used to add a gift to the cart
products / [object]
/
quantity
number
required
Product quantity

The customer will not be able to change this quantity.
products / [object]
/
is_delivery_needed
boolean
Product delivery method

Value options:
  • true - physical delivery
  • false - electronic delivery (license information is sent to the customer's email)
The default value is set in the original product.
products / [object]
/
is_installments_unavailable
boolean
Installment availability for the product
More details on how installments work.

Value options:
  • true - installment not available
  • false - installment not available
It is false by default.

More details on how installments work.
products / [object]
/
is_service
boolean
Technical field
products / [object]
/
vat_included
boolean
VAT calculation method
Only for product sales in rubles (currency = RUB).

Value options:
  • true - VAT is included
  • false - product is not subject to VAT
The default value is set in the original product.
If you need to override any VAT settings of the original product, then use the following rules:
If you are a resident of the Russian Federation and are not a VAT payer (using the simplified taxation system), or are a VAT payer (using the general taxation system), then:
  • If a program is listed on the Unified Register of Russian Software, then sales are exempt from VAT – you have to transfer vat_included: false in the request
  • If a program is not listed on the Unified Register of Russian Software, then VAT is charged on sales - you have to transfer vat_included: true in the request
Please Note: In the original product, you can configure whether a program is listed on the Unified Register of Russian Software or not.
products / [object]
/
subscription
object
Subscription settings (AR)
  • If the parameter has been transferred and the auto-renewal option has been preset for the original product, an auto-renewable subscription will be available for the dynamic product in the cart on the checkout page
  • If the parameter has not been transferred, the auto-renewal option will not be available for the product in the cart on the checkout page (even if the auto-renewal option has been preset for the original product)
More details on how auto-renewal works with dynamic products.
products / [object] / subscription
/
period
string
required*
Validity term, for the product that initiates the subscription (parent).
  • * - Required, if subscription parameter is transferred
  • Format: ISO 8601 code: P[date][unit of measure]
  • Units of measure supported: Y - year, M - month, D - day
    E.g., "P1Y" is "1 year"
products / [object] / subscription
/
name
string
Product name for subscription renewal (child)
The default value is set in the original product.
products / [object] / subscription
/
price
string
Price per renewal product item (child)
Learn more about calculating the final price for renewal.
  • Format: Numeral with 2 decimal places, separator - dot. Transferred as a string
  • The default value is set in the original product
customer
object
Customer data
If the field is transferred, then the customer data will be pre-filled in the cart. The customer can change these values.
customer / [object]
/
type
string
Customer type

Value options:
  • physical - individuals
  • juridical - companies
customer / [object]
/
email
string
Customer's email

Maximum of 72 characters.
customer / [object]
/
first_name
string
Customer's name

Maximum of 255 characters.
customer / [object]
/
last_name
string
Customer's last name

Maximum of 255 characters.
customer / [object]
/
phone
string
Customer's phone number

Maximum of 64 characters.
customer / [object]
/
vat_number
string
Customer's taxpayer identification number
Also used to fill in the INN field for sales in Russia. The number will be prefilled only if a checkout page has one field for entering the Taxpayer Identification Number of the customer (field display depends on checkout currency). Otherwise, the customer must fill in the Taxpayer Identification Number themselves.

Maximum of 255 characters.
company_name
string
customer / [object]
Company name

Maximum of 255 characters.
customer / [object]
/
company_billing_address
string
Legal address

Maximum of 255 characters.
customer / [object]
/
company_delivery_address
string
Actual address

Maximum of 255 characters.
customer / [object]
/
country
string
Customer's country code
  • Format: ISO 3166-1
  • If a country code is transferred, and it is true to the request currency, then the country will be automatically selected in the cart
  • If the country is not true to the request currency (currency), but is available in the cart, then the country field has a higher priority, the currency in the cart will be set according to the country code transferred, see examples further
additional_data
object
Additional parameters
The values that will be saved to the order as referrers can be transferred. It is saved and further used. More details on additional parameters. Please note that the time for storing additional parameters in orders is limited.
additional_data
/
referer7
string
Referer7 value

Maximum of 255 characters.
additional_data
/
referer8
string
Referer8 value

Maximum of 255 characters.
additional_data
/
referer9
string
Referer9 value

Maximum of 255 characters.
additional_data
/
referer10
string
Referer10 value

Maximum of 255 characters.
additional_data
/
referer11
string
Referer11 value

Maximum of 255 characters.
additional_data
/
referer12
string
Referer12 value

Maximum of 255 characters.

Request Example

{
 "currency": "EUR",
 "products":
 [{
   "id": 111111,
   "vendor_code": "API-1",
   "sku": "L1-1",
   "name": "Demo product",
   "name_for_invoice": "Program 1 v1, 3",
   "price": "1120.50",
   "discount_percent": 10,
   "quantity": 1,
   "is_delivery_needed": false,
   "is_installments_unavailable": false,   
   "vat_included": false,
   "subscription": {
    "period": "P1Y",
    "name": "Demo product for renew (1 year)",
    "price": "900"
   }
  }, {
   "id": 2223333,
   "name": "Demo product 2",
   "price": "2000.50",
   "quantity": 1,
  }
 ],
 "customer": {
  "type": "juridical",
  "email": "test@test.com",
  "first_name": "Ivan",
  "last_name": "Petrov",
  "phone": "7999991111",
  "vat_number": "12345654321",
  "company_name": "Company name",
  "company_billing_address": "Trocadéro, Avenue Anatole-France, 5",
  "company_delivery_address": "Trocadéro, Avenue Anatole-France, 5",
  "country": "FR"
 },
 "additional_data": {
  "referer7": "product=test&project=test",
  "referer8": "testA",
  "referer9": "testB",
  "referer10": "testC",
  "referer11": "testD",
  "referer12": "testF"
 }
}

Response Description

In response to the request, you receive the server response code corresponding to the processing result. Depending on the code, the response body may contain additional parameters.

Successful Response

If processing is successful, the following will return in response server response code: HTTP/1.1 200 ОК and json with a checkout link.

Body Parameters

buy_link
string
Checkout link.
  • Format: https://[checkout page domain]/basket/flash/[dynamic checkout page ID]
  • When working in the test environment, a checkout link intended for the test environment will return in response (such links will have the .demoslweb.ru suffix added)
  • In case, when following the link, an empty checkout page opens (no product has been added), then this problem occurs if the original product is not available for sale on the our end. Review the original product id in the request
external_id
string
required
Dynamic checkout page ID
This identifier is generated when each request is processed; i.e. you get a unique identifier in response every time. If your end customer places an order using the checkout link received in response to a request, the system saves the identifier into the order. Later, you can get it from the order data, e.g. in webhooks or through the Orders API.

Example of Successful Response

{
 "buy_link": "https://cart.checkout.softline.com/basket/flash/123456",
 "external_id": "123456"
}

Error Response

If an error occurs while processing the request, you receive a server response code corresponding to the result of processing. 
Depending on the code, the response body may contain additional parameters.

HTTP Server Response Error Code

HTTP code Description
HTTP/1.1 400 Bad Request The request is not valid (error in parameters; necessary data is not transferred, etc.).
An additional error code (one or more) will be transferred in the response bodу.
HTTP/1.1 401 Unauthorized Unsuccessful authorization.
An additional error code (one or more) will be transferred in the response bodу.
HTTP/1.1 404 Not found Invalid request URL. 
HTTP/1.1 500 Request Error Internal Server Error. Please try again later or contact support.

Additional Error Codes for HTTP 400

Error Message Description
If at least one error from the list below is found, then it returns in response to a request, other errors are not validated.
110 JSON is not valid. The request cannot be processed. Request field structure is not valid. Check the fields in the request body against the JSON format.
111 Invalid data format (Content-type). The request cannot be processed. Invalid request header. Content-type must be equal to application/json.
3120 Unable to define cart settings for this currency. Please contact technical support. Failed to identify a cart or a product for the sale currency transferred (currency).
If at least one error from the list below is found, then the request checking is not interrupted. Several errors may return in response.
3010 Invalid field value: [parameter name] The request is not valid, e.g., the required field is not filled out, the field name is incorrect, the field value does not match with the data type provided, or the value format is incorrect. Moreover, the error will return if null is transferred in the field, and this value option is not set as valid in the field description.
3020 Order price cannot be equal to zero. Change product price (price, discount_percent) or add product having non-zero price. The discounted product is equal to zero (products.price = 0 or products.discount_percent = 100), but there is no other product in the request that has a value greater than zero.
3030 Incorrect discount value. Discount_percent value must be strictly greater than zero and less than or equal to 100. Invalid discount value (products.discount_percent). The value must meet the following requirements: 0 discount_percent <= 100.
3040 Purchase of this original product subscription is impossible. Change original product (id) or delete subscription data (subscription). The request contains the data for the subscription (products.subscription), but the settings required are not made for the original product.
3050 Purchase of this original product is impossible. Change original product (id). The request contains the original product (products.id), that cannot be found on the our side.
3060 Email field is filled out incorrectly. Expected format: [name]@[domain].[zone] Invalid email address is transferred (customer.email).
3070 Single request must contain products with different products.id values. More than one product is transferred with the same id. (products.id).

Additional Error Codes for HTTP 401

The errors are the same for all the APIs that use token authorization.

Body Parameters

errors
array [objects]
required
Error list.
errors / [error object]
/
error
number
required
Error code.
errors / [error object]
/
message
string
required
Error description.

Example of Error Response

{
 "errors": [{
   "error": 3010,
   "message": "Invalid field value: currency."
  }, {
   "error": 3010,
   "message": "Invalid field value: name."
  }
 ]
}
Terms & Conditions
© 2023 Softline