Returns API Edit the file on GitHub

Returns API allows Skroutz Merchants to retrieve and manage their returns.

Returns API is currently under development.

Table of Contents

• Setup
  • Obtaining an API token
  • Authorization
• Endpoints
  • Retrieve a single return
  • Handle a return waiting for review
  • Watch a customer video
• Error handling
• Test requests (sandbox)
• Return object attributes appendix

Setup

Obtaining an API token

In order to be able to use the API, you need to generate an API token from within Smart Cart settings page in merchant's panel (Merchants > Services > Skroutz Marketplace).

There can only be one active API key per shop at a certain time. Creating a new API key will expire any previous one.

The same API token used for the Orders API is used here.

Authorization

Pass in a valid API token in the Authorization header, prefixed with Bearer as in the following curl example.

A specific Accept header is also required.

curl -X GET https://api.skroutz.gr/merchants/ecommerce/returns/R-111111-1111111 \
  -H 'Accept: application/vnd.skroutz+json; version=3.0' \
  -H 'Authorization: Bearer your_access_token_here'

Endpoints

Retrieve a single return

Fetch the details of a single return, identified by its return_code.

  GET /merchants/ecommerce/returns/:return_code

Example

curl -X GET https://api.skroutz.gr/merchants/ecommerce/returns/R-111111-1111111 \
  -H 'Accept: application/vnd.skroutz+json; version=3.0' \
  -H 'Authorization: Bearer your_access_token_here'

Response

{
  "return": {
    "return_code": "R-111111-1111111",
    "state": "returning",
    "order_code": "DEMO-OPEN",
    "created_at": "2026-01-01T10:00:00Z",
    "courier_tracking_ids": ["DEMO-RET-TRACK-1", "DEMO-RET-TRACK-2"],
    "courier": "ACS",
    "returning_address": {
      "street_name": "Demo Street",
      "street_number": "1",
      "zip": "11111",
      "city": "Demo City",
      "region": "Demo Region",
      "country_code": "GR"
    },
    "return_line_items": [
      {
        "id": "DEMO-ITEM-1",
        "ean": "1234567890123",
        "product_name": "Demo Product",
        "returning_quantity": 1,
        "return_reason": "damaged_product",
        "user_comment": "This is a demo comment explaining the return.",
        "user_photos": [
          "https://a.scdn.gr/demo/return_photo_1.jpg"
        ]
      }
    ]
  }
}

Handle a return waiting for review

Some returns wait for the merchant's review before Skroutz schedules them: a faulty product, a missing part, or a withdrawal or wrong size outside the return policy. Such a return is in state pending_merchant_review and carries a review with its deadline and the handle_options it accepts.

Send one of the handle_options as option, with the params it takes. The response is the updated return.

  POST /merchants/ecommerce/returns/:return_code/handle

Every option resolves the review, so the return leaves pending_merchant_review (e.g. to rejected after a rejection) and Skroutz sends a return updated webhook.

Example: approve

curl -X POST https://api.skroutz.gr/merchants/ecommerce/returns/R-111111-1111111/handle \
  -H 'Accept: application/vnd.skroutz+json; version=3.0' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -H 'Authorization: Bearer your_access_token_here' \
  -d '{ "option": "approve" }'

Example: reject

curl -X POST https://api.skroutz.gr/merchants/ecommerce/returns/R-111111-1111111/handle \
  -H 'Accept: application/vnd.skroutz+json; version=3.0' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -H 'Authorization: Bearer your_access_token_here' \
  -d '{ "option": "not_faulty", "comment": "The product works according to its specifications." }'

{
  "option": "not_faulty",
  "comment": "The product works according to its specifications."
}

Status: 200

Age: 0
Cache-Control: no-cache
Connection: keep-alive
Content-Length: 1163
Content-Type: application/json; charset=utf-8
Date: Thu, 24 Jun 2021 15:01:26 GMT
Server: h2o (Debian)
Via: 1.1 varnish (Varnish/5.0)
X-App: as103_ssl
X-Cache: MISS
X-Cached: skroutz miss(0)
X-Meta-Client-Id: 27951bdf06a65ea4
X-Origin: lb2
X-Request-Id: 989369834
X-Runtime: 0.021923
X-Varnish: 989369834

{
  "return": {
    "return_code": "DEMO-RETURN-REVIEW",
    "state": "pending_merchant_review",
    "order_code": "DEMO-OPEN",
    "created_at": "2026-01-01T10:00:00Z",
    "courier_tracking_ids": [
      "DEMO-RET-TRACK-1",
      "DEMO-RET-TRACK-2"
    ],
    "courier": "ACS",
    "returning_address": {
      "street_name": "Demo Shop",
      "street_number": "7",
      "zip": "18531",
      "city": "Piraeus",
      "region": "Attica",
      "country_code": "GR"
    },
    "return_line_items": [
      {
        "id": "demo-rli-1",
        "ean": "1234567890123",
        "product_name": "Demo return item",
        "returning_quantity": 1,
        "return_reason": "faulty",
        "user_comment": "Demo customer comment about the return",
        "user_photos": [
          "https://demo.scdn.gr/ds/ecommerce/return_request_line_item_images/demo-img-1.jpeg",
          "https://demo.scdn.gr/ds/ecommerce/return_request_line_item_images/demo-img-2.jpeg"
        ]
      }
    ],
    "review": {
      "review_type": "faulty",
      "expires_at": "2026-01-01T21:00:00+02:00",
      "holiday_auto_approval": false,
      "customer_conversation_open": false
    },
    "handle_options": [
      {
        "option": "approve"
      },
      {
        "option": "contact_manufacturer",
        "comment_required": true
      },
      {
        "option": "usability_suggestions",
        "comment_required": true
      },
      {
        "option": "not_faulty",
        "comment_required": true
      },
      {
        "option": "resolved_via_customer_communication",
        "comment_required": false
      }
    ]
  }
}

Send the missing part

For a missing_part review, the merchant can send the missing part to the customer instead of receiving the product back. Skroutz creates an additional delivery of the part, at the shop's cost, and the return moves to resolved_without_return: the product is not returned.

Pick the values from the option's delivery, as when accepting an order. All params are required.

A window that is no longer available is rejected, never replaced with another one. Fetch the return again for the current windows: the windows in a webhook payload are those available when it was sent.

curl -X POST https://api.skroutz.gr/merchants/ecommerce/returns/R-111111-1111111/handle \
  -H 'Accept: application/vnd.skroutz+json; version=3.0' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -H 'Authorization: Bearer your_access_token_here' \
  -d '{
    "option": "send_missing_part",
    "pickup_location": "YlpD0KROym",
    "cargo": false,
    "pickup_window": "20261029T1000-20261029T1400",
    "weight": 2,
    "number_of_parcels": 1,
    "items_description": "Mounting accessories",
    "delivery_reason": "Sending the missing part"
  }'

Handle errors

{
  "errors": [
    {
      "code": "pickup_window",
      "messages": [
        "is not an available pickup window"
      ]
    }
  ]
}

Watch a customer video

The url and thumbnail_url of a line item's user_videos point to the following endpoints. Each takes your API token and redirects to the video's player page or its thumbnail image, on a link signed for a short time. Request them when you need to show the video, rather than storing the link they redirect to.

  GET /merchants/ecommerce/returns/:return_code/videos/:id
  GET /merchants/ecommerce/returns/:return_code/videos/:id/thumbnail

Error handling

In case of errors, the response will have a representative HTTP status code in the 4xx range. The body would contain an array of errors.

For example, if the requested return code does not exist (or does not belong to your shop), you will get a 404 HTTP status code (Not Found):

{
  "errors": [
    {
      "code": "not_found",
      "messages": [
        "Return not found"
      ]
    }
  ]
}

Test requests (sandbox)

The following d​emo return code​ is available on production for testing reasons.

It is safe to issue requests for the following demo return code multiple times for testing, since it does not reference any real data.

DEMO-RETURN

A demo return with a single returning line item, courier tracking ids and a returning address.

  GET /merchants/ecommerce/returns/DEMO-RETURN

Status: 200

Age: 0
Cache-Control: no-cache
Connection: keep-alive
Content-Length: 720
Content-Type: application/json; charset=utf-8
Date: Thu, 24 Jun 2021 15:01:26 GMT
Server: h2o (Debian)
Via: 1.1 varnish (Varnish/5.0)
X-App: as103_ssl
X-Cache: MISS
X-Cached: skroutz miss(0)
X-Meta-Client-Id: 27951bdf06a65ea4
X-Origin: lb2
X-Request-Id: 989369834
X-Runtime: 0.021923
X-Varnish: 989369834

{
  "return": {
    "return_code": "DEMO-RETURN",
    "state": "returning",
    "order_code": "DEMO-OPEN",
    "created_at": "2026-01-01T10:00:00Z",
    "courier_tracking_ids": [
      "DEMO-RET-TRACK-1",
      "DEMO-RET-TRACK-2"
    ],
    "courier": "ACS",
    "returning_address": {
      "street_name": "Demo Shop",
      "street_number": "7",
      "zip": "18531",
      "city": "Piraeus",
      "region": "Attica",
      "country_code": "GR"
    },
    "return_line_items": [
      {
        "id": "demo-rli-1",
        "ean": "1234567890123",
        "product_name": "Demo return item",
        "returning_quantity": 1,
        "return_reason": "damaged_product",
        "user_comment": "Demo customer comment about the return",
        "user_photos": [
          "https://demo.scdn.gr/ds/ecommerce/return_request_line_item_images/demo-img-1.jpeg",
          "https://demo.scdn.gr/ds/ecommerce/return_request_line_item_images/demo-img-2.jpeg"
        ]
      }
    ]
  }
}

DEMO-RETURN-REVIEW

A demo return of a faulty product, waiting for the merchant's review, with its review and handle_options.

  GET /merchants/ecommerce/returns/DEMO-RETURN-REVIEW
  POST /merchants/ecommerce/returns/DEMO-RETURN-REVIEW/handle

Handling it with any of its handle_options answers with the same return, unchanged.

Status: 200

Age: 0
Cache-Control: no-cache
Connection: keep-alive
Content-Length: 1163
Content-Type: application/json; charset=utf-8
Date: Thu, 24 Jun 2021 15:01:26 GMT
Server: h2o (Debian)
Via: 1.1 varnish (Varnish/5.0)
X-App: as103_ssl
X-Cache: MISS
X-Cached: skroutz miss(0)
X-Meta-Client-Id: 27951bdf06a65ea4
X-Origin: lb2
X-Request-Id: 989369834
X-Runtime: 0.021923
X-Varnish: 989369834

{
  "return": {
    "return_code": "DEMO-RETURN-REVIEW",
    "state": "pending_merchant_review",
    "order_code": "DEMO-OPEN",
    "created_at": "2026-01-01T10:00:00Z",
    "courier_tracking_ids": [
      "DEMO-RET-TRACK-1",
      "DEMO-RET-TRACK-2"
    ],
    "courier": "ACS",
    "returning_address": {
      "street_name": "Demo Shop",
      "street_number": "7",
      "zip": "18531",
      "city": "Piraeus",
      "region": "Attica",
      "country_code": "GR"
    },
    "return_line_items": [
      {
        "id": "demo-rli-1",
        "ean": "1234567890123",
        "product_name": "Demo return item",
        "returning_quantity": 1,
        "return_reason": "faulty",
        "user_comment": "Demo customer comment about the return",
        "user_photos": [
          "https://demo.scdn.gr/ds/ecommerce/return_request_line_item_images/demo-img-1.jpeg",
          "https://demo.scdn.gr/ds/ecommerce/return_request_line_item_images/demo-img-2.jpeg"
        ]
      }
    ],
    "review": {
      "review_type": "faulty",
      "expires_at": "2026-01-01T21:00:00+02:00",
      "holiday_auto_approval": false,
      "customer_conversation_open": false
    },
    "handle_options": [
      {
        "option": "approve"
      },
      {
        "option": "contact_manufacturer",
        "comment_required": true
      },
      {
        "option": "usability_suggestions",
        "comment_required": true
      },
      {
        "option": "not_faulty",
        "comment_required": true
      },
      {
        "option": "resolved_via_customer_communication",
        "comment_required": false
      }
    ]
  }
}

Return object attributes appendix

Return object

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

review and handle_options are present only while the return is in state pending_merchant_review and waits for the merchant's review. They are omitted once the review is handled or its deadline passes.

Return states

The state field is one of the following string values:

Returning address

Present only when the return has a shipment.

Return line items

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

User videos

Review

Present while the return waits for the merchant's review.

Handle options

The options to send to handle the return: approve, then send_missing_part, then the rejection reasons. Each option resolves the review. Contacting the customer, which only extends the deadline, is available in the merchant panel only.

Rejection reasons

Delivery options

The choices for the missing part's delivery, named after the params of send_missing_part, as in an order's accept options.

Delivery option: Pickup location

Delivery option: Pickup window

As in an order's accept options, the id identifies the window by its start and end time (YYYYMMDDTHHMM-YYYYMMDDTHHMM, local Greek time). Each window books its own courier, so there is no courier to choose. The same id can appear in both lists of a location, so cargo tells which one you picked.