Attribute Based Shipping Options
Last updated
Was this helpful?
Last updated
Was this helpful?
Attribute Based Shipping Options provide a cutting-edge solution to this challenge by allowing businesses to customize shipping methods based on specific product attributes. This approach ensures that shipping is not only efficient but also tailored to the unique characteristics of each order.
These shipping options are especially useful in scenarios where certain product attributes necessitate different handling or delivery strategies. For example, consider an online marketplace that sells a variety of products, including perishable goods, fragile items, and heavy equipment. By utilizing attribute-based shipping, the marketplace can allocate specialized cold-chain services for perishable goods, enhanced protective packaging for fragile items, and specialized freight services for heavy equipment. This nuanced approach not only optimizes shipping efficiency but also enhances customer satisfaction by ensuring that each item is delivered in its ideal condition.
Moreover, businesses with diverse product lines can utilize these options to offer customers a more personalized shopping experience. Imagine a retailer that offers clothing, electronics, and furniture. By implementing attribute-based shipping, they can ensure that clothing is dispatched quickly at a lower cost, while electronics are shipped with insurance and furniture with white-glove delivery services.
Ultimately, Attribute Based Shipping Options empower businesses to leverage detailed product information to improve logistics, reduce costs, and provide enhanced service, cementing stronger relationships with their customers.
ATTRIBUTE_KEYS_FOR_ATTRIBUTE_BASED_SHIPPING_OPTION: This dynamic setting allows you to specify the rule for attribute keys that will be used for grouping shipping options.
CHECKOUT_SHIPPING_OPTION_SELECTION_PAGE: This dynamic setting should be set to AttributeBasedShippingOptionSelectionPage to enable the specific selection page for attribute-based shipping options.
This setting can take following values as described:
AttributeBasedShippingOptionSelectionPage
Groups shipping options based on attribute values of products.
DataSourceShippingOptionSelectionPage
Groups shipping options based on seller information of products.
ShippingOptionSelectionPage
Allows selection of a single shipping company for all products in a basket.
These shipping option pages cannot be used simultaneously as they serve as alternatives.
Attribute Based Shipping Options are not compatible with cash on delivery (COD) payment methods. If a COD option is available, a shipping option page rule must be added to accommodate this. [
In these configuration steps, we will proceed with an example where different shipping options are defined for products sold in stores located in different districts. Here, "store" will be defined as a product attribute, and the attribute values will be the districts “Pendik” and “Kadıköy”.
The products sold and their corresponding stores are as follows.
Hat
Pendik
Dress
Pendik
Bag
Kadıköy
It is essential to assign this "store" attribute and its respective values to each product.
Under the default shipping method, all products are processed by a single shipping company. With the attribute-based development, you can separate shipping methods:
Hat & Dress: Use Shipping Company A.
Bag: Use Shipping Company B.
Please follow the below steps to configure attribute based shipping options:
Step 1: Define Product Attributes
As a first step, it is necessary to create a product attribute on the Product and Catalogs > Product Attributes page in Omnitron and to add attribute values for this attribute. After the attribute is defined, an attribute set should be created for this attribute, and then this attribute set should be assigned to the products.
In the following example, the attribute has been defined with the Attribute Code “store”, and two attribute values have been added: “pendik” and “kadikoy”.
Important settings:
Ensure that Is Localizable? is set to No for both attributes, meaning they will not vary based on language or locale.
Use these Attribute Code (store) for future steps in the configuration.
Step 2: Define Shipping Options
In this example, you could have shipping options such as:
For products in Pendik: Create Shipping Company A.
For products in Kadıköy: Create Shipping Company B.
When defining shipping options, the values entered in the Calculator and Rule fields are not crucial at this stage. Calculators and Rules that will be defined in the subsequent steps will be used for the attribute-based shipping options configuration.
Step 3: Configure Dynamic Settings for Attribute-Based Shipping
In this step, you need to configure the dynamic setting for the ATTRIBUTE_KEYS_FOR_ATTRIBUTE_BASED_SHIPPING_OPTION . This step is crucial as it defines the attribute key that will be used for grouping shipping options based on product attributes.
Complete the fields as follows:
1. Group attribute key: Enter the “Group attribute key” (as known as the “Attribute Code” in Omnitron) that you have previously defined in step 1. In this example, you will enter: “store”. This key will be used to group products by store locations.
For products that lack the specified attribute key (for instance, those not tagged with "store"), they will be grouped under a string value of None.
Example configuration:
3. Sort Order: This determines the priority order of the rule, sorted in ascending order. The first group attribute key that meets the rule is used for grouping.
In this example, since only one rule is being defined for the store attribute code, you can set the sort order to 1.
Step 4: Add Attribute-Based Shipping Options
In this step, it is necessary to add attribute-based shipping options. To do this, navigate to Sales Channels > Sales Channel Settings > Attribute Based Shipping Options and click on the "+ New Attribute Based Shipping Option" button to open the form.
In this form, the calculator and rule fields should be filled out as needed. If you want to specify the order, you can provide a value for the order. Make sure to set the status to active.
The most crucial step is to enter the previously defined attribute values and select the corresponding shipping option that will be applicable for each value. After completing these steps, save the form. Then, repeat this configuration for all desired attribute values.
In this example, the shipping options defined in Step 2 have been matched with the relevant attribute values:
Attribute Value: pendik → Shipping Option: Shipping Company A
In this example, products in Pendik are assigned to Shipping Company A.
The sample rule is as follows:
Attribute Value: kadikoy → Shipping Option: Shipping Company B
In this example, products in Kadıköy are assigned to Shipping Company B.
The sample rule is as follows:
Step 5: Enable the Checkout Shipping Option Selection Page
Finally, to enable the configuration, set the CHECKOUT_SHIPPING_OPTION_SELECTION_PAGE dynamic setting to AttributeBasedShippingOptionSelectionPage.
In this configuration scenario, a home appliance company operates with different delivery strategies for products delivered to two major cities:
The company offers separate shipping options for products delivered to İstanbul based on their brand (Beko, Arçelik, Siemens).
Where all brands are available under a single store, shipping options for products delivered to İzmir are determined by the type of appliance (small or large home appliance).
Please follow the below steps to configure attribute based shipping options:
Step 1: Define Product Attributes
As a first step, it is necessary to create a product attribute on the Product and Catalogs > Product Attributes page in Omnitron and to add attribute values for this attribute. After the attribute is defined, an attribute set should be created for this attribute, and then this attribute set should be assigned to the products.
In this example, the following product attributes have been defined:
Attribute Code: brand
Values: beko, arcelik, siemens (these are the brands)
Attribute Code: type
Values: small, large (these are the product types)
Important settings:
Ensure that Is Localizable? is set to No for both attributes, meaning they will not vary based on language or locale.
Use these Attribute Codes (brand and type) for future steps in the configuration.
Step 2: Define Shipping Options
In this example, you could have shipping options such as:
For beko products delivered to İstanbul: Create Shipping Company A.
For arcelik products delivered to İstanbul: Create Shipping Company B.
For siemens products delivered to İstanbul: Create Shipping Company C.
For small products delivered to İzmir: Create Shipping Company D.
For large products delivered to İzmir: Create Shipping Company E.
When defining shipping options, the values entered in the Calculator and Rule fields are not crucial at this stage. Calculators and Rules that will be defined in the subsequent steps will be used for the attribute-based shipping options configuration.
Step 3: Configure Dynamic Settings for Attribute-Based Shipping
In this step, you need to configure the dynamic setting for the ATTRIBUTE_KEYS_FOR_ATTRIBUTE_BASED_SHIPPING_OPTION. This step is crucial as it defines the attribute key that will be used for grouping shipping options based on product attributes.
Complete the fields as follows:
1. Group attribute key: Enter the “Group attribute key” (also known as the “Attribute Code” in Omnitron) that you have previously defined in step 1. In this example, you will enter: “brand” for the 1. Field and “type” for the 2. Field. These keys will be used to group products by brand and type.
For products that lack the specified attribute key (for instance, those not tagged with "store"), they will be grouped under a string value of None.
Example Rule for the "brand" group attribute key for Istanbul:
Example Rule for the "type" group attribute key for Izmir:
3. Sort Order: This setting determines the priority order for applying the rule, sorted in ascending order. The first matching group attribute key is used for grouping.
In this example, the sort order for products delivered to Istanbul is set to 1, while for products delivered to Izmir, it is set to 2.
Step 4: Add Attribute-Based Shipping Options
In this step, it is necessary to add attribute-based shipping options. To do this, navigate to Sales Channels > Sales Channel Settings > Attribute Based Shipping Options and click on the "+ New Attribute Based Shipping Option" button to open the form.
In this form, the calculator and rule fields should be filled out as needed. If you want to specify the order, you can provide a value for the order. Make sure to set the status to active.
The most crucial step is to enter the previously defined attribute values and select the corresponding shipping option that will be applicable for each value. After completing these steps, save the form. Then, repeat this configuration for all desired attribute values.
In this example, the shipping options defined in Step 2 have been matched with the relevant attribute values defined in Step 1:
For İstanbul (based on brand): Products will be assigned to the shipping company by brand, and different shipping companies will handle the deliveries:
Attribute Value: beko → Shipping Option: Shipping Company A
In this example, products of the Beko brand delivered to Istanbul are assigned to Shipping Company A using the And Rule.
The sample rule is as follows:
Attribute Value: arcelik → Shipping Option: Shipping Company B
In this example, products of the Arçelik brand delivered to Istanbul are assigned to Shipping Company B using the And Rule.
The sample rule is as follows:
Attribute Value: siemens → Shipping Option: Shipping Company C
In this example, products of the Siemens brand delivered to Istanbul are assigned to Shipping Company C using the And Rule.
The sample rule is as follows:
For İzmir (based on type): Products will be assigned to the shipping company by type, and different shipping companies will handle the deliveries:
Attribute Value: small → Shipping Option: Shipping Company D
In this example, products of the Small home appliance type delivered to İzmir are assigned to Shipping Company D using the And Rule.
The sample rule is as follows:
Attribute Value: large → Shipping Option: Shipping Company E
In this example, products of the Large home appliance type delivered to İzmir are assigned to Shipping Company E using the And Rule.
The sample rule is as follows:
Step 5: Enable the Checkout Shipping Option Selection Page
Finally, to enable the configuration, set the CHECKOUT_SHIPPING_OPTION_SELECTION_PAGE dynamic setting to AttributeBasedShippingOptionSelectionPage.
If the address selected by the user during the checkout process does not meet the defined ATTRIBUTE_KEYS_FOR_ATTRIBUTE_BASED_SHIPPING_OPTION setting, the following error message will be displayed:
To prevent this error, an additional field for the rule must be defined in the ATTRIBUTE_KEYS_FOR_ATTRIBUTE_BASED_SHIPPING_OPTION setting in Step 3 of the configuration. In the following example, an Any Rule has been added to group fragile products that are not delivered to Istanbul or Izmir. Based on this grouping, a shipping option can be offered according to the attribute-based shipping option defined in Step 4.
The Rules section defines configurable rule types for implementing Attribute-Based Shipping Options. This section provides an overview of each rule type, its parameters, and examples for setting up complex structures.
Here is an outline of the rule types and their applications:
any-rule
Any Rule
-
Applies when any conditions are met.
not-rule
Not Rule
child dict
Used to exclude specific conditions; works by negating attribute conditions.
and-rule
And Rule
children list[{dict}]
Combines multiple conditions that all must be met; ideal for complex shipping configurations based on multiple attributes.
or-rule
Or Rule
children list[{dict}]
Applies if any one of several conditions is met.
city-rule
City Rule
cities list, exclude boolean
Enables shipping rules based on specific cities, including/excluding certain city IDs.
country-rule
Country Rule
countries list, exclude boolean
Enables shipping rules based on specific countries, including/excluding certain country IDs.
township-rule
Township Rule
townships list, exclude boolean
Enables shipping rules based on specific townships, including/excluding certain township IDs.
district-rule
District Rule
districts list, exclude boolean
Enables shipping rules based on specific districts, including/excluding certain district IDs.
postal-code-rule
Postal Code Rule
postal_codes list, exclude boolean
Enables shipping rules based on specific postal codes, including/excluding certain postal code IDs.
The city-rule, country-rule, township-rule, district-rule, and postal-code-rule apply shipping options based on selected shipping address during the checkout process.
Here are examples for setting up a city-rule: (For other location-based rules, refer to the slug and name in the table above.)
1. Including Specific Cities (e.g., city IDs 1234, 1235):
2. Excluding Specific Cities (e.g., all cities except city IDs 1234, 1235):
This rule applies when no specific conditions are needed. Useful for cases where a flexible rule setup is required.
This example demonstrates how to set up a complex rule structure by combining multiple rule types.
This rule structure demonstrates a logical configuration that applies the following conditions:
The Or Rule at the top level will result in a positive outcome if either rule1 is satisfied or if the And Rule is satisfied.
Within the And Rule, two Not Rules are applied to rule2 and rule3, meaning that both rule2 and rule3 must not be satisfied for the And Rule to be true.
In simpler terms, this configuration will trigger the ATTRIBUTE_KEYS_FOR_ATTRIBUTE_BASED_SHIPPING_OPTION dynamic setting if:
rule1 is satisfied, or
both rule2 and rule3 are not satisfied simultaneously.
The structure above can be logically represented as:
Products that either lack the attribute key set by dynamic settings or have the attribute key but do not have an attribute value will be grouped under the string value None. If you want to display specific shipping options for these products without attribute key, it is necessary to create an attribute-based shipping option in the configuration steps, as in the Step 4. This created shipping option may also be visible for other products. If you wish to restrict the visibility for this option, a specific rule can be implemented.
Example for Scenario 1:
If the shipping option should only apply to locations other than Kadıköy and Pendik, you can use the following rule configuration:
Not Rule: This rule is designed to exclude the conditions specified in the child rules.
Or Rule: Contains two child rules that target the attributes for Kadıköy and Pendik:
The first child rule specifies that the attribute_value for the store must not be kadikoy.
The second child rule specifies that the attribute_value for the store must not be pendik.
By implementing this configuration, the shipping options will be visible for all locations except for Kadıköy and Pendik.
Important Note on Cash on Delivery: The cash on delivery payment method cannot be managed with AttributeBasedShippingOptionSelectionPage and DataSourceShippingOptionSelectionPage. Therefore, COD should not be enabled for these shipping options.
To resolve this, the omnishop.payments.rules.ShippingOptionPageRule is to be utilized, which allows configuring the page parameter with the following setup:
The COD payment method is only applicable with the ShippingOptionSelectionPage shipping option. Therefore, the rule specified in the JSON format below needs to be added as a conf for the cash on delivery payment method.
GET List Attribute Shipping OptionsThis method is used to get the available attribute shipping options for the current checkout.
Path: /orders/checkout/?page=AttributeBasedShippingOptionSelectionPage
Query Parameters
The following query parameters can be used to get a list of attribute based shipping options.
page
string
query
The checkout page for the transaction.
Example Request
To retrieve available attribute based shipping options, a GET request should be sent to the /orders/checkout/?page=AttributeBasedShippingOptionSelectionPage endpoint.
Example Response (200 OK)
In a successful response with a status code of 200 OK, the API returns the requested attribute-based shipping options in a checkout context. The response includes the complete checkout page information of the user.
attribute_based_shipping_options
dict
A dictionary structure that contains shipping options grouped by various attributes based on the basket.
key <attribute value>
str
Represents the attribute value that groups the shipping options (e.g., "kadikoy"). This key encompasses the list of attribute shipping options.
attribute_based_shipping_options[].pk
int
The primary key (PK) of the attribute shipping option.
attribute_based_shipping_options[].shipping_amount
str
A string indicating the cost of the attribute shipping option (e.g., "39.90").
attribute_based_shipping_options[].shipping_option_name
str
Represents the name of the shipping option (e.g., "Shipping Company A").
attribute_based_shipping_options[].shipping_option_logo
url or null
Contains the URL of the shipping option's logo. Returns null if no logo is available.
attribute_key
list of str
A list of keys that represents how the shipping options are grouped (e.g., "store"). This shows the attributes used for organizing the shipping options.
product_ids
list of int
A list containing the IDs of products.
Example Response Structure:
POST Select Attribute Based Shipping OptionsThis method is used to select attribute based shipping options for the checkout data sources.
Path: /orders/checkout/?page=AttributeBasedShippingOptionSelectionPage
Body Parameters
The following request body parameters can be used to select attribute based shipping options.
attribute_based_shipping_options
dict
body
Yes
Dictionary containing PKs of selected shipping options categorized by attribute names.
Example Request
Example Response (200 OK)
In a successful response with a status code of 200 OK, the API indicates that a change has occurred in the checkout. The error field must be checked; if it is null, the page_context will include the next page information, and the selected shipping options will be returned.
Example Bad Request Response (200 OK)
In an unsuccessful response with a status code of 200 but containing a non-null error field, the errors might resemble the following:
Once the attribute and its values are set up, you need to define the shipping options for these attribute values. For detailed information on defining shipping options, please refer to the documentation.
2. Rule: In the Rule field, the rules detailed in the section should be configured for this field. Since this example involves configuring different store locations, the Any Rule is used.
Once the attribute and its values are set up, you need to define the shipping options for these attribute values. For detailed information on defining shipping options, please refer to the documentation.
2. Rule: In the Rule field, the rules detailed in the section should be configured for this field. Since this example involves grouping products by brand and type across different cities, the City Rule is applied.
