Return events: a customer created a new return, or its status changed. Request parameters, notification selection and the response format are described in the [E-shop API overview](https://www.bulkgate.com/en/docs/eshop-api/eshop-api-overview/).

## API URL

| ENDPOINT                                                           | NOTIFICATION EVENT                        |
|:-------------------------------------------------------------------|:------------------------------------------|
| `https://portal.bulkgate.com/api/1.0/eshop/return/new`             | `product_return`                          |
| `https://portal.bulkgate.com/api/1.0/eshop/return/change-status`   | `return_status_change_<return_status_id>` |

> [!NOTE]
> If the request does not reach its destination, repeat it on the [backup server](https://www.bulkgate.com/en/docs/api-administration-tokens/api-backup-server/) `backup1.bulkgate.com`.

## Supported HTTP methods

- `POST` - `application/json`

```http
POST /api/1.0/eshop/return/new HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
```

## New return

`eshop/return/new` triggers the notification of the `product_return` event. Pass the return data using variables from the Return group, e.g. `return_id`, `return_reason` or `return_products1`.

```http-json
POST /api/1.0/eshop/return/new HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json

{
  "application_id": 451,
  "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
  "language": "en",
  "variables": {
    "return_id": "77",
    "order_id": "10045",
    "return_reason": "Wrong size",
    "customer_mobile": "777777777",
    "customer_country_id": "cz"
  }
}
```

## Return status change

`eshop/return/change-status` looks up the notification for a specific status. It builds the event name from `return_status_change_` and the value of the `return_status_id` variable, so always send `return_status_id` — without it the portal cannot match the notification to any status. Your e-shop uploads the statuses notifications can be set up for via the [setup](https://www.bulkgate.com/en/docs/eshop-api/eshop-api-setup/).

```http-json
POST /api/1.0/eshop/return/change-status HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json

{
  "application_id": 451,
  "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
  "language": "en",
  "variables": {
    "return_id": "77",
    "return_status_id": "3",
    "return_status": "Return received",
    "customer_mobile": "777777777",
    "customer_country_id": "cz"
  }
}
```

The request above uses the notification set up for the `return_status_change_3` event.

## Response

```json
{
    "data": {
        "customer": [
            {
                "status": "accepted",
                "message_id": "tmpde1bcd4b1d1",
                "part_id": ["tmpde1bcd4b1d1"],
                "number": "420777777777",
                "channel": "sms"
            }
        ]
    }
}
```

The meaning of the `customer` and `admin` keys, send errors and error types are described in the [E-shop API overview](https://www.bulkgate.com/en/docs/eshop-api/eshop-api-overview/).
