Webhook Returns Edit the file on GitHub

Webhook Returns allows Skroutz Merchants to automatically receive return details to their platform when a new return is created or an existing one is updated (its state or logistics change), so the merchant's own system can stay in sync without polling the Returns API.

Webhook Returns is currently under development .

Table of Contents

Setup

In order to be able to use the webhook, a return webhook URL should be registered by the merchant from within Smart Cart settings page in merchant's panel (Merchants > Services > Skroutz Marketplace).

Registering a URL alone does not enable delivery — the return webhook must also be explicitly turned on from the same settings page. Both are required before any request is sent.

Webhook Returns requests are sent from the same infrastructure as Webhook Orders requests, so the same IP ranges apply:

IPv4:

  • 185.6.76.0/22
  • 3.73.204.153/32
  • 3.72.204.195/32
  • 3.67.183.221/32
  • 63.34.193.172/32
  • 54.195.53.34/32
  • 108.129.50.199/32

IPv6:

  • 2a03:e40::/32

Please ensure these IPs are whitelisted in your firewall or security tools to prevent webhook delivery failures.

You can also access the IP ranges in JSON format for programmatic consumption.

The webhook URL should match the shop's domain and it should follow secure HTTP (HTTPS)

Webhook URL example
Shop URL Webhook URL
https://shop.gr https://shop.gr/smart_cart_returns

Webhook requests

An HTTP POST request is sent to the predefined return webhook URL once an event has been triggered.

The anatomy of a request

Request
POST {webhook_url}
Request headers
Header Value
Content-Type application/json; charset=utf-8
User-Agent Skroutz OrderNotifier v1 (shared with Webhook Orders)

Since the User-Agent value is shared with Webhook Orders, it cannot be used to distinguish order from return notifications. Use the event_type field in the request body instead.

Expected request response
200

Webhook events

The available webhook events for which a request is performed are:

  • return created events
  • return updated events

Return created

A return created webhook request (merchant_return_created) is triggered once, right after a return is first placed.

Return updated

A return updated webhook request (merchant_return_updated) is triggered whenever:

  • The return's state changes (e.g. approved by the merchant, marked as returning, returned, rejected, expired or cancelled). If the update also makes shipment information newly available — for example when the return transitions into the returning state — the payload additionally carries the courier and returning_address fields.
  • The return's courier is reassigned on an existing return shipment.
  • The return's courier tracking IDs become available.

A return updated request is only sent once a return created request has already been delivered for that same return and webhook URL. In practice, if you enable the return webhook (or change its URL) after a return already exists, that return will not receive update events until a fresh return created event has been recorded against the new URL.

Request payload

Name Type Value Description
event_type String merchant_return_created, merchant_return_updated Return event type
event_time Date String in format
YYYY-MM-DDTHH:MM:SSZ		   Event creation time
return Object   Return details
changes Object   Return changes with old and new values (optional)

Return object

Name Type Values Description
return_code String   Return Code
state String pending_merchant_review, returning, pending_physical_review, returned, rejected, expired, cancelled Current lifecycle state of the return. One of the return states.
order_code String   The code of the order this return belongs to
created_at Date String in format
YYYY-MM-DDTHH:MM:SSZ		   Return creation date
courier_tracking_ids Array of Strings (Optional) Deduplicated tracking IDs across current shipments
courier String (Optional) Human-readable name of the courier (e.g. ACS)
returning_address Object (Optional) Returning address — the address the merchant should receive the return at
return_line_items Array   Return line items — the products being returned

courier_tracking_ids, courier and returning_address are omitted entirely (not sent as null) when not applicable — e.g. virtual returns with no shipment.

Return states

The state field is one of the following string values:

State Description
pending_merchant_review The customer submitted a return request and the merchant needs to review it.
returning The package is in transit back to the merchant.
pending_physical_review The package arrived at the merchant and must perform physical inspection.
returned The package was delivered back to the merchant.
rejected The return was rejected.
expired The merchant never responded to the return request within the deadline.
cancelled The return was cancelled.

Returning address

Present only when the return has a shipment.

Name Type Description
returning_address.street_name String Street/road name
returning_address.street_number String Building number
returning_address.zip String Postal code
returning_address.city String City
returning_address.region String Region/state
returning_address.country_code String Country code (e.g. GR)

Return line items

Each element of the return_line_items array represents one product line being returned.

Name Type Values Description
id String   ID of the order line item being returned
product_name String   Product display name
returning_quantity Integer   How many units of this product the customer is returning
return_reason String faulty, wrong_product, withdrawal, damaged_product, expired_product, authenticity_doubt, delivery_issues, other (Optional) Reason the customer selected
user_comment String (Optional) Free-text comment left by the customer explaining the return
user_photos Array of Strings (Optional) Full URLs of photos uploaded by the customer as evidence

Return changes object

Only present on return updated requests, and only includes the keys that actually changed.

Field Shape Notes
state { old, new } Raw state values, see return object
courier { old, new } Human-readable courier name; old can be null when courier info first becomes available
returning_address { old, new } Same shape as returning address
courier_tracking_ids { old, new } Only included when a new value is actually present

Payload Examples

Example 1 (return created)

{
  "event_type": "merchant_return_created",
  "event_time": "2026-08-18T09:12:03Z",
  "return": {
    "return_code": "R-111111-1111111",
    "state": "pending_merchant_review",
    "order_code": "48213907",
    "created_at": "2026-08-18T09:12:03Z",
    "return_line_items": [
      {
        "id": "gY6oNzr8jp",
        "product_name": "Apple iPhone 15 128GB",
        "returning_quantity": 1,
        "return_reason": "wrong_product",
        "user_comment": "Ordered black, received white.",
        "user_photos": [
          "https://api.skroutz.gr/assets/returns/photo_1.jpg"
        ]
      }
    ]
  }
}

Example 2 (return updated - shipment info newly available)

{
  "event_type": "merchant_return_updated",
  "event_time": "2026-08-19T10:00:00Z",
  "return": {
    "return_code": "R-111111-1111111",
    "state": "returning",
    "order_code": "48213907",
    "created_at": "2026-08-18T09:12:03Z",
    "courier": "ACS",
    "returning_address": {
      "street_name": "Ermou",
      "street_number": "12",
      "zip": "10563",
      "city": "Athens",
      "region": "Attica",
      "country_code": "GR"
    },
    "return_line_items": [
      { "id": "gY6oNzr8jp", "product_name": "Apple iPhone 15 128GB", "returning_quantity": 1 }
    ]
  },
  "changes": {
    "state": { "old": "pending_merchant_review", "new": "returning" },
    "courier": { "old": null, "new": "ACS" },
    "returning_address": {
      "old": null,
      "new": {
        "street_name": "Ermou",
        "street_number": "12",
        "zip": "10563",
        "city": "Athens",
        "region": "Attica",
        "country_code": "GR"
      }
    }
  }
}

Example 3 (return updated - courier tracking IDs become available)

{
  "event_type": "merchant_return_updated",
  "event_time": "2026-08-19T11:30:00Z",
  "return": {
    "return_code": "R-111111-1111111",
    "state": "returning",
    "order_code": "48213907",
    "created_at": "2026-08-18T09:12:03Z",
    "courier": "ACS",
    "courier_tracking_ids": ["ACS1234567890"],
    "returning_address": {
      "street_name": "Ermou",
      "street_number": "12",
      "zip": "10563",
      "city": "Athens",
      "region": "Attica",
      "country_code": "GR"
    },
    "return_line_items": [
      { "id": "gY6oNzr8jp", "product_name": "Apple iPhone 15 128GB", "returning_quantity": 1 }
    ]
  },
  "changes": {
    "courier_tracking_ids": { "old": null, "new": ["ACS1234567890"] }
  }
}

Example 4 (return updated - courier reassignment)

{
  "event_type": "merchant_return_updated",
  "event_time": "2026-08-19T12:30:00Z",
  "return": {
    "return_code": "R-111111-1111111",
    "state": "returning",
    "order_code": "48213907",
    "created_at": "2026-08-18T09:12:03Z",
    "courier": "Speedex",
    "courier_tracking_ids": ["ACS1234567890"],
    "returning_address": {
      "street_name": "Ermou",
      "street_number": "12",
      "zip": "10563",
      "city": "Athens",
      "region": "Attica",
      "country_code": "GR"
    },
    "return_line_items": [
      { "id": "gY6oNzr8jp", "product_name": "Apple iPhone 15 128GB", "returning_quantity": 1 }
    ]
  },
  "changes": {
    "courier": { "old": "ACS", "new": "Speedex" }
  }
}

Example 5 (return updated - plain state change)

{
  "event_type": "merchant_return_updated",
  "event_time": "2026-08-19T14:03:11Z",
  "return": {
    "return_code": "R-111111-1111111",
    "state": "returned",
    "order_code": "48213907",
    "created_at": "2026-08-18T09:12:03Z",
    "courier": "Speedex",
    "courier_tracking_ids": ["ACS1234567890"],
    "returning_address": {
      "street_name": "Ermou",
      "street_number": "12",
      "zip": "10563",
      "city": "Athens",
      "region": "Attica",
      "country_code": "GR"
    },
    "return_line_items": [
      {
        "id": "gY6oNzr8jp",
        "product_name": "Apple iPhone 15 128GB",
        "returning_quantity": 1
      }
    ]
  },
  "changes": {
    "state": { "old": "returning", "new": "returned" }
  }
}