Список возвратов и невыкупов

Получает список возвратов и невыкупов.

Чтобы получить информацию по одному возврату или невыкупу, выполните запрос GET campaigns/{campaignId}/orders/{orderId}/returns/{returnId}.

⚙️ Лимит: 10 000 запросов в час

Request

GET

https://api.partner.market.yandex.ru/campaigns/{campaignId}/returns

Path parameters

Name

Type

Description

campaignId*

integer<int64>

Идентификатор кампании в API и магазина в кабинете. Каждая кампания в API соответствует магазину в кабинете.

Чтобы узнать идентификаторы своих магазинов, воспользуйтесь запросом GET campaigns.

ℹ️ Что такое кабинет и магазин на Маркете

Query parameters

Name

Type

Description

page_token

string

Идентификатор страницы c результатами.

Если параметр не указан, возвращается самая старая страница.

Рекомендуется передавать значение выходного параметра nextPageToken, полученное при последнем запросе.

Если задан page_token, параметры offset, page_number и page_size игнорируются.
Example: eyBuZXh0SWQ6IDIzNDIgfQ==

limit

integer<int32>

Количество товаров на одной странице.
Example: 20

orderIds

integer<int64>[]

Идентификаторы заказов — для фильтрации результатов.

Несколько идентификаторов перечисляются через запятую без пробела. Максимальное количество идентификаторов — 50.

statuses

RefundStatusType[]

Статусы возвратов или невыкупов — для фильтрации результатов.

Несколько статусов перечисляются через запятую.
Example: STARTED_BY_USER,WAITING_FOR_DECISION

type

ReturnType

Тип заказа для фильтрации:

  • RETURN — возврат.

  • UNREDEEMED — невыкуп.

Если не указывать, в ответе будут и возвраты, и невыкупы.

fromDate

string<date>

Начальная дата для фильтрации возвратов или невыкупов по дате обновления.

Формат: ГГГГ-ММ-ДД.
Example: 2022-10-31

toDate

string<date>

Конечная дата для фильтрации возвратов или невыкупов по дате обновления.

Формат: ГГГГ-ММ-ДД.
Example: 2022-11-30

from_date

string<date>

Этот параметр устарел. Вместо него используйте fromDate.

Начальная дата для фильтрации возвратов или невыкупов по дате обновления.
Example: 2022-10-31

to_date

string<date>

Этот параметр устарел. Вместо него используйте toDate.

Конечная дата для фильтрации возвратов или невыкупов по дате обновления.
Example: 2022-11-30

RefundStatusType

Cтатус возврата денег:

  • STARTED_BY_USER — создан клиентом из личного кабинета.

  • REFUND_IN_PROGRESS — ждет решение о возврате денег.

  • REFUNDED — по возврату проведены все возвратные денежные транзакции.

  • FAILED — невозможно провести возврат покупателю.

  • WAITING_FOR_DECISION — ожидает решения.

  • DECISION_MADE — по возврату принято решение.

  • REFUNDED_WITH_BONUSES — возврат осуществлен баллами Плюса или промокодом.

  • REFUNDED_BY_SHOP — магазин сделал самостоятельно возврат денег.

  • CANCELLED — возврат отменен.

Type

Description

RefundStatusType

Enum: STARTED_BY_USER, REFUND_IN_PROGRESS, REFUNDED, FAILED, WAITING_FOR_DECISION, DECISION_MADE, REFUNDED_WITH_BONUSES, REFUNDED_BY_SHOP, CANCELLED, UNKNOWN

ReturnType

Тип заказа для фильтрации:

  • RETURN — возврат.

  • UNREDEEMED — невыкуп.

Если не указывать, в ответе будут и возвраты, и невыкупы.

Type

Description

ReturnType

Enum: UNREDEEMED, RETURN

Responses

200 OK

Постраничные возвраты партнера.

Body

application/json
{
    "status": "OK",
    "result": {
        "paging": {
            "nextPageToken": "string"
        },
        "returns": [
            {
                "id": 0,
                "orderId": 0,
                "creationDate": "2022-12-29T18:02:01Z",
                "updateDate": "2022-12-29T18:02:01Z",
                "refundStatus": "STARTED_BY_USER",
                "logisticPickupPoint": {
                    "id": 0,
                    "name": "string",
                    "address": {
                        "country": "Россия",
                        "city": "Москва",
                        "street": "Стрелецкая улица",
                        "house": "9к2",
                        "postcode": 123518
                    },
                    "instruction": "string",
                    "type": "WAREHOUSE",
                    "logisticPartnerId": 0
                },
                "shipmentRecipientType": "SHOP",
                "shipmentStatus": "CREATED",
                "refundAmount": 0,
                "items": [
                    {
                        "marketSku": 0,
                        "shopSku": "string",
                        "count": 0,
                        "decisions": [
                            {
                                "returnItemId": 0,
                                "count": 0,
                                "comment": "string",
                                "reasonType": "BAD_QUALITY",
                                "subreasonType": "USER_DID_NOT_LIKE",
                                "decisionType": "REFUND_MONEY",
                                "refundAmount": 0,
                                "partnerCompensation": 0,
                                "images": [
                                    "string"
                                ]
                            }
                        ],
                        "instances": [
                            {
                                "stockType": "FIT",
                                "status": "CREATED",
                                "cis": "string",
                                "imei": "string"
                            }
                        ],
                        "tracks": [
                            {
                                "trackCode": "string"
                            }
                        ]
                    }
                ],
                "returnType": "UNREDEEMED"
            }
        ]
    }
}

Name

Type

Description

status

ApiResponseStatusType

Тип ответа.
Enum: OK, ERROR

result

PagedReturnsDTO

Возвраты.

ApiResponseStatusType

Тип ответа.

Type

Description

ApiResponseStatusType

Enum: OK, ERROR

PagedReturnsDTO

Возвраты.

Name

Type

Description

paging

ForwardScrollingPagerDTO

Информация о страницах с результатами.

returns

ReturnDTO[]

Список возвратов.
Возврат заказа.

ForwardScrollingPagerDTO

Ссылка на следующую страницу.

Name

Type

Description

nextPageToken

string

Идентификатор следующей страницы результатов.

ReturnDTO

Возврат заказа.

Name

Type

Description

id

integer<int64>

Идентификатор возврата.

orderId

integer<int64>

Номер заказа.

creationDate

string<date-time>

Дата создания возврата клиентом.

updateDate

string<date-time>

Дата обновления возврата.

refundStatus

RefundStatusType

Cтатус возврата денег:

  • STARTED_BY_USER — создан клиентом из личного кабинета.

  • REFUND_IN_PROGRESS — ждет решение о возврате денег.

  • REFUNDED — по возврату проведены все возвратные денежные транзакции.

  • FAILED — невозможно провести возврат покупателю.

  • WAITING_FOR_DECISION — ожидает решения.

  • DECISION_MADE — по возврату принято решение.

  • REFUNDED_WITH_BONUSES — возврат осуществлен баллами Плюса или промокодом.

  • REFUNDED_BY_SHOP — магазин сделал самостоятельно возврат денег.

  • CANCELLED — возврат отменен.


Enum: STARTED_BY_USER, REFUND_IN_PROGRESS, REFUNDED, FAILED, WAITING_FOR_DECISION, DECISION_MADE, REFUNDED_WITH_BONUSES, REFUNDED_BY_SHOP, CANCELLED, UNKNOWN

logisticPickupPoint

LogisticPickupPointDTO

Пункт вывоза.

shipmentRecipientType

RecipientType

Способ возврата товара покупателем.
Enum: SHOP, DELIVERY_SERVICE, POST

shipmentStatus

ReturnShipmentStatusType

Статус передачи возврата.
Enum: CREATED, RECEIVED, IN_TRANSIT, READY_FOR_PICKUP, PICKED, LOST, EXPIRED, CANCELLED, FULFILMENT_RECEIVED, PREPARED_FOR_UTILIZATION, NOT_IN_DEMAND, UTILIZED, READY_FOR_EXPROPRIATION, RECEIVED_FOR_EXPROPRIATION

refundAmount

integer<int64>

Сумма возврата.

items

ReturnItemDTO[]

Список товаров в возврате.
Список товаров в возврате.

returnType

ReturnType

Тип возврата.
Enum: UNREDEEMED, RETURN

LogisticPickupPointDTO

Описание пункта вывоза для возврата.

Name

Type

Description

id

integer<int64>

Идентификатор пункта вывоза.

name

string

Название пункта вывоза.

address

PickupAddressDTO

Адрес пункта вывоза.

instruction

string

Дополнительные инструкции к вывозу.

type

LogisticPointType

Тип логистической точки.
Enum: WAREHOUSE, PICKUP_POINT, PICKUP_TERMINAL, PICKUP_POST_OFFICE, PICKUP_MIXED, PICKUP_RETAIL, UNKNOWN

logisticPartnerId

integer<int64>

Идентификатор логистического партнера, к которому относится логистическая точка.

RecipientType

Способ возврата товара покупателем:

  • SHOP — в точку возврата магазина.

  • DELIVERY_SERVICE — отправить курьером.

  • POST — почта.

Type

Description

RecipientType

Enum: SHOP, DELIVERY_SERVICE, POST

ReturnShipmentStatusType

Статус передачи возврата:

  • CREATED — возврат создан.

  • RECEIVED — принят у покупателя.

  • IN_TRANSIT — возврат в пути.

  • READY_FOR_PICKUP — возврат готов к выдаче магазину.

  • PICKED — возврат выдан магазину.

  • LOST — возврат утерян при транспортировке.

  • CANCELLED — возврат отменен.

  • FULFILMENT_RECEIVED — возврат принят на складе Маркета.

  • PREPARED_FOR_UTILIZATION — возврат передан в утилизацию.

  • UTILIZED — возврат утилизирован.

Type

Description

ReturnShipmentStatusType

Enum: CREATED, RECEIVED, IN_TRANSIT, READY_FOR_PICKUP, PICKED, LOST, EXPIRED, CANCELLED, FULFILMENT_RECEIVED, PREPARED_FOR_UTILIZATION, NOT_IN_DEMAND, UTILIZED, READY_FOR_EXPROPRIATION, RECEIVED_FOR_EXPROPRIATION

ReturnItemDTO

Список товаров в возврате.

Name

Type

Description

marketSku

integer<int64>

SKU товара на Маркете.

shopSku*

string

Ваш SKU — идентификатор товара в вашей системе.

Разрешена любая последовательность длиной до 80 знаков. В нее могут входить английские и русские буквы, цифры и символы . , / \ ( ) [ ] - = _

Правила использования SKU:

  • У каждого товара SKU должен быть свой.

  • SKU товара нельзя менять — можно только удалить товар и добавить заново с новым SKU.

  • Уже заданный SKU нельзя освободить и использовать заново для другого товара. Каждый товар должен получать новый идентификатор, до того никогда не использовавшийся в вашем каталоге.

Что такое SKU и как его назначать


Min length: 1
Max length: 80

count*

integer<int64>

Количество единиц товара.

decisions

ReturnDecisionDTO[]

Список решений по возврату.
Решения по возвратам.

instances

ReturnInstanceDTO[]

Список логистических позиций возврата.
Логистическая информация по возврату.

tracks

TrackDTO[]

Список трек-кодов для почтовых отправлений.
Информация о трек-номерах.

PickupAddressDTO

Адрес доставки.

Name

Type

Description

country

string

Страна.
Example: Россия

city

string

Город.
Example: Москва

street

string

Улица.
Example: Стрелецкая улица

house

string

Номер дома.
Example: 9к2

postcode

string

Почтовый индекс.
Example: 123518

LogisticPointType

Тип логистической точки:

  • WAREHOUSE — склад.
  • PICKUP_POINT — обычная точка выдачи заказов (ПВЗ).
  • PICKUP_TERMINAL — постамат.
  • PICKUP_POST_OFFICE — отделение почтовой связи (ОПС).
  • PICKUP_MIXED — торговый зал и пункт выдачи заказов.
  • PICKUP_RETAIL — торговый зал.

Type

Description

LogisticPointType

Enum: WAREHOUSE, PICKUP_POINT, PICKUP_TERMINAL, PICKUP_POST_OFFICE, PICKUP_MIXED, PICKUP_RETAIL, UNKNOWN

ReturnDecisionDTO

Решения по возвратам.

Name

Type

Description

returnItemId

integer<int64>

Идентификатор товара в возврате.

count

integer<int32>

Количество единиц товара.

comment

string

Комментарий.

reasonType

ReturnDecisionReasonType

Причины возврата:

  • BAD_QUALITY — бракованный товар (есть недостатки).

  • DO_NOT_FIT — товар не подошел.

  • WRONG_ITEM — привезли не тот товар.

  • DAMAGE_DELIVERY — товар поврежден при доставке.

  • LOYALTY_FAIL — невозможно установить виновного в браке/пересорте.

  • CONTENT_FAIL — ошибочное описание товара по вине Маркета.

  • UNKNOWN — причина не известна.


Enum: BAD_QUALITY, DOES_NOT_FIT, WRONG_ITEM, DAMAGE_DELIVERY, LOYALTY_FAIL, CONTENT_FAIL, UNKNOWN

subreasonType

ReturnDecisionSubreasonType

Детали причин возврата:

  • DO_NOT_FIT:

    • USER_DID_NOT_LIKE — товар не понравился.
    • USER_CHANGED_MIND — передумал покупать.
    • DELIVERED_TOO_LONG — длительный срок доставки, поэтому передумал.
  • BAD_QUALITY:

    • BAD_PACKAGE — упаковка товара была нарушена.
    • DAMAGED — царапины, сколы.
    • NOT_WORKING — не включается / не работает.
    • INCOMPLETENESS — некомплект (не хватает детали в наборе, к товару).
  • WRONG_ITEM:

    • WRONG_ITEM — не тот товар.
    • WRONG_COLOR — не соответствует по цвету.
    • DID_NOT_MATCH_DESCRIPTION — не соответствует заявленным характеристикам/описанию.


Enum: USER_DID_NOT_LIKE, USER_CHANGED_MIND, DELIVERED_TOO_LONG, BAD_PACKAGE, DAMAGED, NOT_WORKING, INCOMPLETENESS, WRONG_ITEM, WRONG_COLOR, DID_NOT_MATCH_DESCRIPTION, UNKNOWN

decisionType

ReturnDecisionType

Решение по возврату:

  • REFUND_MONEY — вернуть деньги покупателю.

  • REFUND_MONEY_INCLUDING_SHIPMENT — вернуть деньги за товар и пересылку.

  • REPAIR — отремонтировать товар.

  • REPLACE — заменить товар.

  • SEND_TO_EXAMINATION — взять товар на экспертизу.

  • DECLINE_REFUND — отказать в возврате.

  • OTHER_DECISION — другое решение.


Enum: REFUND_MONEY, REFUND_MONEY_INCLUDING_SHIPMENT, REPAIR, REPLACE, SEND_TO_EXAMINATION, DECLINE_REFUND, OTHER_DECISION, UNKNOWN

refundAmount

integer<int64>

Сумма возврата.

partnerCompensation

integer<int64>

Компенсация за обратную доставку.

images

string[]

Список хеш-кодов фотографий товара от покупателя.

ReturnInstanceDTO

Логистическая информация по возврату.

Name

Type

Description

stockType

ReturnInstanceStockType

Тип остатка на складе.
Enum: FIT, DEFECT, ANOMALY, SURPLUS, EXPIRED, MISGRADING, UNDEFINED, INCORRECT_IMEI, INCORRECT_SERIAL_NUMBER, INCORRECT_CIS, PART_MISSING, NON_COMPLIENT, NOT_ACCEPTABLE, UNKNOWN

status

ReturnInstanceStatusType

Логистический статус конкретного товара.
Enum: CREATED, RECEIVED, IN_TRANSIT, READY_FOR_PICKUP, PICKED, RECEIVED_ON_FULFILLMENT, CANCELLED, LOST, UTILIZED, PREPARED_FOR_UTILIZATION, EXPROPRIATED, NOT_IN_DEMAND

cis

string

Код идентификации единицы товара в системе «Честный ЗНАК».

imei

string

Международный идентификатор мобильного оборудования.

TrackDTO

Информация о трек-номерах.

Name

Type

Description

trackCode

string

Трек-код почтового отправления.

ReturnDecisionReasonType

Причины возврата:

  • BAD_QUALITY — бракованный товар (есть недостатки).

  • DO_NOT_FIT — товар не подошел.

  • WRONG_ITEM — привезли не тот товар.

  • DAMAGE_DELIVERY — товар поврежден при доставке.

  • LOYALTY_FAIL — невозможно установить виновного в браке/пересорте.

  • CONTENT_FAIL — ошибочное описание товара по вине Маркета.

  • UNKNOWN — причина не известна.

Type

Description

ReturnDecisionReasonType

Enum: BAD_QUALITY, DOES_NOT_FIT, WRONG_ITEM, DAMAGE_DELIVERY, LOYALTY_FAIL, CONTENT_FAIL, UNKNOWN

ReturnDecisionSubreasonType

Детали причин возврата:

  • DO_NOT_FIT:

    • USER_DID_NOT_LIKE — товар не понравился.
    • USER_CHANGED_MIND — передумал покупать.
    • DELIVERED_TOO_LONG — длительный срок доставки, поэтому передумал.
  • BAD_QUALITY:

    • BAD_PACKAGE — упаковка товара была нарушена.
    • DAMAGED — царапины, сколы.
    • NOT_WORKING — не включается / не работает.
    • INCOMPLETENESS — некомплект (не хватает детали в наборе, к товару).
  • WRONG_ITEM:

    • WRONG_ITEM — не тот товар.
    • WRONG_COLOR — не соответствует по цвету.
    • DID_NOT_MATCH_DESCRIPTION — не соответствует заявленным характеристикам/описанию.

Type

Description

ReturnDecisionSubreasonType

Enum: USER_DID_NOT_LIKE, USER_CHANGED_MIND, DELIVERED_TOO_LONG, BAD_PACKAGE, DAMAGED, NOT_WORKING, INCOMPLETENESS, WRONG_ITEM, WRONG_COLOR, DID_NOT_MATCH_DESCRIPTION, UNKNOWN

ReturnDecisionType

Решение по возврату:

  • REFUND_MONEY — вернуть деньги покупателю.

  • REFUND_MONEY_INCLUDING_SHIPMENT — вернуть деньги за товар и пересылку.

  • REPAIR — отремонтировать товар.

  • REPLACE — заменить товар.

  • SEND_TO_EXAMINATION — взять товар на экспертизу.

  • DECLINE_REFUND — отказать в возврате.

  • OTHER_DECISION — другое решение.

Type

Description

ReturnDecisionType

Enum: REFUND_MONEY, REFUND_MONEY_INCLUDING_SHIPMENT, REPAIR, REPLACE, SEND_TO_EXAMINATION, DECLINE_REFUND, OTHER_DECISION, UNKNOWN

ReturnInstanceStockType

Тип остатка на складе.

Type

Description

ReturnInstanceStockType

Enum: FIT, DEFECT, ANOMALY, SURPLUS, EXPIRED, MISGRADING, UNDEFINED, INCORRECT_IMEI, INCORRECT_SERIAL_NUMBER, INCORRECT_CIS, PART_MISSING, NON_COMPLIENT, NOT_ACCEPTABLE, UNKNOWN

ReturnInstanceStatusType

Логистический статус конкретного товара.

Type

Description

ReturnInstanceStatusType

Enum: CREATED, RECEIVED, IN_TRANSIT, READY_FOR_PICKUP, PICKED, RECEIVED_ON_FULFILLMENT, CANCELLED, LOST, UTILIZED, PREPARED_FOR_UTILIZATION, EXPROPRIATED, NOT_IN_DEMAND

400 Bad Request

Запрос содержит неправильные данные.

Body

application/json
{
    "status": "OK",
    "errors": [
        {
            "code": "string",
            "message": "string"
        }
    ]
}

Name

Type

Description

status

ApiResponseStatusType

Тип ответа.
Enum: OK, ERROR

errors

ApiErrorDTO[]

Список ошибок.
Общий формат ошибки.

ApiErrorDTO

Общий формат ошибки.

Name

Type

Description

code*

string

Код ошибки.

message

string

Описание ошибки.

401 Unauthorized

В запросе не указаны данные для авторизации.

Body

application/json
{
    "status": "OK",
    "errors": [
        {
            "code": "string",
            "message": "string"
        }
    ]
}

Name

Type

Description

status

ApiResponseStatusType

Тип ответа.
Enum: OK, ERROR

errors

ApiErrorDTO[]

Список ошибок.
Общий формат ошибки.

403 Forbidden

Данные для авторизации неверны или доступ к ресурсу запрещен.

Body

application/json
{
    "status": "OK",
    "errors": [
        {
            "code": "string",
            "message": "string"
        }
    ]
}

Name

Type

Description

status

ApiResponseStatusType

Тип ответа.
Enum: OK, ERROR

errors

ApiErrorDTO[]

Список ошибок.
Общий формат ошибки.

404 Not Found

Запрашиваемый ресурс не найден.

Body

application/json
{
    "status": "OK",
    "errors": [
        {
            "code": "string",
            "message": "string"
        }
    ]
}

Name

Type

Description

status

ApiResponseStatusType

Тип ответа.
Enum: OK, ERROR

errors

ApiErrorDTO[]

Список ошибок.
Общий формат ошибки.

420 Method Failure

Превышено ограничение на доступ к ресурсу.

Body

application/json
{
    "status": "OK",
    "errors": [
        {
            "code": "string",
            "message": "string"
        }
    ]
}

Name

Type

Description

status

ApiResponseStatusType

Тип ответа.
Enum: OK, ERROR

errors

ApiErrorDTO[]

Список ошибок.
Общий формат ошибки.

500 Internal Server Error

Внутренняя ошибка сервера.

Body

application/json
{
    "status": "OK",
    "errors": [
        {
            "code": "string",
            "message": "string"
        }
    ]
}

Name

Type

Description

status

ApiResponseStatusType

Тип ответа.
Enum: OK, ERROR

errors

ApiErrorDTO[]

Список ошибок.
Общий формат ошибки.