diff --git a/add-custom-shipping-carrier.md b/add-custom-shipping-carrier.md
new file mode 100644
index 0000000..acb74ca
--- /dev/null
+++ b/add-custom-shipping-carrier.md
@@ -0,0 +1,235 @@
+# Add custom shipping carrier
+
+[TOC]
+
+Mage-OS allows the creation of custom shipping carriers to handle various shipping methods for
+different carriers or logistics providers. A custom shipping carrier can be added by creating a
+Mage-OS module and configuring the required fields to handle shipping calculations,
+carrier configurations, and frontend integration.
+
+## Module Setup
+
+The first step in adding a custom shipping carrier is creating the necessary directory structure
+for the Mage-OS module:
+
+```bash
+app/code/MageOS/ShippingCarrier/
+├── registration.php
+├── composer.json
+├── etc
+│ ├── module.xml
+│ ├── config.xml
+│ ├── adminhtml
+ └── system.xml
+├── Model
+│ └── Carrier
+│ └── CustomCarrier.php
+```
+
+Create register module file `app/code/MageOS/ShippingCarrier/registration.php`
+
+```php
+
+
+
+
+```
+
+## Shipping Carrier Configuration
+
+In the `config.xml` file, define the shipping carrier's core settings, such as its active state,
+title, and allowed countries. Create `app/code/MageOS/ShippingCarrier/etc/config.xml`:
+
+```xml
+
+
+
+
+
+ 1
+ Custom Shipping Carrier
+ Custom Shipping Method Name
+ 10
+ 0
+ 15
+ MageOS\ShippingCarrier\Model\Carrier\CustomCarrier
+
+
+
+
+```
+
+Explanation:
+
+- active: Enables or disables the custom carrier.
+- title: The name displayed in the checkout.
+- name: Internal name of the carrier.
+- model: The path to the custom shipping carrier model.
+- shipping_cost: The amount of the handling fee.
+
+## Admin Configuration for Carrier
+
+To allow store administrators to configure the shipping method, we define settings in
+`app/code/MageOS/ShippingCarrier/etc/adminhtml/system.xml`:
+
+```xml
+
+
+
+
+
+
+
+
+ Magento\Config\Model\Config\Source\Yesno
+
+
+
+
+
+
+
+
+
+ validate-number validate-zero-or-greater
+
+
+
+ shipping-applicable-country
+ Magento\Shipping\Model\Config\Source\Allspecificcountries
+
+
+
+ Magento\Directory\Model\Config\Source\Country
+ 1
+
+
+
+ Magento\Config\Model\Config\Source\Yesno
+ shipping-skip-hide
+
+
+
+
+
+
+
+
+```
+
+This configuration allows administrators to enable the carrier, set a title, and configure a handling
+fee through the Mage-OS admin panel.
+
+## Shipping Carrier Model
+
+The core logic for the custom shipping carrier is in the CustomCarrier.php model.
+This class extends Mage-OS's abstract shipping carrier class and implements the shipping calculation and rates.
+
+```php
+rateResultFactory = $rateResultFactory;
+ $this->rateMethodFactory = $rateMethodFactory;
+ }
+
+ /**
+ * Custom Shipping Rates Collector
+ *
+ * @param RateRequest $request
+ * @return \Magento\Shipping\Model\Rate\Result|bool
+ */
+ public function collectRates(RateRequest $request)
+ {
+ if (!$this->getConfigFlag('active')) {
+ return false;
+ }
+
+ /** @var Method $method */
+ $method = $this->rateMethodFactory->create();
+
+ $method->setCarrier($this->_code);
+ $method->setCarrierTitle($this->getConfigData('title'));
+
+ $method->setMethod($this->_code);
+ $method->setMethodTitle($this->getConfigData('name'));
+
+ $shippingPrice = (float)$this->getConfigData('shipping_cost');
+ $method->setPrice($shippingPrice);
+ $method->setCost($shippingPrice);
+ $method->setDataUsingMethod('cost', $shippingPrice);
+
+ /** @var Result $result */
+ $result = $this->rateResultFactory->create();
+ $result->append($method);
+
+ return $result;
+ }
+
+ public function getAllowedMethods(): array
+ {
+ return [$this->_code => $this->getConfigData('name')];
+ }
+}
+```
+
+Explanation:
+
+- collectRates(): Calculates shipping rates based on the quote request and returns them.
+ Here, a fixed rate of 10.00 is used.
+- getAllowedMethods(): Returns the allowed shipping methods for this carrier.
+
+## Frontend Integration
+
+Once the backend logic is in place, the custom shipping carrier will automatically appear in the Mage-OS checkout
+if it's enabled and configured properly. The title and price will be displayed as defined in the carrier configuration.
+
+## Conclusion
+This guide walks through the basic setup of a custom shipping carrier in Mage-OS. The carrier integrates with Mage-OS’s shipping framework, allowing you to customize the shipping calculation and display it during the checkout process. You can extend this basic structure to integrate with third-party APIs, offer dynamic shipping rates, or introduce more complex shipping logic based on cart contents or customer information.
diff --git a/documentation.md b/documentation.md
index d10e17d..12bbc26 100644
--- a/documentation.md
+++ b/documentation.md
@@ -73,6 +73,7 @@
- ## Tutorials & Examples
- [Collection of real-world examples, and step-by-step tutorials](/docs/{{version}}/collection-of-real-world-examples-and-step-by-step-tutorials)
- [Case studies of problem-solving in Magento 2](/docs/{{version}}/case-studies-of-problem-solving-in-magento-2)
+ - [Add custom shipping carrier](/docs/{{version}}/add-custom-shipping-carrier)
- ## Community & Support
- [Get help and support](/docs/{{version}}/how-to-get-help-and-support)
- [Community Contribution](/docs/{{version}}/how-to-contribute-to-the-magento-2-community)