The basic concept of our API is to keep everything as simple as possible for you and to avoid any unnecessary backend work on your side.
From Developers, For Developers
To achieve this goal, we reduced the required fields in the API recommendation endpoint to a minimum and thereby circumvented the necessity for you to do any backend matching.
A product recommendation consists of two parts. First, you inform us which product is in the basket, and then we automatically provide you with a list of products that would be a great fit. This structured list of products includes all relevant information.
To get your first recommendation, please provide us the following information:
The amount of information is very limited — at this point, no personal information about your customer is necessary.
The basic setup of your account is stored and can be changed in the admin interface. However, you always have the ability to edit the basic information connected to your account during a recommendations request, including:
If you leave this information blank during your request, we will use the default values stored for your account.
To improve the recommendations, you can voluntarily provide more information such as:
None of this information is required, but if you include it, the customer-related information must be GDPR compliant.
Context-related information is a fully flexible tool you can use to give us any information about the shopping situation, including (but not limited to):
The more we know about the product in the basket, the better we can predict which cross-selling item best fits the profile. Therefore, you have the ability to provide us with more information about the product, such as:
In some cases, information about the customer is relevant for the product recommendation and is GDPR compliant. In this case, the following customer information can be provided to make the recommendation fit even better:
The most flexible way to get the recommendations is to use our API (see our Reference for all technical details).
You will receive your recommendations with a simple GET request:
The API does not require any authentication for the recommendations request.
The most simple recommendations request only requires three additional URL-encoded parameters:
In this example, we use the product "Apple iPhone 12 Pro - Pacific blue" ( URL-encoded - Apple%20iPhone %2012%20Pro%20-%20Pacific%20blue) with the session "test" and the partner ID "35up-test."
No additional parameters are necessary to make your first successful API request.
Every request uses the partner ID to load default settings for:
These values can be adjusted in the admin area. To edit these default values during the request, additional parameters are needed. In this case, we want to take our first example, but change the values to Germany, German, and Euros, with a maximum number of 10 products:
The currency Euro is connected to the country Germany, so in this case no additional parameter is needed.
The more information you provide about the product in the basket, the better the recommendation. To provide additional information, you can add any baseProduct* value, such as:
These additional parameters are not required, but they can provide helpful additional information.
If information about the customer could influence the recommendation, you can submit these values as well. However, you have to take care that all information provided is GDPR compliant. These values can be added as customer.*
Following is an example for an 80-year-old person from Boston:
These additional parameters are not required, but they can provide helpful additional information.
The use of a plugin eases the integration and does not require additional coding. We currently have plugins under development for the following shop systems:
Please contact us if you are interested in testing our plugins before release.
The recommendations are displayed in the cross-selling widget. Moreover, the widget provides the customer with additional information and allows the customer to add the products to the cart.
The widget is fully configurable and can be adjusted to the look and feel of your website.
You can decide where the widget should be displayed (e.g., in the basket, the checkout, a popup, the product-detail page, or on all pages mentioned). The best-fitting location and amount of integrations depend on your user journey.
The most common location in which to display the cross-selling widget is the basket. The customer has already selected his/her final product and has displayed a willingness to buy, so that is the perfect opportunity to show fitting cross-selling items. Moreover, the basket is a late stage in the journey and shows a high-level of trust in your brand. However, it is still possible to seamlessly add complementary products to the basket without the need to recalculate the final price and taxes.
Another option is to display the widget as a popup between the order detail page and the basket, right after the customer adds the base product. In this case, the customer has already selected his final product and demonstrated a high willingness to buy it. An overlay reminds him about fitting cross-selling items and creates a high awareness of the complementary product. In addition, there is no need to recalculate the final price and taxes.
The cross-selling widget can also be displayed to show complementary items on every product-detail page. This display enriches the product-detail pages. To prevent the complementary item(s) from replacing the base product purchases, an "add to cart" click should not lead to a direct load of the basket, but should stay on the product-detail page.
The most flexible way to get and show the recommendations is to use our API (see our Reference for all technical details).
You will receive your recommendations with a simple GET request:
The response is a structured JSON, which provides all the information needed to show the recommended cross-selling products.
A comprehensive JSON response for one product is below. However, if more than one product is recommended, the "recommendations" array will provide the additional products in the following structure.
The JSON response always provides the following information, which can be used to display the products.
The vendor object provides the following information for every vendor:
The SKU string shows the unique identifier of a product on our platform.
The price object provides following information:
The name string shows the full name of the product.
Images provides a number of product image URLs with the required "thumbnail."
The descriptions object provides:
The delivery object provides two data points on the delivery time:
Actions are optional actionable URLs that trigger operations on the platform. They are deactivated in the default configuration.
To allow a seamless customer journey, the cross-selling items must be added to the basket and processed on the backend. The handover of the data from the cross-selling widget to the basket and the backend depends on the type of integration (API/plugin) and the shop systems involved.
The minimum requirements are as follows:
Based on this information, a new total price can be calculated and a new comprehensive basket can be rendered.
Please check the API Reference for all technical details about the API.
The API was designed to make the integration for developers as easy as possible. However, the handover of the product data from 35up to your backend requires additional coding on your side when you use the API. The additional 35up product, from this point on, needs to be present in your database.
To achieve the handover using the standard processes that most shop systems use seems to be the easiest, cleanest approach. Of course, the exact execution depends on your system and your system conditions. Here, we identify three best practices:
Many modern shop systems provide the ability to add "configurable" products into the basket. These products do not have to preexist in your product database — they can be created "on the fly." This mechanism is perfect for adding 35up cross-selling to the basket and handing over the data to your backend. In this case, you simply create a new configurable product every time a customer adds a 35up product to the basket and enrich the necessary information based on the product data provided.
This approach ensures the sole use of standard processes and is not likely to require additional changes on the backend.
Another approach to hand over the product data from the front end to the backend is the use of dummy products. If your shop system does not allow for configurable products, dummy products are very often the next best choice. In this case, you create one "35up dummy" product in your product database. Every time a 35up product is added to the basket, you add this dummy product and overwrite the price and name with the values from the product info.
If neither the configurable nor the dummy product approach works for your system, you could add the additional cross-selling items as attributes or comments to an order. In this case, make sure that the information is stored in a structured, repeatable way and that you can use the values to calculate the final price.
To support your effort in handing over the product data, we created an additional API endpoint: "GET products."
This endpoint provides you with all product information based on the SKU. With this endpoint, you only have to hand over the SKU and the quantity, and you can reach all other information on demand later.
The JSON response always provides the following information, which can be used to store the product with all its details in your product database:.
For every vendor, the vendor object provides:
The SKU string shows the unique identifier of a product on our platform.
The price object provides following information:
The name string shows the full name of the product.
Images provides a number of product image URLs, with the required "thumbnail."
The descriptions object provides:
The delivery object provides two data points on the delivery time:
Every product that is ordered at your shop will pass through your backend, the 35up platform, and ultimately end up in the vendor's system.
The customer experiences the journey on your website seamlessly. However, he/she will receive two different packages: one from your shop with the base product and one from the vendor with the cross-selling product.
Please check the API Reference for all technical details about the API.
Order placements and updates require authorization and need to be executed on the backend.
35up uses the standard HTTP authorization, based on base64 encoding.
Most tools and libraries will automatically handle this process.
To place an order, you need to make a POST request authorized to:
All the information needed is part of the request body:
The shipping address is crucial. Please make sure you always provide the correct information to avoid unhappy customers and additional costs.
The item’s array provides the information about which product should be ordered in what quantity:
If the order was successfully placed, you will receive a response with the status code 201.
This response contains valuable information:
An order can have one of the following statuses:
To update an order status, you need to make an authorized PATCH request to:
The ID is the order ID received as a response to the POST order request.
The request body:
The response will have the same structure as the POST order request response.
If there is to be a delay between placing an order and dispatching it, this can be solved as follows:
This can be useful if, for example, credit scoring is to be carried out first for the main order.
Please check the API Reference for all technical details about the API.
The listing of orders requires authorization and needs to be executed on the backend.
35up uses the standard HTTP authorization, based on base64 encoding.
Most tools and libraries will automatically handle this process.
To get a list of all orders, you need to make an authorized GET request to:
The response provides you with a list of orders:
An order can have one of the following statuses:
Based on the ID from the Get Orders request, you can get detailed information about a single order with a GET orders/ID request:
The response body includes all necessary information:
The shipping address is crucial. Please make sure you always provide the correct information to avoid unhappy customers and additional costs.
The items array provides information about which product should be ordered in what quantity:
The return management does not need a separated integration; it can be fully managed through admin. In the admin area, you can request returns for your customers or confirm incoming returned products.
However, a full integration of the return process is beneficial and can fully automate the process. The integration enables you to:
Once the customer requests a return, the request needs to be sent to 35up to create a return label. With this return label, the customer then sends the product directly back to the vendor.
To refund the customer is in your responsibility. 35up will refund your purchase price.
Please check the API Reference for all technical details about the API.
To request or patch a return requires authorization and needs to be executed on the backend.
35up uses the standard HTTP authorization, based on base64 encoding.
Most tools and libraries will automatically handle this process.
To place an order, you need to make an authorized POST request to:
All the information needed is part of the request body:
To update a return status, you need to make an authorized PATCH request to:
The ID is the order ID that should be returned.
The request body:
In the default case, payment collection is the seller’s responsibility. The seller collects the amount from the customer. 35up will invoice the seller, and the vendor will invoice 35up.
The exception to the default case happens when the seller only collects the IBAN from the customer and not the amount itself. In this case, the IBAN can be passed to 35up to collect the cross-selling item’s purchase amount.
Please check the API Reference for all technical details about the API.
The request to post payment information requires authorization and needs to be executed on the backend.
35up uses the standard HTTP authorization, based on base64 encoding.
Most tools and libraries will automatically handle this process
To place the SEPA payment information of an order, you need to make an authorized POST request to:
All the information needed is part of the request body.