Extension Subscription Gateway Flows
This document provides a detailed explanation of the extension subscription gateway flows, including the purpose of the flow, the services involved, and the description of each field in the requests and responses.
All requests are sent with x-akinon-api-version: 2. The microservice must validate this header and respond accordingly.
Example configuration:
{
"extension": {
"klass": "omnishop.libs.subscription_gateways.extension.gateway.ExtensionGateway",
"dispatch_klass": "omnishop.libs.subscription_gateways.service.GenericDispatchService",
"conf": {
"auth": {
"username": "<basic-auth-username>",
"password": "<basic-auth-password>"
},
"base_url": "https://extension-service.example.com/"
}
}
}Purpose of the Flow
The Extension Subscription Gateway Flow is designed to decouple Commerce from subscription providers (e.g. Emarsys, Revotas). Instead of communicating directly with each provider, Commerce sends user and order data to an external microservice, which is responsible for forwarding it to the configured provider. This flow is particularly useful for:
Provider Abstraction: Allowing the microservice to handle provider-specific logic without changes to Commerce.
Centralized Subscription Management: Supporting multiple providers through a single integration point.
Scalability: Standardizing the integration with multiple third-party systems using a consistent API pattern.
This part of the document contains the list of services that can be integrated in flows above. 2 configuration parameters will be shared during integration:
username
Username for basic authentication
password
Password for basic authentication
subscribe-email (POST)
This service is used to subscribe a user by email address. It is triggered when a user opts in to email communication.
URL:
Request Headers
x-akinon-request-id
Unique ID for problem solving & tracing.
Mandatory
x-akinon-api-version
Akinon Customer API version.
Mandatory
Authorization
Basic [BASE64_encoded(username:password)]
Mandatory
Request Body Structure
String
Email address to subscribe
domain
String
Domain from which the request originated
Request Body Example
Request Body (typescript interface)
Response Body (raw 200)
subscribe-user (POST)
This service is used to subscribe a user with full profile information. It is triggered when a user registers or when their subscription preferences are updated.
URL:
Request Headers
x-akinon-request-id
Unique ID for problem solving & tracing.
Mandatory
x-akinon-api-version
Akinon Customer API version.
Mandatory
Authorization
Basic [BASE64_encoded(username:password)]
Mandatory
Request Body Structure
pk
Number
User ID
String
Email address
firstName
String
First name
lastName
String
Last name
phone
String/Null
Phone number
gender
String/Null
Gender
dateOfBirth
String/Null
Date of birth
languageCode
String
Language code (e.g. tr, en)
emailAllowed
Boolean
Email subscription consent
smsAllowed
Boolean
SMS subscription consent
callAllowed
Boolean
Call subscription consent
whatsappAllowed
Boolean
WhatsApp subscription consent
isActive
Boolean
Whether the account is active
isStaff
Boolean
Whether the user is a staff member
dateJoined
String (ISO 8601)
Registration date
lastLogin
String/Null (ISO 8601)
Last login date
modifiedDate
String (ISO 8601)
Last modified date
userType
String
User type
attributes
Object
Additional user attributes
Request Body Example
Request Body (typescript interface)
Response Body (raw 200)
order-info (POST)
This service is used to notify the microservice about a newly created order. It sends the full order details including the user profile and order items.
URL:
Request Headers
x-akinon-request-id
Unique ID for problem solving & tracing.
Mandatory
x-akinon-api-version
Akinon Customer API version.
Mandatory
Authorization
Basic [BASE64_encoded(username:password)]
Mandatory
Request Body Structure
pk
Number
Order ID
number
String
Order number
status
String
Order status name (e.g. approved, shipped, delivered)
currency
String
Currency code — ISO 4217 lowercase (e.g. try, eur, usd)
amount
String
Total order amount (decimal value as string)
discountAmount
String
Total discount amount (decimal value as string)
shippingAmount
String
Shipping cost (decimal value as string)
createdDate
String (ISO 8601)
Order creation date
user
Object
User profile — same structure as /subscribe-user
orderItems
Array
List of order items
orderItems[].pk
Number
Order item ID
orderItems[].product
Object
Product info
orderItems[].product.pk
Number
Product ID
orderItems[].product.sku
String
Product SKU
orderItems[].price
String
Unit price (decimal value as string)
orderItems[].priceCurrency
String
Currency code — ISO 4217 lowercase (e.g. try, eur, usd)
orderItems[].taxRate
String
Tax rate (decimal value as string)
orderItems[].status
String
Order item status name (e.g. approved, shipped)
Request Body Example
Request Body (typescript interface)
Response Body (raw 200)
unsubscribed-users (GET)
This service is called by a scheduled Celery task every hour. Commerce fetches users who unsubscribed within the given time range and updates their consent fields (email_allowed, sms_allowed, call_allowed) accordingly. Only users with the relevant consent field currently set to true are affected.
URL:
Request Headers
x-akinon-request-id
Unique ID for problem solving & tracing.
Mandatory
x-akinon-api-version
Akinon Customer API version.
Mandatory
Authorization
Basic [BASE64_encoded(username:password)]
Mandatory
Query Parameters
fromDate
String (ISO 8601)
Start of the time range
toDate
String (ISO 8601)
End of the time range
Response Body Structure
emailUnsubscribed
String[]
Email addresses of users who unsubscribed from email
smsUnsubscribed
String[]
Phone numbers of users who unsubscribed from SMS
callUnsubscribed
String[]
Phone numbers of users who unsubscribed from calls
Response Body Example
Response Body (typescript interface)
Response Body For Errors (ALL)
If any errors are encountered in the services, these errors should be reported in the format below, and the list of error codes should be shared with Akinon.
Response Body (raw 4xx/5xx json)
Response Body (raw 4xx/5xx typescript interface)
Changelog
Version 1.0.0
Added
Initial implementation of the Extension Subscription Gateway
subscribe-emailendpoint for email-only subscriptionssubscribe-userendpoint for full user profile subscriptionsorder-infoendpoint for order creation notificationsunsubscribed-usersendpoint for hourly consent synchronizationHTTP Basic Auth support
x-akinon-request-idandx-akinon-api-versionheaders on all requests
Last updated
Was this helpful?

