Webhook Model
Webhook Model
With the development of webhooks, we will be able to automatically notify another application when a certain event or action occurs.
- Instead of receiving data using the getshipmentpackage service that you use to pull your orders, a mechanism is used that sends a request to a special URL that you share, which is triggered when the event occurs, using webhooks.
Webhook Service
You can use webhook subscriptions to receive notifications about order events in Trendyol Seller Center.
- "CREATED"
- "PICKING"
- "INVOICED"
- "SHIPPED"
- "CANCELLED"
- "DELIVERED"
- "UNDELIVERED"
- "RETURNED"
- "UNSUPPLIED"
- "AWAITING"
- "UNPACKED"
- "AT_COLLECTION_POINT"
- "VERIFIED"
We are providing all the status with the same service. (as a full body). Sellers should provide the webhook service with the request model below to be able to get the requested status for the order.
Webhook Authorization
There are 2 types of authorization method allowed which "BASIC_AUTHENTICATION" or "API_KEY". You should use one of the method while creating your webhook request in the field called "AuthenticationType".
- If the "AuthenticationType" field is "API_KEY", the "apiKey" field is mandatory, and the "username" and "password" fields may not be sent.
- If your service expects api key in the header, it will be sent as "x-api-key".
- If the "AuthenticationType" field is "BASIC_AUTHENTICATION", the "username" and "password" fields are mandatory. The "apiKey" field may not be sent.
Webhook Retry Model
In case of an error in webhook services, the system will automatically take action and deactivate the relevant webhook request. In this context, we will send two e-mails to our sellers.
- In the 1st e-mail, we will share information about the webhook ID that received the error and we will share with you the period during which we will continue to send requests to this service.
- In the 2nd e-mail, we will inform you that we have reached the end of the relevant period and that the webhook ID that received the error has been deactivated.
You can activate your deactivated webhooks after fixing the problem in your service.
Webhook Best Practices
- If there is any failed request made to your webhook services, Trendyol will push the failed orders every 5 minutes until it get success. (This will be changed in the future)
- Since sending data via webhook is not always possible, it is recommended that you make improvements to receive data periodically from Trendyol via the relevant service.
- For example, if you have created a webhook request for order data, we recommend that you synchronize your data periodically using the getshipmentpackage service.
- Your webhook service's endpoint should not contain "Trendyol", "Dolap", "localhost".
- The maximum number of webhooks that can be created for a seller is 15. Webhooks that are deactivated are also included in this number. If you exceed the maximum number of webhooks, you can delete the appropriate one from your existing webhooks and re-define a webhook.
Webhook Request Model
Currently we are only allowing sellers to use orders with the same model with the getShipmentPackages service.
- Request type should be JSON.
- Request METHOD should be POST.
"createdBy" can get the values below:
- "order-creation" -> The package is created directly with the coming order
- "cancel" -> The package is created after partial cancellation
- "split" -> The package is created based on the package split
- "transfer" -> Orders that are directed to another seller by Trendyol because the seller who received the order does not have the product.
Trendyol will be pushing the orders according to model below;
{
"totalElements": 1,
"totalPages": 1,
"page": 0,
"size": 1,
"content": [
{
"shipmentAddress": {
"id": 11111111,
"firstName": "Trendyol",
"lastName": "Customer",
"company": "",
"address1": "DSM Grup Danışmanlık İletişim ve Satış Ticaret A.Ş. Maslak Mahallesi Saat Sokak Spine Tower No:5 İç Kapı No:19 Sarıyer/İstanbul",
"address2": "",
"city": "İstanbul",
"cityCode": 34,
"district": "Sarıyer",
"districtId": 54,
"countyId": 0, // for CEE region
"countyName": "", // for CEE region
"shortAddress": "", // for GULF region
"stateName": "", // for GULF region
"addressLines": {
"addressLine1": "",
"addressLine2": ""
},
"postalCode": "34200",
"countryCode": "TR",
"neighborhoodId": 21111,
"neighborhood": "Maslak Mahallesi",
"phone": null,
"fullAddress": "DSM Grup Danışmanlık İletişim ve Satış Ticaret A.Ş. Maslak Mahallesi Saat Sokak Spine Tower No:5 İç Kapı No:19 Sarıyer/İstanbul",
"fullName": "Trendyol Customer"
},
"orderNumber": "10654411111",
"packageGrossAmount": 498.90,
"packageSellerDiscount": 0.00,
"packageTyDiscount": 0.00, // If commercial is true, it may return full, if false, it will return 0.
"packageTotalDiscount": 0.00,
"discountDisplays": [
{
"displayName": "Sepette %20 İndirim",
"discountAmount": 100
}
],
"taxNumber": null,
"invoiceAddress": {
"id": 11111112,
"firstName": "Trendyol",
"lastName": "Customer",
"company": "", // Orders from the GULF region may be empty.
"address1": "DSM Grup Danışmanlık İletişim ve Satış Ticaret A.Ş. Maslak Mahallesi Saat Sokak Spine Tower No:5 İç Kapı No:19 Sarıyer/İstanbul",
"address2": "",
"city": "İstanbul",
"cityCode": 0,
"district": "Sarıyer", // Orders from the GULF region may be empty.
"districtId": 54,
"countyId": 0, // It will available for the CEE region.
"countyName": "", // It will available for the CEE region.
"shortAddress": "", // It will available for the GULF region.
"stateName": "", // It will available for the GULF region.
"addressLines": {
"addressLine1": "",
"addressLine2": ""
},
"postalCode": "", // Orders from the GULF region may be empty.
"countryCode": "TR",
"neighborhoodId": 0,
"phone": null,
"latitude": "11.111111",
"longitude": "22.222222",
"fullAddress": "DSM Grup Danışmanlık İletişim ve Satış Ticaret A.Ş. Maslak Mahallesi Saat Sokak Spine Tower No:5 İç Kapı No:19 Sarıyer/İstanbul",
"fullName": "Trendyol Customer",
"taxOffice": "Company of OMS's Tax Office", // If it is not a corporate invoice (commercial=false), it will not be returned in the body.
"taxNumber": "Company of OMS's Tax Number" // If it is not a corporate invoice (commercial=false), it will not be returned in the body.
},
"customerFirstName": "Trendyol",
"customerEmail": "[email protected]",
"customerId": 1451111111,
"supplierId": 2738,
"customerLastName": "Customer",
"shipmentPackageId": 3330111111,
"cargoTrackingNumber": 7280027504111111,
"cargoTrackingLink": "https://tracking.trendyol.com/?id=111111111-1111-1111-1111-11111111",
"cargoSenderNumber": "210090111111",
"cargoProviderName": "Trendyol Express",
"lines": [
{
"quantity": 1,
"salesCampaignId": 11,
"productSize": "Tek Ebat",
"stockCode": "111111",
"productName": "Kuş ve Çiçek Desenli Tepsi - Yeşil / Altın Sarısı - 49 cm, 01SYM134, Tek Ebat",
"contentId": 1239111111,
"productOrigin": "TR",
"sellerId": 2738,
"lineGrossAmount": 498.90,
"lineTotalDiscount": 0.00,
"lineSellerDiscount": 0.00,
"lineTyDiscount": 0.00,
"discountDetails": [
{
"lineItemPrice": 498.90,
"lineItemSellerDiscount": 0.00,
"lineItemTyDiscount": 0.00
}
],
"currencyCode": "TRY",
"productColor": "Yeşil",
"lineId": 4765111111,
"vatRate": 20.00,
"barcode": "8683772071724",
"orderLineItemStatusName": "Delivered",
"lineUnitPrice": 498.90,
"fastDeliveryOptions": [],
"productCategoryId": 2710,
"commission": 13,
"businessUnit": "Sports Shoes",
"cancelledBy": "",
"cancelReason": "",
"cancelReasonCode": 0
}
],
"orderDate": 1762253333685,
"identityNumber": "11111111111",
"currencyCode": "TRY",
"packageHistories": [
{
"createdDate": 1762860180000,
"status": "Delivered"
}
],
"shipmentPackageStatus": "Delivered",
"status": "Delivered",
"whoPays": 1, // If it is a seller pays agreement, 1 comes, if it is a trendyol agreement, this field does not come.
"deliveryType": "normal",
"timeSlotId": 0,
"estimatedDeliveryStartDate": 1762858136000,
"estimatedDeliveryEndDate": 1763030936000,
"packageTotalPrice": 498.90,
"deliveryAddressType": "Shipment",
"agreedDeliveryDate": 1762376340000,
"fastDelivery": false,
"originShipmentDate": 1762242537619,
"lastModifiedDate": 1762865408581,
"commercial": false,
"fastDeliveryType": "",
"deliveredByService": false,
"warehouseId": 372389,
"invoiceLink": "https://efatura01.evidea.com/11111111111",
"micro": true,
"giftBoxRequested": false,
"3pByTrendyol": false,
"etgbNo": "25341453EX025864", // When micro is true, information will be returned for the etgbNo field.
"etgbDate": 1762646400000, // When micro is true, information will be returned for the etgbDate field.
"containsDangerousProduct": false, // In micro export orders, if there are any dangerous products in the package received by the seller, such as batteries, perfume, etc., it will return true.
"cargoDeci": 10,
"isCod": false,
"createdBy": "order-creation", // Indicates how the package was created, can be "order-creation", "split", "cancel" or "transfer"
"originPackageIds": null, // This field is populated after cancellation or splitting operations and gives the packageid of the first package after these operations.
"hsCode": "711111000000", // This field will return as a string for micro orders.
"shipmentNumber": 606404425
}
]
}
Starting June 15, 2026, the following fields will also be added to the service response for "Trendyol Yurt Dışı Aracılığı ile" model (this date is currently a draft):
"invoiceNumber": "1255141"
"invoiceStatus": "NotInvoiced"
"invoiceRejectedReasonKeys: [
{
"INVOICE_NUMBER_ALREADY_EXISTS",
"INVOICE_TOTAL_MISMATCH"
}
]
Definitions of "invoiceStatus" field :
| invoiceStatus | Definition |
|---|---|
| NotInvoiced | Indicates that the invoice for the order package has not been sent. |
| Received | The invoice for the order package is currently under review. |
| Rejected | The invoice for the order package was found to be incorrect/invalid after controls. For order packages in this status: if it is a Türkiye Marketplace order, the incorrect invoice must be deleted from the order package and resent. If it is a Micro-Export or Trendyol Cross-Border Fulfillment order, a new invoice must be provided without sending a delete request for the same order package. |
| Invoiced | The invoice for the order package has been verified as correct after controls. The "invoiceLink" field for the order package will be with value only for packages that have transitioned to this status other. For Micro-Export and Trendyol Cross-Border Fulfillment order packages that have not transitioned to this status, cargo labels will not be returned by our integration service. |
Definitions of "invoiceRejectedReasonKeys" field:
| invoiceRejectedReasonKeys | Definition |
|---|---|
| INVOICE_LINE_MISMATCH | For each product type in your order, there must be a matching line item containing the correct product quantity, unit price, and VAT information. |
| INVOICE_TOTAL_MISMATCH | The grand total amount on your invoice must match the total order amount. |
| INVOICE_LINE_NUMBER_MISMATCH | The number of line items on your invoice must match the number of unique product types in the order. |
| INVOICE_TYPE_MISMATCH | The invoice type specified on your invoice must be "sales". |
| SENDER_VKN_MISMATCH | The sender's Tax Identification Number (VKN) on your invoice must match the VKN defined in the system. |
| RECEIPENT_VKN_MISMATCH | The recipient's Tax Identification Number (VKN) on your invoice must match Trendyol's VKN details. |
| INVOICE_NUMBER_MISMATCH | The invoice number on your invoice must match the invoice number you provided for the order. |
| INVOICE_DATE_MISMATCH | The invoice date must be later than or equal to the order date. |
| INVOICE_SCENARIO_MISMATCH | The invoice scenario must be either "basic" or "commercial". |
| INVOICE_NOT_FOUND_IN_MAILBOX | The invoice could not be found in the Trendyol mailbox. You are expected to submit a new invoice. |
| INVOICE_NUMBER_ALREADY_EXISTS | A previously submitted invoiceNumber is being resent for a different order package. The invoice number must be changed. |
Updated about 14 hours ago