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:
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
klass
string
Gateway class path
conf.username
string
HTTP Basic Auth username
conf.password
string
HTTP Basic Auth password
conf.send_url
string
Full URL of the notification endpoint including protocol, domain, and path (e.g., https://example.com/api/notification)
conf.from_number
string
Sender identifier (phone number or alias)
Available Gateways
Console
omnishop.libs.notification_gateways.console.NotificationBackend
Logs to console (development only)
Extension
omnishop.libs.notification_gateways.notification_extensions.gateway.NotificationExtensionGateway
HTTP POST with Basic Auth (production)
Notification Flow
The Notification flow is triggered during various order lifecycle events:
An order event occurs (e.g., order delivered, order shipped).
The system checks if the notification gateway is configured.
Commerce sends a POST request to the external service defined in
NOTIFICATION_GATEWAYS.The payload includes order details, user information, and event type.
The external gateway service receives the payload and handles the message delivery.
POST Send Notification
POST Send NotificationPath: 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
Base Payload Structure
from
string
Sender identifier configured in from_number
to
string
Recipient phone number with country code
event
string
Event type that triggered the notification
payload
object
Event-specific data
site_domain
string
Site domain
receiver_user
object
User information (optional)
Notification Events
The following events trigger notifications:
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
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).
Order Cancellation Payload:
Used by: order_cancellation
cancellation_type
string
cancel (before shipment) or refund (after delivery)
order_items
array
Cancelled items (only included if specific items cancelled)
return_code
string
Return code if applicable (only included when present)
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.
Partial Shipment Payload:
Used by: order_shipped_partial_cargo
tracking_number
string
Tracking number for the partial shipment
shipping_company
string
Name of the shipping company
order_items
array
Items included in this partial shipment
Checkout URL Payload:
Used by: order_checkout_url_with_token
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.
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.
Enum Reference
Order Status
Order and order item status codes. Returned as {value, label} object.
50
cancellation waiting
Cancellation request is pending
100
cancelled
Order has been cancelled
200
waiting
Order is waiting to be processed
300
payment_waiting
Waiting for payment confirmation
350
confirmation waiting
Waiting for order confirmation
400
approved
Order has been approved
450
preparing
Order is being prepared
500
shipped
Order has been shipped
510
shipped_and_informed
Shipped and customer notified
520
ready for pickup
Ready for customer pickup
540
attempted_delivery
Delivery was attempted
544
review_started
Review process started (trade-in)
545
review_waiting
Waiting for review (trade-in)
546
waiting_for_payment
Waiting for payment (trade-in)
547
paid
Payment received (trade-in)
550
delivered
Order delivered to customer
600
refunded
Order has been refunded
Currency Types
ISO 4217 currency codes. Returned as {value, label} object.
try
TL
Turkish Lira
eur
EUR
Euro
usd
USD
US Dollar
egp
EGP
Egyptian Pound
gbp
GBP
British Pound
mad
MAD
Moroccan Dirham
pln
PLN
Polish Zloty
sar
SAR
Saudi Riyal
ron
RON
Romanian Leu
uah
UAH
Ukrainian Hryvnia
czk
CZK
Czech Koruna
huf
HUF
Hungarian Forint
rub
RUB
Russian Ruble
bgn
BGN
Bulgarian Lev
iqd
IQD
Iraqi Dinar
kwd
KWD
Kuwaiti Dinar
bhd
BHD
Bahraini Dinar
omr
OMR
Omani Rial
qar
QAR
Qatari Riyal
aed
AED
UAE Dirham
ngn
NGN
Nigerian Naira
inr
INR
Indian Rupee
kzt
KZT
Kazakhstani Tenge
jod
JOD
Jordanian Dinar
rsd
RSD
Serbian Dinar
amd
AMD
Armenian Dram
lyd
LYD
Libyan Dinar
Gender Types
User gender. Returned as {value, label} object. Can be null.
male
male
female
female
Client Types
Platform where the order was placed.
default
Web browser (desktop or mobile web)
android
Android mobile application
ios
iOS mobile application
instore
In-store POS system
b2b
B2B portal
Product Types
Type of product. Returned as {value, label} object.
-1
Pre Product
Pre-product (draft)
0
Simple
Simple product (single SKU)
1
Product Meta
Configurable product (parent with variants)
2
Bundle
Bundle product (contains multiple products)
3
Grouped
Grouped product
-2
Pre Miscellaneous
Pre-miscellaneous (draft)
4
Miscellaneous
Miscellaneous product
5
Offer
Offer product
Shipping Companies
Supported shipping carriers. Returned as {value, label} object. Can be null.
aras
Aras Kargo
ups
UPS
yurtici
Yurtiçi Kargo
mng
MNG Kargo
hbexpress
Hepsi Express
aramex
Aramex
ptt
Ptt
dhlexpress
DHL Express
gls
GLS Logistic
dpd
DPD Cargo
novaposhta
Nova Poshta
cdek
Cdek
surat
Sürat Kargo
scotty
Scotty Cargo
sendeo
Sendeo Cargo
other
Other
Many more shipping companies are supported. See the full list in the codebase.
Cancellation Types
Type of cancellation in order_cancellation event.
cancel
Order cancelled before shipment
refund
Refund after delivery (return)
Data Models
Receiver User
Based on UserProfileSerializer.
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.
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.
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.
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.
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).
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
Last updated
Was this helpful?