ECO-598: Ecommerce Objects

Readme.md

@@ -77,6 +77,13 @@ For more information how to obtain an API key visit the [following link](https:/
     - [Get a list of timezones](#get-a-list-of-timezones)
   - [Campaign languages](#campaign-languages)
     - [Get a list of languages](#get-a-list-of-languages)
+  - [E-commerce](#e-commerce)
+    - [Shops](#shops)
+    - [Products and variants](#products-and-variants)
+    - [Categories](#categories)
+    - [Customers, orders and carts](#customers-orders-and-carts)
+    - [Imports](#imports)
+    - [Revenue reports and settings](#revenue-reports-and-settings)
 
 ## Installation
 <a name="installation"></a>
@@ -901,3 +908,113 @@ client = MailerLite.Client({
 
 response = client.campaigns.languages()
 ```
+
+## E-commerce
+<a name="e-commerce"></a>
+
+Every e-commerce call takes the shop ID first. The examples below assume:
+
+```python
+import mailerlite as MailerLite
+
+client = MailerLite.Client({
+  'api_key': 'your-api-key'
+})
+```
+
+### Shops
+<a name="shops"></a>
+
+```python
+client.ecommerce_shops.list(limit=25)
+client.ecommerce_shops.get(1234)
+client.ecommerce_shops.create('My shop', 'https://shop.example.com', 'EUR')
+client.ecommerce_shops.update(1234, name='New name')
+client.ecommerce_shops.delete(1234)
+```
+
+### Products and variants
+<a name="products-and-variants"></a>
+
+```python
+client.ecommerce_products.list(1234, filter={'enabled': True}, sort='-created_at')
+client.ecommerce_products.get(1234, 5678)
+client.ecommerce_products.create(1234, 'Red T-shirt', price=19.99)
+client.ecommerce_products.update(1234, 5678, price=24.99)
+client.ecommerce_products.delete(1234, 5678)
+client.ecommerce_products.change_status(1234, 5678, False)
+client.ecommerce_products.assign_categories(1234, 5678, [91], replace=True)
+
+client.ecommerce_product_variants.list(1234, 5678)
+client.ecommerce_product_variants.sync(1234, 5678, [{'name': 'Large', 'attributes': {'size': 'L'}, 'resource_id': 'variant-l'}])
+client.ecommerce_product_variants.update(1234, 5678, 42, 'Extra large', {'size': 'XL'})
+client.ecommerce_product_variants.delete(1234, 5678, 42)
+```
+
+### Categories
+<a name="categories"></a>
+
+```python
+client.ecommerce_categories.list(1234)
+client.ecommerce_categories.get(1234, 91)
+client.ecommerce_categories.create(1234, 'Hats')
+client.ecommerce_categories.update(1234, 91, name='Caps')
+client.ecommerce_categories.delete(1234, 91)
+client.ecommerce_categories.products(1234, 91)
+client.ecommerce_categories.assign_product(1234, 91, 5678)
+client.ecommerce_categories.unassign_product(1234, 91, 5678)
+```
+
+### Customers, orders and carts
+<a name="customers-orders-and-carts"></a>
+
+```python
+client.ecommerce_customers.list(1234, filter={'email': 'customer@example.com'})
+client.ecommerce_customers.create(1234, 'customer@example.com', create_subscriber=True)
+client.ecommerce_customers.update(1234, 77, name='Jane')
+client.ecommerce_customers.delete(1234, 77)
+
+client.ecommerce_orders.list(1234, filter={'attributed': True, 'email_id': 555})
+client.ecommerce_orders.create(
+    1234,
+    {'email': 'customer@example.com'},
+    {'items': [{'ecommerce_product_id': 5678, 'quantity': 1, 'price': 19.99}]},
+    status='complete',
+)
+client.ecommerce_orders.update(1234, 99, status='complete')
+client.ecommerce_orders.delete(1234, 99)
+
+client.ecommerce_carts.list(1234)
+client.ecommerce_carts.update(1234, 33, checkout_url='https://shop.example.com/cart')
+client.ecommerce_cart_items.list(1234, 33)
+client.ecommerce_cart_items.update(1234, 33, 8, quantity=2)
+client.ecommerce_cart_items.delete(1234, 33, 8)
+```
+
+### Imports
+<a name="imports"></a>
+
+```python
+client.ecommerce_imports.products(1234, [{'name': 'Red T-shirt', 'price': 19.99}])
+client.ecommerce_imports.categories(1234, [{'name': 'Hats'}])
+client.ecommerce_imports.customers(1234, [{'email': 'customer@example.com'}])
+```
+
+### Revenue reports and settings
+<a name="revenue-reports-and-settings"></a>
+
+```python
+client.ecommerce_shops.stats(1234, '2026-10-01', '2026-10-31')
+
+client.campaigns.ecommerce_stats(1111, 1234)
+client.campaigns.ecommerce_orders(1111, 1234)
+
+client.subscribers.ecommerce_stats(2222, 1234)
+client.subscribers.ecommerce_orders(2222, 1234)
+
+client.automations.ecommerce_stats(3333)
+client.automations.email_ecommerce_stats(3333, 4444)
+client.automations.ecommerce_orders(3333, 'all_time')
+
+client.ecommerce_settings.get()
+```

mailerlite/__init__.py

@@ -8,6 +8,16 @@
 
 # import all api files into api package
 from mailerlite.sdk.campaigns import Campaigns
+from mailerlite.sdk.ecommerce_carts import EcommerceCarts
+from mailerlite.sdk.ecommerce_cart_items import EcommerceCartItems
+from mailerlite.sdk.ecommerce_categories import EcommerceCategories
+from mailerlite.sdk.ecommerce_customers import EcommerceCustomers
+from mailerlite.sdk.ecommerce_imports import EcommerceImports
+from mailerlite.sdk.ecommerce_orders import EcommerceOrders
+from mailerlite.sdk.ecommerce_product_variants import EcommerceProductVariants
+from mailerlite.sdk.ecommerce_products import EcommerceProducts
+from mailerlite.sdk.ecommerce_settings import EcommerceSettings
+from mailerlite.sdk.ecommerce_shops import EcommerceShops
 from mailerlite.sdk.fields import Fields
 from mailerlite.sdk.forms import Forms
 from mailerlite.sdk.groups import Groups
@@ -33,3 +43,13 @@ def __init__(self, config={}):
         self.webhooks = Webhooks(self.api_client)
         self.automations = Automations(self.api_client)
         self.batches = Batches(self.api_client)
+        self.ecommerce_shops = EcommerceShops(self.api_client)
+        self.ecommerce_products = EcommerceProducts(self.api_client)
+        self.ecommerce_product_variants = EcommerceProductVariants(self.api_client)
+        self.ecommerce_categories = EcommerceCategories(self.api_client)
+        self.ecommerce_customers = EcommerceCustomers(self.api_client)
+        self.ecommerce_orders = EcommerceOrders(self.api_client)
+        self.ecommerce_carts = EcommerceCarts(self.api_client)
+        self.ecommerce_cart_items = EcommerceCartItems(self.api_client)
+        self.ecommerce_imports = EcommerceImports(self.api_client)
+        self.ecommerce_settings = EcommerceSettings(self.api_client)

mailerlite/sdk/automations.py

@@ -82,3 +82,101 @@ def activity(self, automation_id, **kwargs):
             f"{self.base_api_url}/{automation_id}/activity",
             query_params,
         ).json()
+
+    def ecommerce_stats(self, automation_id, **kwargs):
+        """
+        Get the orders and revenue an automation earned
+        Ref: https://developers.mailerlite.com/docs/automations.html
+
+        :param automation_id: int Automation ID
+        :param **kwargs: You can pass additional arguments - shop_id, start_date or end_date
+        :return: JSON array
+        :rtype: dict
+        """
+
+        if not isinstance(automation_id, int):
+            raise TypeError(
+                f"`automation_id` type is not valid. Expected `int`, got {type(automation_id)}."
+            )
+
+        query_params = {}
+        for key, val in kwargs.items():
+            if key not in ["shop_id", "start_date", "end_date"]:
+                raise TypeError("Got an unknown argument '%s'" % key)
+            query_params[key] = val
+
+        return self.api_client.request(
+            "GET",
+            f"{self.base_api_url}/{automation_id}/monthly-totals/ecommerce",
+            query_params,
+        ).json()
+
+    def email_ecommerce_stats(self, automation_id, email_id, **kwargs):
+        """
+        Get the orders and revenue one automation email earned
+        Ref: https://developers.mailerlite.com/docs/automations.html
+
+        :param automation_id: int Automation ID
+        :param email_id: int Email ID
+        :param **kwargs: You can pass additional arguments - shop_id, start_date or end_date
+        :return: JSON array
+        :rtype: dict
+        """
+
+        if not isinstance(automation_id, int):
+            raise TypeError(
+                f"`automation_id` type is not valid. Expected `int`, got {type(automation_id)}."
+            )
+
+        if not isinstance(email_id, int):
+            raise TypeError(
+                f"`email_id` type is not valid. Expected `int`, got {type(email_id)}."
+            )
+
+        query_params = {}
+        for key, val in kwargs.items():
+            if key not in ["shop_id", "start_date", "end_date"]:
+                raise TypeError("Got an unknown argument '%s'" % key)
+            query_params[key] = val
+
+        return self.api_client.request(
+            "GET",
+            f"{self.base_api_url}/{automation_id}/emails/{email_id}/ecommerce-overview-stats",
+            query_params,
+        ).json()
+
+    def ecommerce_orders(self, automation_id, time_frame, **kwargs):
+        """
+        List the orders attributed to an automation
+        Ref: https://developers.mailerlite.com/docs/automations.html
+
+        :param automation_id: int Automation ID
+        :param time_frame: str week, month, two_months, three_months, six_months, year, last_year, all_time or custom
+        :param **kwargs: You can pass additional arguments - time_frame_start, time_frame_end, ecommerce_shop_id, page or limit
+        :return: JSON array
+        :rtype: dict
+        """
+
+        if not isinstance(automation_id, int):
+            raise TypeError(
+                f"`automation_id` type is not valid. Expected `int`, got {type(automation_id)}."
+            )
+
+        available_params = [
+            "time_frame_start",
+            "time_frame_end",
+            "ecommerce_shop_id",
+            "page",
+            "limit",
+        ]
+        query_params = {"time_frame": time_frame}
+        for key, val in kwargs.items():
+            if key not in available_params:
+                raise TypeError("Got an unknown argument '%s'" % key)
+            query_params[key] = val
+
+        return self.api_client.request(
+            "GET",
+            f"{self.base_api_url}/{automation_id}/order-activity",
+            query_params,
+        ).json()

mailerlite/sdk/campaigns.py

@@ -192,3 +192,54 @@ def languages(self):
         """
 
         return self.api_client.request("GET", f"{self.base_api_url}/languages").json()
+
+    def ecommerce_stats(self, campaign_id, shop_id):
+        """
+        Get the orders and revenue a campaign earned in one shop
+        Ref: https://developers.mailerlite.com/docs/ecommerce/shops
+
+        :param campaign_id: int Campaign ID
+        :param shop_id: int Shop ID
+        :return: JSON array
+        :rtype: dict
+        """
+
+        if not isinstance(campaign_id, int):
+            raise TypeError(
+                f"`campaign_id` type is not valid. Expected `int`, got {type(campaign_id)}."
+            )
+
+        return self.api_client.request(
+            "GET",
+            f"{self.base_api_url}/{campaign_id}/reports/ecommerce",
+            {"shop_id": shop_id},
+        ).json()
+
+    def ecommerce_orders(self, campaign_id, shop_id, **kwargs):
+        """
+        List the orders a campaign has in one shop
+        Ref: https://developers.mailerlite.com/docs/ecommerce/shops
+
+        :param campaign_id: int Campaign ID
+        :param shop_id: int Shop ID
+        :param **kwargs: You can pass additional arguments - page or limit
+        :return: JSON array
+        :rtype: dict
+        """
+
+        if not isinstance(campaign_id, int):
+            raise TypeError(
+                f"`campaign_id` type is not valid. Expected `int`, got {type(campaign_id)}."
+            )
+
+        query_params = {"shop_id": shop_id}
+        for key, val in kwargs.items():
+            if key not in ["page", "limit"]:
+                raise TypeError("Got an unknown argument '%s'" % key)
+            query_params[key] = val
+
+        return self.api_client.request(
+            "GET",
+            f"{self.base_api_url}/{campaign_id}/reports/ecommerce/orders",
+            query_params,
+        ).json()