# Notification Extension The Notification Module enables sending notifications to customers through external messaging gateways for order-related events. This document provides the technical setup required to enable this feature, including backend configuration, payload structures, and how the external service (extension) should operate. ## Prerequisites * An external messaging service endpoint must be available to receive notification payloads. * The endpoint must support HTTP Basic Authentication. * The endpoint must accept JSON payloads via POST requests. ## Configurations A dynamic configuration named `NOTIFICATION_GATEWAYS` must be defined via **Sales Channels > Sales Channel Settings > Dynamic Setting** in the admin panel. This configuration must include both a gateway class and configuration section: ```python NOTIFICATION_GATEWAY = "default" NOTIFICATION_GATEWAYS = { "default": { "klass": "omnishop.libs.notification_gateways.notification_extensions.gateway.NotificationExtensionGateway", "conf": { "username": "your_username", "password": "your_password", "send_url": "https://example.com/api/notification", "from_number": "your_sender_id" } } } ``` ### Configuration Parameters
ParameterTypeDescription
klassstringGateway class path
conf.usernamestringHTTP Basic Auth username
conf.passwordstringHTTP Basic Auth password
conf.send_urlstringFull URL of the notification endpoint including protocol, domain, and path (e.g., https://example.com/api/notification)
conf.from_numberstringSender identifier (phone number or alias)
### Available Gateways
GatewayClass PathDescription
Consoleomnishop.libs.notification_gateways.console.NotificationBackendLogs to console (development only)
Extensionomnishop.libs.notification_gateways.notification_extensions.gateway.NotificationExtensionGatewayHTTP POST with Basic Auth (production)
## Notification Flow The Notification flow is triggered during various order lifecycle events: 1. An order event occurs (e.g., order delivered, order shipped). 2. The system checks if the notification gateway is configured. 3. Commerce sends a POST request to the external service defined in `NOTIFICATION_GATEWAYS`. 4. The payload includes order details, user information, and event type. 5. The external gateway service receives the payload and handles the message delivery. ### `POST` Send Notification **Path:** `https://example.com/api/notification` The extension must expose a POST endpoint that accepts notification payloads in the following format. The request includes HTTP Basic Authentication headers. #### Request Headers ``` Authorization: Basic base64(username:password) Content-Type: application/json ``` #### Base Payload Structure ```json { "from": "akinon", "to": "+905551234567", "event": "order_delivered", "payload": { ... }, "site_domain": "www.example.com", "receiver_user": { ... } } ```
FieldTypeDescription
fromstringSender identifier configured in from_number
tostringRecipient phone number with country code
eventstringEvent type that triggered the notification
payloadobjectEvent-specific data
site_domainstringSite domain
receiver_userobjectUser information (optional)
### Notification Events The following events trigger notifications: | Event | Description | Payload Type | | ------------------------------- | --------------------------------------------------- | -------------------------- | | `order_delivered` | Order has been delivered to the customer | Order Payload | | `product_alert` | Product is back in stock (stock alert subscription) | Product Alert Payload | | `order_cancellation` | Order or items have been cancelled | Order Cancellation Payload | | `pay_on_delivery` | Pay on delivery order created | Order Payload | | `order_completed` | Order successfully completed | Order Payload | | `order_refund_result` | Refund has been processed | Order Payload | | `order_shipped_cargo` | Order shipped via cargo | Order Payload | | `order_shipped_partial_cargo` | Partial shipment sent | Partial Shipment Payload | | `order_ready_for_pick_up` | Order ready for customer pickup | Order Payload | | `order_e_archive_url_available` | E-archive invoice URL available | Order Payload | | `order_checkout_url_with_token` | Checkout URL with authentication token | Checkout URL Payload | #### Example Payloads **Order Event Payload:** Used by: `order_delivered`, `pay_on_delivery`, `order_completed`, `order_refund_result`, `order_shipped_cargo`, `order_ready_for_pick_up`, `order_e_archive_url_available` ```json { "from": "akinon", "to": "+905551234567", "event": "order_delivered", "payload": { "order": { "pk": 12345, "number": "ORD-2024-00001", "status": { "value": "550", "label": "delivered" }, "currency": { "value": "try", "label": "TL" }, "amount": "1250.00", "discount_amount": "50.00", "shipping_amount": "15.00", "shipping_tax_rate": "18.00", "refund_amount": "0.00", "discount_refund_amount": "0.00", "shipping_refund_amount": "0.00", "invoice_number": "INV-2024-00001", "invoice_date": "2024-01-15T10:30:00Z", "e_archive_url": "https://example.com/e-archive/INV-2024-00001", "tracking_number": "TRK123456789", "defined_tracking_url": null, "remote_addr": "192.168.1.1", "has_gift_box": false, "gift_box_note": null, "language_code": "en", "notes": null, "delivery_range": null, "shipping_option_slug": "standard-shipping", "extra_field": {}, "user": 1001, "user_email": "john.doe@example.com", "basket": 5001, "shipping_option": 1, "payment_option": { "pk": 1, "name": "Credit Card", "payment_type": "credit_card", "slug": "credit-card" }, "card": 101, "bin_number": "123456", "installment": 1, "installment_count": 1, "installment_interest_amount": "0.00", "segment": 1, "shipping_tracking_url": null, "checkout_provider": null, "created_date": "2024-01-15T10:30:00Z", "modified_date": "2024-01-16T14:20:00Z", "amount_without_discount": "1300.00", "is_cancelled": false, "is_cancellable": false, "is_refundable": true, "is_payable": false, "tracking_url": "https://tracking.example.com/TRK123456789", "client_type": { "value": "default", "label": "default" }, "shipping_company": { "value": "yurtici", "label": "Yurtiçi Kargo" }, "shipping_address": { "pk": 5001, "email": "john.doe@example.com", "phone_number": "+905551234567", "first_name": "John", "last_name": "Doe", "country": { "pk": 1, "name": "Turkey", "code": "TR", "is_active": true }, "city": { "pk": 34, "name": "Istanbul", "is_active": true }, "line": "123 Main Street, Apt 4B", "title": "Home", "township": { "pk": 340, "name": "Kadikoy", "is_active": true }, "district": { "pk": 3401, "name": "Moda", "is_active": true }, "postcode": "34710", "notes": null, "company_name": null, "tax_office": null, "tax_no": null, "e_bill_taxpayer": false, "hash_data": "abc123...", "address_type": { "value": "customer", "label": "Customer" }, "retail_store": null, "remote_id": null, "identity_number": null, "extra_field": {}, "user": { "pk": 1001, "username": "john.doe@example.com", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "is_active": true, "date_joined": "2024-01-01T10:00:00Z", "last_login": "2024-01-16T09:00:00Z", "email_allowed": true, "sms_allowed": true, "whatsapp_allowed": true, "call_allowed": false, "gender": { "value": "male", "label": "male" }, "attributes": {}, "phone": "+905551234567", "date_of_birth": "1990-05-15", "attributes_kwargs": {}, "user_type": { "value": "registered", "label": "Registered" }, "modified_date": "2024-01-16T09:00:00Z" } }, "billing_address": { "pk": 5002, "email": "john.doe@example.com", "phone_number": "+905551234567", "first_name": "John", "last_name": "Doe", "country": { "pk": 1, "name": "Turkey", "code": "TR", "is_active": true }, "city": { "pk": 34, "name": "Istanbul", "is_active": true }, "line": "123 Main Street, Apt 4B", "title": "Home", "township": { "pk": 340, "name": "Kadikoy", "is_active": true }, "district": { "pk": 3401, "name": "Moda", "is_active": true }, "postcode": "34710", "notes": null, "company_name": null, "tax_office": null, "tax_no": null, "e_bill_taxpayer": false, "hash_data": "def456...", "address_type": { "value": "customer", "label": "Customer" }, "retail_store": null, "remote_id": null, "identity_number": null, "extra_field": {}, "user": { "pk": 1001, "username": "john.doe@example.com", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "is_active": true, "date_joined": "2024-01-01T10:00:00Z", "last_login": "2024-01-16T09:00:00Z", "email_allowed": true, "sms_allowed": true, "whatsapp_allowed": true, "call_allowed": false, "gender": { "value": "male", "label": "male" }, "attributes": {}, "phone": "+905551234567", "date_of_birth": "1990-05-15", "attributes_kwargs": {}, "user_type": { "value": "registered", "label": "Registered" }, "modified_date": "2024-01-16T09:00:00Z" } }, "bank": { "pk": 1, "name": "Example Bank", "slug": "example-bank", "logo": "https://cdn.example.com/bank-logos/example-bank.png", "logo_path": null }, "orderitem_set": [ { "pk": 50001, "order": 12345, "status": { "value": "550", "label": "delivered" }, "price": "299.00", "price_currency": { "value": "try", "label": "TL" }, "tax_rate": "18.00", "invoice_number": "INV-2024-00001-001", "invoice_date": "2024-01-15T10:30:00Z", "e_archive_url": null, "tracking_number": "TRK123456789", "defined_tracking_url": null, "shipping_company": { "value": "yurtici", "label": "Yurtiçi Kargo" }, "defined_shipping_company": null, "retail_price": "350.00", "image": null, "parent": null, "extra_field": {}, "estimated_delivery_date": "2024-01-20", "shipped_date": "2024-01-16T09:00:00Z", "delivered_date": "2024-01-18T14:30:00Z", "attributes": { "color": "Black", "size": "M" }, "attributes_kwargs": { "color": { "label": "Color" }, "size": { "label": "Size" } }, "localized_attributes": {}, "localized_attributes_kwargs": {}, "extra_product_price": 1001, "extra_product_stock": 1001, "shipping_tracking_url": null, "datasource": 1, "shipping_option_group": { "pk": 1, "amount": "15.00", "shipping_option_name": "Standard Shipping", "shipping_option_logo": "https://cdn.example.com/logos/standard.png" }, "discount_amount": "24.00", "is_cancelled": false, "is_cancellable": false, "is_refundable": true, "is_tradable": false, "tracking_url": "https://tracking.example.com/TRK123456789", "discounted_price": "275.00", "cancellationrequest_set": [], "active_cancellation_request": null, "available_easy_return_shipping_companies": [], "datasource_detailed": null, "extra_product_stock_detailed": null, "extra_product_price_detailed": null, "product": { "pk": 1001, "sku": "TSH-001-BLK-M", "base_code": "TSH-001", "name": "Premium Cotton T-Shirt", "image": "https://cdn.example.com/images/tshirt-001.jpg", "absolute_url": "/products/premium-cotton-t-shirt/", "attributes": { "color": "Black", "size": "M" }, "attributes_kwargs": { "color": { "label": "Color" }, "size": { "label": "Size" } }, "form_schema": null, "data_source": null, "extra_attributes": {}, "category": null, "attribute_set": 1 } } ], "discountitem_set": [ { "name": "Summer Sale", "amount": "50.00", "created_date": "2024-01-15T10:30:00Z", "order_number": "ORD-2024-00001", "currency": { "value": "try", "label": "TL" } } ], "loyaltytransaction_set": [ { "pk": 1, "uuid": "550e8400-e29b-41d4-a716-446655440000", "amount": "100.00", "order": 12345, "user": 1001, "user_email": "john.doe@example.com", "reference": "LOYALTY-2024-00001" } ] } }, "site_domain": "www.example.com", "receiver_user": { "id": 1001, "first_name": "John", "last_name": "Doe", "email_allowed": true, "sms_allowed": true, "call_allowed": false, "whatsapp_allowed": true, "avatar": null, "email": "john.doe@example.com", "phone": "+905551234567", "date_of_birth": "1990-05-15", "gender": { "value": "male", "label": "male" }, "genders": [ { "value": "male", "label": "male" }, { "value": "female", "label": "female" } ], "language_code": "en", "attributes": {}, "date_joined": "2024-01-01T10:00:00Z" } } ``` **Product Alert Payload:** Used by: `product_alert` Sent when a product that a user subscribed to for stock alerts becomes available (stock quantity meets the configured threshold). ```json { "from": "akinon", "to": "+905551234567", "event": "product_alert", "payload": { "product": { "pk": 1001, "name": "Premium Cotton T-Shirt", "base_code": "TSH-001", "sku": "TSH-001-BLK-M", "product_type": { "value": "0", "label": "Simple" }, "is_active": true, "parent": null, "attributes": { "color": "Black", "size": "M", "material": "Cotton" }, "attributes_kwargs": { "color": { "label": "Color", "data_type": "dropdown" }, "size": { "label": "Size", "data_type": "dropdown" } }, "extra_attributes": {}, "is_seller_product": false, "group_products": [], "productimage_set": [ { "pk": 3001, "status": { "value": "active", "label": "Active" }, "image": "https://cdn.example.com/images/tshirt-001.jpg", "order": 1, "created_date": "2024-01-01T10:00:00Z", "specialimage_set": [] } ], "attribute_set": 1, "custom_attribute_set": null, "is_listable": true, "listing_code": "TSH-001-BLK-M", "data_source": null, "absolute_url": "/products/premium-cotton-t-shirt/?color=Black&size=M", "is_form_required": false } }, "site_domain": "www.example.com", "receiver_user": { "id": 1001, "first_name": "John", "last_name": "Doe", "email_allowed": true, "sms_allowed": true, "call_allowed": false, "whatsapp_allowed": true, "avatar": null, "email": "john.doe@example.com", "phone": "+905551234567", "date_of_birth": "1990-05-15", "gender": { "value": "male", "label": "male" }, "genders": [ { "value": "male", "label": "male" }, { "value": "female", "label": "female" } ], "language_code": "en", "attributes": {}, "date_joined": "2024-01-01T10:00:00Z" } } ``` **Order Cancellation Payload:** Used by: `order_cancellation` ```json { "from": "akinon", "to": "+905551234567", "event": "order_cancellation", "payload": { "order": { "pk": 12345, "number": "ORD-2024-00001", "status": { "value": "100", "label": "cancelled" }, "currency": { "value": "try", "label": "TL" }, "amount": "1250.00", "discount_amount": "50.00", "shipping_amount": "15.00", "amount_without_discount": "1300.00", "is_cancelled": true, "is_cancellable": false, "is_refundable": false, "is_payable": false, "tracking_url": null, "client_type": { "value": "default", "label": "default" }, "shipping_company": null, "shipping_address": { }, "billing_address": { }, "payment_option": { "pk": 1, "name": "Credit Card", "payment_type": "credit_card", "slug": "credit-card" }, "bank": { "pk": 1, "name": "Example Bank", "slug": "example-bank", "logo": null, "logo_path": null }, "orderitem_set": [], "discountitem_set": [], "loyaltytransaction_set": [], "created_date": "2024-01-15T10:30:00Z", "modified_date": "2024-01-16T14:20:00Z" }, "cancellation_type": "cancel", "order_items": [ { "pk": 50001, "order": 12345, "status": { "value": "100", "label": "cancelled" }, "price": "299.00", "price_currency": { "value": "try", "label": "TL" }, "tax_rate": "18.00", "invoice_number": null, "invoice_date": null, "e_archive_url": null, "tracking_number": null, "defined_tracking_url": null, "shipping_company": null, "defined_shipping_company": null, "retail_price": "350.00", "image": null, "parent": null, "extra_field": {}, "estimated_delivery_date": null, "shipped_date": null, "delivered_date": null, "attributes": { "color": "Black", "size": "M" }, "attributes_kwargs": { "color": { "label": "Color" }, "size": { "label": "Size" } }, "localized_attributes": {}, "localized_attributes_kwargs": {}, "extra_product_price": null, "extra_product_stock": null, "shipping_tracking_url": null, "datasource": null, "shipping_option_group": null, "discount_amount": "0.00", "is_cancelled": true, "is_cancellable": false, "is_refundable": false, "is_tradable": false, "tracking_url": null, "discounted_price": "299.00", "cancellationrequest_set": [], "active_cancellation_request": null, "available_easy_return_shipping_companies": [], "datasource_detailed": null, "extra_product_stock_detailed": null, "extra_product_price_detailed": null, "product": { "pk": 1001, "sku": "TSH-001-BLK-M", "base_code": "TSH-001", "name": "Premium Cotton T-Shirt", "image": "https://cdn.example.com/images/tshirt-001.jpg", "absolute_url": "/products/premium-cotton-t-shirt/", "attributes": { "color": "Black", "size": "M" }, "attributes_kwargs": { "color": { "label": "Color" }, "size": { "label": "Size" } }, "form_schema": null, "data_source": null, "extra_attributes": {}, "category": null, "attribute_set": 1 } } ], "return_code": "RET-2024-00123" }, "site_domain": "www.example.com", "receiver_user": { "id": 1001, "first_name": "John", "last_name": "Doe", "email_allowed": true, "sms_allowed": true, "call_allowed": false, "whatsapp_allowed": true, "avatar": null, "email": "john.doe@example.com", "phone": "+905551234567", "date_of_birth": "1990-05-15", "gender": { "value": "male", "label": "male" }, "genders": [ { "value": "male", "label": "male" }, { "value": "female", "label": "female" } ], "language_code": "en", "attributes": {}, "date_joined": "2024-01-01T10:00:00Z" } } ```
FieldTypeDescription
cancellation_typestringcancel (before shipment) or refund (after delivery)
order_itemsarrayCancelled items (only included if specific items cancelled)
return_codestringReturn code if applicable (only included when present)
{% hint style="warning" %} The `order_items` and `return_code` fields are optional. They are only included in the payload when specific items are cancelled or when a return code exists. {% endhint %} **Partial Shipment Payload:** Used by: `order_shipped_partial_cargo` ```json { "from": "akinon", "to": "+905551234567", "event": "order_shipped_partial_cargo", "payload": { "order": { "pk": 12345, "number": "ORD-2024-00001", "status": { "value": "500", "label": "shipped" }, "currency": { "value": "try", "label": "TL" }, "amount": "1250.00", "discount_amount": "50.00", "shipping_amount": "15.00", "amount_without_discount": "1300.00", "is_cancelled": false, "is_cancellable": false, "is_refundable": false, "is_payable": false, "tracking_url": "https://tracking.example.com/TRK123456789", "client_type": { "value": "default", "label": "default" }, "shipping_company": { "value": "dhlexpress", "label": "DHL Express" }, "shipping_address": { }, "billing_address": { }, "payment_option": { "pk": 1, "name": "Credit Card", "payment_type": "credit_card", "slug": "credit-card" }, "bank": null, "orderitem_set": [], "discountitem_set": [], "loyaltytransaction_set": [], "created_date": "2024-01-15T10:30:00Z", "modified_date": "2024-01-16T14:20:00Z" }, "tracking_number": "TRK123456789", "shipping_company": "DHL Express", "order_items": [ { "pk": 50001, "order": 12345, "status": { "value": "500", "label": "shipped" }, "price": "299.00", "price_currency": { "value": "try", "label": "TL" }, "tax_rate": "18.00", "invoice_number": null, "invoice_date": null, "e_archive_url": null, "tracking_number": "TRK123456789", "defined_tracking_url": null, "shipping_company": { "value": "dhlexpress", "label": "DHL Express" }, "defined_shipping_company": null, "retail_price": "350.00", "image": null, "parent": null, "extra_field": {}, "estimated_delivery_date": "2024-01-20", "shipped_date": "2024-01-16T09:00:00Z", "delivered_date": null, "attributes": { "color": "Black", "size": "M" }, "attributes_kwargs": { "color": { "label": "Color" }, "size": { "label": "Size" } }, "localized_attributes": {}, "localized_attributes_kwargs": {}, "extra_product_price": null, "extra_product_stock": null, "shipping_tracking_url": null, "datasource": null, "shipping_option_group": { "pk": 1, "amount": "15.00", "shipping_option_name": "Express Shipping", "shipping_option_logo": "https://cdn.example.com/logos/express.png" }, "discount_amount": "0.00", "is_cancelled": false, "is_cancellable": false, "is_refundable": false, "is_tradable": false, "tracking_url": "https://tracking.example.com/TRK123456789", "discounted_price": "299.00", "cancellationrequest_set": [], "active_cancellation_request": null, "available_easy_return_shipping_companies": [], "datasource_detailed": null, "extra_product_stock_detailed": null, "extra_product_price_detailed": null, "product": { "pk": 1001, "sku": "TSH-001-BLK-M", "base_code": "TSH-001", "name": "Premium Cotton T-Shirt", "image": "https://cdn.example.com/images/tshirt-001.jpg", "absolute_url": "/products/premium-cotton-t-shirt/", "attributes": { "color": "Black", "size": "M" }, "attributes_kwargs": { "color": { "label": "Color" }, "size": { "label": "Size" } }, "form_schema": null, "data_source": null, "extra_attributes": {}, "category": null, "attribute_set": 1 } } ] }, "site_domain": "www.example.com", "receiver_user": { "id": 1001, "first_name": "John", "last_name": "Doe", "email_allowed": true, "sms_allowed": true, "call_allowed": false, "whatsapp_allowed": true, "avatar": null, "email": "john.doe@example.com", "phone": "+905551234567", "date_of_birth": "1990-05-15", "gender": { "value": "male", "label": "male" }, "genders": [ { "value": "male", "label": "male" }, { "value": "female", "label": "female" } ], "language_code": "en", "attributes": {}, "date_joined": "2024-01-01T10:00:00Z" } } ```
FieldTypeDescription
tracking_numberstringTracking number for the partial shipment
shipping_companystringName of the shipping company
order_itemsarrayItems included in this partial shipment
**Checkout URL Payload:** Used by: `order_checkout_url_with_token` ```json { "from": "akinon", "to": "+905551234567", "event": "order_checkout_url_with_token", "payload": { "checkout_url": "https://www.example.com/checkout/?token=abc123def456" }, "site_domain": "www.example.com", "receiver_user": { "id": 1001, "first_name": "John", "last_name": "Doe", "email_allowed": true, "sms_allowed": true, "call_allowed": false, "whatsapp_allowed": true, "avatar": null, "email": "john.doe@example.com", "phone": "+905551234567", "date_of_birth": "1990-05-15", "gender": { "value": "male", "label": "male" }, "genders": [ { "value": "male", "label": "male" }, { "value": "female", "label": "female" } ], "language_code": "en", "attributes": {}, "date_joined": "2024-01-01T10:00:00Z" } } ``` ### Service Behavior * The service must return HTTP 200 for successful processing. * The service should process notifications asynchronously if possible. * Failed notifications should be logged for retry or manual intervention. * The timeout for requests is configurable in the gateway settings. {% hint style="danger" %} The notification gateway does not currently have a built-in retry mechanism. If a notification request fails, it will not be automatically retried. Ensure your external service is highly available or implement your own retry logic on the receiving end. {% endhint %} ### Enum Reference #### Order Status Order and order item status codes. Returned as `{value, label}` object.
ValueLabelDescription
50cancellation waitingCancellation request is pending
100cancelledOrder has been cancelled
200waitingOrder is waiting to be processed
300payment_waitingWaiting for payment confirmation
350confirmation waitingWaiting for order confirmation
400approvedOrder has been approved
450preparingOrder is being prepared
500shippedOrder has been shipped
510shipped_and_informedShipped and customer notified
520ready for pickupReady for customer pickup
540attempted_deliveryDelivery was attempted
544review_startedReview process started (trade-in)
545review_waitingWaiting for review (trade-in)
546waiting_for_paymentWaiting for payment (trade-in)
547paidPayment received (trade-in)
550deliveredOrder delivered to customer
600refundedOrder has been refunded
#### Currency Types ISO 4217 currency codes. Returned as `{value, label}` object.
ValueLabelDescription
tryTLTurkish Lira
eurEUREuro
usdUSDUS Dollar
egpEGPEgyptian Pound
gbpGBPBritish Pound
madMADMoroccan Dirham
plnPLNPolish Zloty
sarSARSaudi Riyal
ronRONRomanian Leu
uahUAHUkrainian Hryvnia
czkCZKCzech Koruna
hufHUFHungarian Forint
rubRUBRussian Ruble
bgnBGNBulgarian Lev
iqdIQDIraqi Dinar
kwdKWDKuwaiti Dinar
bhdBHDBahraini Dinar
omrOMROmani Rial
qarQARQatari Riyal
aedAEDUAE Dirham
ngnNGNNigerian Naira
inrINRIndian Rupee
kztKZTKazakhstani Tenge
jodJODJordanian Dinar
rsdRSDSerbian Dinar
amdAMDArmenian Dram
lydLYDLibyan Dinar
#### Gender Types User gender. Returned as `{value, label}` object. Can be null.
ValueLabel
malemale
femalefemale
#### Client Types Platform where the order was placed.
ValueDescription
defaultWeb browser (desktop or mobile web)
androidAndroid mobile application
iosiOS mobile application
instoreIn-store POS system
b2bB2B portal
#### Product Types Type of product. Returned as `{value, label}` object.
ValueLabelDescription
-1Pre ProductPre-product (draft)
0SimpleSimple product (single SKU)
1Product MetaConfigurable product (parent with variants)
2BundleBundle product (contains multiple products)
3GroupedGrouped product
-2Pre MiscellaneousPre-miscellaneous (draft)
4MiscellaneousMiscellaneous product
5OfferOffer product
#### Shipping Companies Supported shipping carriers. Returned as `{value, label}` object. Can be null.
ValueLabel
arasAras Kargo
upsUPS
yurticiYurtiçi Kargo
mngMNG Kargo
hbexpressHepsi Express
aramexAramex
pttPtt
dhlexpressDHL Express
glsGLS Logistic
dpdDPD Cargo
novaposhtaNova Poshta
cdekCdek
suratSürat Kargo
scottyScotty Cargo
sendeoSendeo Cargo
otherOther
{% hint style="warning" %} Many more shipping companies are supported. See the full list in the codebase. {% endhint %} #### Cancellation Types Type of cancellation in `order_cancellation` event.
ValueDescription
cancelOrder cancelled before shipment
refundRefund after delivery (return)
### Data Models #### Receiver User Based on `UserProfileSerializer`. | Field | Type | Description | | ------------------ | --------------- | ------------------------------------------------ | | `id` | integer | User ID | | `first_name` | string | User's first name | | `last_name` | string | User's last name | | `email_allowed` | boolean | User consent for email marketing | | `sms_allowed` | boolean | User consent for SMS marketing | | `call_allowed` | boolean \| null | User consent for phone calls | | `whatsapp_allowed` | boolean \| null | User consent for WhatsApp messages | | `avatar` | string \| null | User's avatar image URL | | `email` | string | User's email address (read-only) | | `phone` | string | User's phone number | | `date_of_birth` | string \| null | User's birth date (YYYY-MM-DD) | | `gender` | object \| null | User's gender `{value, label}` | | `genders` | array | All available gender options | | `language_code` | string | User's preferred language code | | `attributes` | object | Custom user attributes | | `date_joined` | string | Account creation timestamp (ISO 8601, read-only) | #### Order Based on `UserOrderSerializer`. Includes all Order model fields plus computed fields. | Field | Type | Description | | ----------------------------- | --------------- | -------------------------------------------------------------------------------------------- | | `pk` | integer | Order ID | | `number` | string | Order number (human-readable) | | `status` | object | Order status `{value, label}` | | `currency` | object | Order currency `{value, label}` | | `amount` | string | Total order amount after discounts | | `discount_amount` | string | Total discount applied | | `shipping_amount` | string | Shipping cost | | `shipping_tax_rate` | string \| null | Tax rate applied to shipping | | `refund_amount` | string | Total refund amount | | `discount_refund_amount` | string | Discount refund amount | | `shipping_refund_amount` | string | Shipping refund amount | | `invoice_number` | string \| null | Invoice number | | `invoice_date` | string \| null | Invoice date (ISO 8601) | | `e_archive_url` | string \| null | E-archive URL | | `tracking_number` | string \| null | Shipment tracking number | | `defined_tracking_url` | string \| null | Custom tracking URL | | `remote_addr` | string \| null | Customer IP address | | `has_gift_box` | boolean \| null | Whether order includes gift box | | `gift_box_note` | string \| null | Gift box note | | `language_code` | string \| null | Language code | | `notes` | string \| null | Order notes | | `delivery_range` | object \| null | Delivery date range | | `shipping_option_slug` | string \| null | Shipping option slug | | `extra_field` | object \| null | Additional custom fields | | `user` | integer \| null | User ID | | `user_email` | string | Customer email | | `basket` | integer \| null | Basket ID | | `shipping_option` | integer | Shipping option ID | | `card` | integer \| null | Payment card ID | | `bin_number` | string \| null | Card BIN number | | `installment` | integer \| null | Installment ID | | `installment_count` | integer | Number of installments | | `installment_interest_amount` | string | Interest amount | | `segment` | integer \| null | Segment ID | | `shipping_tracking_url` | string \| null | Shipping tracking URL | | `checkout_provider` | integer \| null | Checkout provider ID | | `created_date` | string | Order creation timestamp (ISO 8601) | | `modified_date` | string | Last modification timestamp (ISO 8601) | | `amount_without_discount` | string | Order amount before discounts (computed) | | `is_cancelled` | boolean | Whether order is cancelled (computed) | | `is_cancellable` | boolean | Whether order can be cancelled (computed) | | `is_refundable` | boolean | Whether order is eligible for refund (computed) | | `is_payable` | boolean | Whether order is awaiting payment (computed) | | `tracking_url` | string \| null | Tracking URL | | `client_type` | object | Platform where order was placed `{value, label}` | | `shipping_company` | object \| null | Shipping carrier `{value, label}` | | `shipping_address` | object \| null | Delivery address (AddressDetailedSerializer) | | `billing_address` | object \| null | Invoice address (AddressDetailedSerializer) | | `payment_option` | object | Payment method with `pk`, `name`, `payment_type`, `slug` | | `bank` | object \| null | Bank information with `pk`, `name`, `slug`, `logo`, `logo_path` | | `orderitem_set` | array | List of items in the order | | `discountitem_set` | array | Discount items with `name`, `amount`, `created_date`, `order_number`, `currency` | | `loyaltytransaction_set` | array | Loyalty transactions with `pk`, `uuid`, `amount`, `order`, `user`, `user_email`, `reference` | #### Address Based on `AddressDetailedSerializer`. | Field | Type | Description | | ----------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pk` | integer | Address ID | | `email` | string \| null | Contact email | | `phone_number` | string | Contact phone number | | `first_name` | string | Recipient first name | | `last_name` | string | Recipient last name | | `country` | object | Country with `pk`, `name`, `code`, `is_active` | | `city` | object | City with `pk`, `name`, `is_active` | | `line` | string | Street address line | | `title` | string | Address label (e.g., Home, Work) | | `township` | object | Township with `pk`, `name`, `is_active` | | `district` | object \| null | District with `pk`, `name`, `is_active` | | `postcode` | string \| null | Postal/ZIP code | | `notes` | string \| null | Address notes | | `company_name` | string \| null | Company name (for corporate addresses) | | `tax_office` | string \| null | Tax office | | `tax_no` | string \| null | Tax number | | `e_bill_taxpayer` | boolean | Whether address is e-bill taxpayer | | `hash_data` | string | Address hash (read-only) | | `address_type` | object | Address type `{value, label}` | | `retail_store` | object \| null | Retail store (for pickup addresses) | | `remote_id` | string \| null | Remote ID | | `identity_number` | string \| null | Identity number | | `extra_field` | object \| null | Additional custom fields | | `user` | object | User with `pk`, `username`, `first_name`, `last_name`, `email`, `is_active`, `date_joined`, `last_login`, `email_allowed`, `sms_allowed`, `whatsapp_allowed`, `call_allowed`, `gender`, `attributes`, `phone`, `date_of_birth`, `attributes_kwargs`, `user_type`, `modified_date` | #### Order Item Based on `UserOrderItemSerializer`. Includes all OrderItem model fields plus computed fields. | Field | Type | Description | | ------------------------------------------ | --------------- | ----------------------------------------------------------------------------------- | | `pk` | integer | Order item ID | | `order` | integer | Order ID (FK) | | `status` | object | Item status `{value, label}` | | `price` | string | Unit price of the item | | `price_currency` | object | Price currency `{value, label}` | | `tax_rate` | string | Tax rate percentage | | `invoice_number` | string \| null | Invoice number | | `invoice_date` | string \| null | Invoice date (ISO 8601) | | `e_archive_url` | string \| null | E-archive URL | | `tracking_number` | string \| null | Shipment tracking number | | `defined_tracking_url` | string \| null | Custom tracking URL | | `shipping_company` | object \| null | Shipping carrier `{value, label}` | | `defined_shipping_company` | string \| null | Custom shipping company name | | `retail_price` | string \| null | Retail price | | `image` | string \| null | Order item image URL | | `parent` | integer \| null | Parent order item ID | | `extra_field` | object \| null | Additional custom fields | | `estimated_delivery_date` | string \| null | Estimated delivery date | | `shipped_date` | string \| null | Date item was shipped (ISO 8601) | | `delivered_date` | string \| null | Date item was delivered (ISO 8601) | | `attributes` | object | Item attribute values | | `attributes_kwargs` | object | Attribute metadata | | `localized_attributes` | object | Localized attribute values | | `localized_attributes_kwargs` | object | Localized attribute metadata | | `extra_product_price` | integer \| null | Extra product price ID | | `extra_product_stock` | integer \| null | Extra product stock ID | | `shipping_tracking_url` | string \| null | Shipping tracking URL | | `datasource` | integer \| null | Data source ID | | `shipping_option_group` | object \| null | Shipping option with `pk`, `amount`, `shipping_option_name`, `shipping_option_logo` | | `discount_amount` | string | Discount amount | | `is_cancelled` | boolean | Whether item is cancelled (computed) | | `is_cancellable` | boolean | Whether item can be cancelled (computed) | | `is_refundable` | boolean | Whether item is eligible for refund (computed) | | `is_tradable` | boolean | Whether item can be exchanged (computed) | | `tracking_url` | string \| null | URL to track this item's shipment (computed) | | `discounted_price` | string | Price after discounts applied (computed) | | `cancellationrequest_set` | array | Cancellation requests | | `active_cancellation_request` | object \| null | Active cancellation request (computed) | | `available_easy_return_shipping_companies` | array | Available return shipping companies (computed) | | `datasource_detailed` | object \| null | Detailed data source info | | `extra_product_stock_detailed` | object \| null | Detailed stock info | | `extra_product_price_detailed` | object \| null | Detailed price info | | `product` | object | Product details | #### Product (in Order Item) Based on `UserOrderProductSerializer`. | Field | Type | Description | | ------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pk` | integer | Product ID | | `sku` | string | Stock keeping unit (unique variant identifier) | | `base_code` | string | Base product code (shared across variants) | | `name` | string | Product name | | `image` | string \| null | Product image URL (computed) | | `absolute_url` | string \| null | Product page URL path (computed) | | `attributes` | object | Product attribute values | | `attributes_kwargs` | object | Attribute metadata (labels, display info) | | `form_schema` | array \| null | Form schema array with `{order, attribute: {key, name, data_type}, is_required}` | | `data_source` | object \| null | Data source object with `pk`, `name`, `slug`, `title`, `supplier_code`, `address`, `email`, `phone_number`, `fax_number`, `kep_address`, `mersis_number`, `trade_association`, `extras`, `price_list`, `stock_list`, `is_active` | | `extra_attributes` | object | Additional custom attributes | | `category` | object \| null | Category object with `{name}` | | `attribute_set` | integer | Attribute set ID | #### Product (in Product Alert) Based on `ProductSerializerWithOfferURL` (inherits from ProductSerializer). | Field | Type | Description | | ---------------------- | --------------- | --------------------------------------------- | | `pk` | integer | Product ID | | `name` | string | Product name | | `base_code` | string | Base product code | | `sku` | string | Stock keeping unit | | `product_type` | object | Product type `{value, label}` | | `is_active` | boolean | Whether product is active | | `parent` | integer \| null | Parent product ID (for variants) | | `attributes` | object | Product attribute values | | `attributes_kwargs` | object | Attribute metadata | | `extra_attributes` | object | Additional custom attributes | | `is_seller_product` | boolean | Whether product is from seller | | `group_products` | array | Group product IDs | | `productimage_set` | array | Product images | | `attribute_set` | integer | Attribute set ID | | `custom_attribute_set` | integer \| null | Custom attribute set ID | | `is_listable` | boolean | Whether product is listable (computed) | | `listing_code` | string \| null | Listing code | | `data_source` | integer \| null | Data source ID | | `absolute_url` | string \| null | Product page URL with query params (computed) | | `is_form_required` | boolean | Whether form is required |