1. Webhook Model

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".
If you are working with multiple countries (for example SA and AE) under one sellerID, you should separate the orders according to "countryCode".
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.
"defectiveClaimListingInsight" is a section that identifies products returned due to defective/missing/incorrect reasons and informs the seller about the specific problem that product caused for the customer when a new order arrives. This allows the seller to proactively take precautions when preparing and shipping products to avoid similar situations in the next order, aiming to reduce the rate of returns due to seller-related defects.

Trendyol will be pushing the orders according to model below;

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.

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",
            "orderCountryCode": "RO", // the country where the customer is located, the country where the order was placed
            "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.
                "sector": "",
                "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",
            "channelId": 1, 
            "shipmentPackageId": 3330111111,
            "cargoTrackingNumber": 7280027504111111,
            "cargoTrackingLink": "https://tracking.trendyol.com/?id=111111111-1111-1111-1111-11111111",
            "cargoSenderNumber": "210090111111",
            "sellerDeliveryMethod": "LOCKER", // In case it is LOCKER, package needs to be dropped to the BoxNow locker.Otherwise returns null
            "sellerOtpCode": "2342345",// In case sellerDeliveryMethod is LOCKER, this field returns PIN code to open BoxNow compartement .Otherwise returns null
            "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,
                    "lineSgrFee": 30.40, // averager of line sgr fee (lineItemSgrFee/quantity) 
                    "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,
                    "defectiveClaimListingInsight": ""
                }
            ],
            "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, // (as is calculated packageTotalPrice + totalSgrFee) 
            "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,
            "totalSgrFee": 60.80 //  (total sgrFee of all lines * total of quantities)
        }
    ]
}

Box Now Order Flow

In case an order package to be dropped to BoxNow locker instead of cargo provider picking, below 2 fields in the response body to be used to progress:

“sellerDeliveryMethod”: “LOCKER”

In case it is LOCKER, package needs to be dropped to the BoxNow locker.Otherwise returns null
“sellerOtpCode”: “2342345"

In case sellerDeliveryMethod is LOCKER, this field returns PIN code to open BoxNow compartment. In some cases this field cannot be fulfilled once the order created, if "sellerDeliveryMethod” field is “LOCKER” then you need to refetch order package until get this value. If "sellerDeliveryMethod” field is not “LOCKER” than this field returns null.

You can check Box Now locker address via below website in order to decide which locker point you will be dropped the package:

In Greece https://boxnow.gr/en/locker-finder

Then you can follow below steps:

Step 1: Print your shipping label.
Step 2: Drop off the package at any BoxNow locker you have chosen for
Step 3: Use the PIN code (sellerOtpCode) to open a compartment.
Step 4: Place the package inside and close the locker door.

Each package must be placed in a separate locker compartment. Multiple packages in the same compartment may result in lost packages or unprocessed returns.