Attribute Based Shipping Options
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.
Key Dynamic Settings
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 toAttributeBasedShippingOptionSelectionPage
to enable the specific selection page for attribute-based shipping options.
This setting can take following values as described:
Value | Description |
---|---|
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.
NOTE
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. [Shipping Option Page Rule]
Configuration Steps
Example Scenario 1
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.
Product Name | Attribute Values for “store” Attribute |
---|---|
Hat | Pendik |
Dress | Pendik |
Bag | Kadıköy |
NOTE
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
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 Shipping Options documentation.
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.
NOTE
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
.
2. Rule: In the Rule field, the rules detailed in the Rules section should be configured for this field. Since this example involves configuring different store locations, the Any Rule is used.
Example configuration:
{
"name": "Any Rule",
"slug": "any-rule"
}
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": "pendik",
"attribute_field": "store",
"name": "Product Attribute Rule",
"func": "all",
"slug": "product-attribute-rule"
}
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:
{
"attribute_value": "kadikoy",
"attribute_field": "store",
"name": "Product Attribute Rule",
"func": "all",
"slug": "product-attribute-rule"
}
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
.
Example Scenario 2
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
andtype
) for future steps in the configuration.
Step 2: Define Shipping Options
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 Shipping Options documentation.
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.
NOTE
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
.
2. Rule: In the Rule field, the rules detailed in the Rules 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.
Example Rule for the "brand" group attribute key for Istanbul:
{
"exclude": false,
"cities": [34], // Istanbul City ID
"name": "City Rule",
"slug": "city-rule"
}
Example Rule for the "type" group attribute key for Izmir:
{
"exclude": false,
"cities": [35], // Izmir City ID
"name": "City Rule",
"slug": "city-rule"
}
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:
{
"name": "And Rule",
"slug": "and-rule",
"children": [
{
"attribute_value": "beko",
"attribute_field": "brand",
"name": "Product Attribute Rule",
"func": "all",
"slug": "product-attribute-rule"
},
{
"exclude": false,
"cities": [34], // Istanbul City ID
"name": "City Rule",
"slug": "city-rule"
}
]
}
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:
{
"name": "And Rule",
"slug": "and-rule",
"children": [
{
"attribute_value": "arcelik",
"attribute_field": "brand",
"name": "Product Attribute Rule",
"func": "all",
"slug": "product-attribute-rule"
},
{
"exclude": false,
"cities": [34], // Istanbul City ID
"name": "City Rule",
"slug": "city-rule"
}
]
}
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:
{
"name": "And Rule",
"slug": "and-rule",
"children": [
{
"attribute_value": "siemens",
"attribute_field": "brand",
"name": "Product Attribute Rule",
"func": "all",
"slug": "product-attribute-rule"
},
{
"exclude": false,
"cities": [34], // Istanbul City ID
"name": "City Rule",
"slug": "city-rule"
}
]
}
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:
{
"name": "And Rule",
"slug": "and-rule",
"children": [
{
"attribute_value": "small",
"attribute_field": "type",
"name": "Product Attribute Rule",
"func": "all",
"slug": "product-attribute-rule"
},
{
"exclude": false,
"cities": [35], // Izmir City ID
"name": "City Rule",
"slug": "city-rule"
}
]
}
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:
{
"name": "And Rule",
"slug": "and-rule",
"children": [
{
"attribute_value": "large",
"attribute_field": "type",
"name": "Product Attribute Rule",
"func": "all",
"slug": "product-attribute-rule"
},
{
"exclude": false,
"cities": [35], // Izmir City ID
"name": "City Rule",
"slug": "city-rule"
}
]
}
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
.
NOTE
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:
"code": "attribute_based_shipping_option_100",
"en": _("No attribute based shipping option available.")
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.
Rules
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:
Slug | Name | Serializer | Description |
---|---|---|---|
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. |
Location-Based Rules for Shipping Address
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):
{
"exclude": false,
"cities": [1234, 1235],
"name": "City Rule",
"slug": "city-rule"
}
2. Excluding Specific Cities (e.g., all cities except city IDs 1234, 1235):
{
"exclude": true,
"cities": [1234, 1235],
"name": "City Rule",
"slug": "city-rule"
}
Any-Rule
This rule applies when no specific conditions are needed. Useful for cases where a flexible rule setup is required.
{
"name": "Any Rule",
"slug": "any-rule"
}
Complex Rule Structure Example
This example demonstrates how to set up a complex rule structure by combining multiple rule types.
{
"children": [
{
...(rule1)
},
{
"children": [
{
"child": {
...(rule2)
},
"name": "Not Rule",
"slug": "not-rule"
},
{
"child": {
...(rule3)
},
"name": "Not Rule",
"slug": "not-rule"
}
],
"name": "And Rule",
"slug": "and-rule"
}
],
"name": "Or Rule",
"slug": "or-rule"
}
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:
(rule1 or ((not rule2) and (not rule3)))
Managing Shipping Options for Products with Undefined or None Attributes
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:
{
"name": "Not Rule",
"slug": "not-rule",
"child": {
"name": "Or Rule",
"slug": "or-rule",
"children": [
{
"attribute_value": "kadikoy",
"attribute_field": "store",
"name": "Product Attribute Rule",
"func": "all",
"slug": "product-attribute-rule"
},
{
"attribute_value": "pendik",
"attribute_field": "store",
"name": "Product Attribute Rule",
"func": "all",
"slug": "product-attribute-rule"
}
]
}
}
- 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 bekadikoy
. - The second child rule specifies that the
attribute_value
for the store must not bependik
.
- The first child rule specifies that the
By implementing this configuration, the shipping options will be visible for all locations except for Kadıköy and Pendik.
Shipping Option Page Rule
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:
Example Configuration
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.
{
"rule": {
"params": {
"page": "ShippingOptionSelectionPage"
},
"klass": "omnishop.payments.rules.ShippingOptionPageRule"
}
}
API Methods
GET
List Attribute Shipping Options
This 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.
Parameter | Data Type | In | Description |
---|---|---|---|
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.
curl --location --request POST 'https://{storefront_url}/orders/checkout/?page=AttributeBasedShippingOptionSelectionPage' \
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.
Key | Type | Description |
---|---|---|
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:
{
"page_context": {
"attribute_based_shipping_options": {
"pendik": {
"attribute_based_shipping_options": [
{
"pk": 1,
"shipping_amount": "39.90",
"shipping_option_name": "Shipping Company A",
"shipping_option_logo": null
}
],
"product_ids": [
535
],
"attribute_key": [
"store"
]
},
"kadikoy": {
"attribute_based_shipping_options": [
{
"pk": 3,
"shipping_amount": "59.90",
"shipping_option_name": "Shipping Company B",
"shipping_option_logo": null
}
],
"product_ids": [
536
],
"attribute_key": [
"store"
]
}
}
},
"page_name": "AttributeBasedShippingOptionSelectionPage",
"page_slug": "attributebasedshippingoptionselectionpage"
}
POST
Select Attribute Based Shipping Options
This 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.
Parameter | Data Type | In | Required | Description |
---|---|---|---|---|
attribute_based_shipping_options | dict | body | Yes | Dictionary containing PKs of selected shipping options categorized by attribute names. |
Example Request
curl --location '<https://{storefront_url}/orders/checkout/?page=AttributeBasedShippingOptionSelectionPage>' \\
--data 'attribute_based_shipping_options={"pendik": 1, "kadikoy": 2}'
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.
{
...
"attribute_based_shipping_options": [
{
"pk": 135,
"shipping_option_name": "Shipping Company A",
"shipping_option_logo": null,
"shipping_amount": "39.90",
"product_ids": [
535
],
"attribute_value": "pendik",
"attribute_key": [
"store"
]
},
{
"pk": 134,
"shipping_option_name": "Shipping Company B",
"shipping_option_logo": null,
"shipping_amount": "59.90",
"product_ids": [
536
],
"attribute_value": "kadikoy",
"attribute_key": [
"store"
]
}
]
}
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:
{
"errors": {
"attribute_based_shipping_options": [
"Invalid pk \"5\" - object does not exist."
]
}
}
"errors":{
"attribute_based_shipping_options":"This field is required"
}