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
• 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.(/smart_cart/orders_api#retrieve-a-single-order).

  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",
        "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"
        ]
      }
    ]
  }
}

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": "pending",
    "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",
        "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"
        ]
      }
    ]
  }
}

Return object attributes appendix

Return object

Return states

The state field is one of the following string values:

Returning address

Present only when the return has a shipment. All fields are strings.

Return line items

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