Skip to content

REVER Admin API (1.0.0)

Summary

Introduction

  • Overview: The REVER ADMIN API provides seamless integration for managing returns through three main categories: Reverse Logistics, Processes, and Settings.
  • Logistics: Handles all operations related to package returns, including shipment tracking, warehouse logistics, and return labels for items sent back to the eCommerce warehouse.
  • Processes: Manages return workflows, including return statuses, item inspections, and actions that can be taken on a return, such as refunds, exchanges, or inspections.
  • Settings: Contains configuration information REVER uses to execute return processes, including return rules, time limits, and warehouse preferences.

OpenAPI Specification

You can download the OpenAPI specification file here to generate your client code.

this API is meant to be used for returns that are already created or processed. The API is not meant to be used to start returns from the customer portal. For integrating with your own portal please take a look at the Storefront API.

E-commerce IDs and Groups

Most commonly, you will only need to use the e-commerce ID provided during onboarding. However, if you need to manage multiple e-commerce stores simultaneously, a group ID is required. An e-commerce group is an identifier that groups multiple e-commerce stores that are managed together. Typically, these are different brands belonging to the same parent company.

Authentication

The REVER Admin API uses API key authentication.

Authenticating via API Key

This authentication method is primarily used for server-to-server (unattended) integrations. You must request an API key through your account manager. The API key must be kept secure and confidential, do not share it with anyone.

To authenticate a request using an API key, include the header x-rever-api-key. Example: x-rever-api-key: 87bf223499abeef

Rate Limiting

The API implements rate limiting. If you receive a 429 error response, please wait a few seconds before retrying.

Download OpenAPI description
admin.json
admin.yaml
Languages
Servers
Mock server
https://docs.itsrever.com/_mock/apis/admin/

Logistics

Collection of methods that provide logistics services including CRUD operations for logistics orders, pickups, etc. Also handles logistics-related files like shipping labels.

Operations

Processes

Collection of methods for managing return processes. It includes CRUD operations and status updates.

Operations

SearchReturnProcesses

Request

Search for return processes

Query
pageinteger(int32)

The page number to return

order_idstring

The order ID to search for, this is the order ID from the e-commerce not the customer order ID

statusstring

The status of the return process

customer_emailstring

The email of the customer

order_numberstring

The order number to search for, this is the order number the user received in their email

curl -i -X GET \
  'https://docs.itsrever.com/_mock/apis/admin/v1/processes/search?page=0&order_id=string&status=string&customer_email=string&order_number=string'

Responses

OK

Bodyapplication/json
paginationobject(pb.Pagination)
return_summariesArray of objects(pb.ReturnSummary)
Response
application/json
{
  "pagination": {
    "current_page": 0,
    "page_size": 0,
    "total_pages": 0
  },
  "return_summaries": [
    { … }
  ]
}

GetReturnSummary

Request

Get a Return Summary

Path
process_idstringrequired
curl -i -X GET \
  'https://docs.itsrever.com/_mock/apis/admin/v1/processes/{process_id}'

Responses

OK

Bodyapplication/json
return_summaryobject(pb.ReturnSummary)
Response
application/json
{
  "return_summary": {
    "basic_process_data": { … },
    "compensation": { … },
    "currency_code": "string",
    "customer": { … },
    "exchange_timing": "TIMING_UNSPECIFIED",
    "extra_line_items": { … },
    "keep_your_item_type": "KEEP_YOUR_ITEM_TYPE_UNSPECIFIED",
    "open_exchange_items": { … },
    "ordered_items": { … },
    "payments": { … },
    "refund_payment_method": "REFUND_PAYMENT_METHOD_UNSPECIFIED",
    "refund_timing": "TIMING_UNSPECIFIED",
    "returned_items": { … },
    "start_return_on_platform_time": "string",
    "status": "RETURN_PROCESS_STATUS_UNSPECIFIED",
    "upload_documents_info": { … }
  }
}

PatchReturnProcess

Request

Updates a return process via a PATCH (updating only certain fields)

Path
process_idstringrequired

ID of the process to be updated. Required.

Bodyapplication/jsonrequired
patchstring

Preferred. map[string]interface{} as a json string

process_idstring

ID of the process to be updated. Required.

return_process_patchobject

any json object with the return process structure

userstring

User doing the patch

curl -i -X PATCH \
  'https://docs.itsrever.com/_mock/apis/admin/v1/processes/{process_id}/patch' \
  -H 'Content-Type: application/json' \
  -d '{
    "patch": "string",
    "process_id": "string",
    "return_process_patch": {},
    "user": "string"
  }'

Responses

OK

Bodyapplication/json
new_last_known_shipping_statusstring(enum)

value of the field last_known_shipping_status after the update

Enum"NO_SHIPPING_STATUS""CREATED""COLLECTED""IN_WAREHOUSE""ERROR""CANCELED"
previous_last_known_shipping_statusstring(enum)

value of the field last_known_shipping_status before the update

Enum"NO_SHIPPING_STATUS""CREATED""COLLECTED""IN_WAREHOUSE""ERROR""CANCELED"
Response
application/json
{
  "new_last_known_shipping_status": "NO_SHIPPING_STATUS",
  "previous_last_known_shipping_status": "NO_SHIPPING_STATUS"
}

MarkAsRefunded

Request

Marks the line items of the request as refunded

Path
process_idstringrequired

gets the reverse delivery info

Bodyapplication/jsonrequired
currencystring

Currency of the order

extra_linesArray of objects(pb.ExtraLineRequest)

Extra lines of the credit note

line_itemsArray of objects(pb.RefundedLineItems)

Items of the credit note

order_idstring

Order ID

order_referencestring

Order reference

process_idstring

Process id

return_process_platform_idstring

return process platform id

total_amountobject

total amount to refund of the order

total_amount_shopobject

total amount to refund in shop currency

curl -i -X POST \
  'https://docs.itsrever.com/_mock/apis/admin/v1/processes/{process_id}/mark-as-refunded' \
  -H 'Content-Type: application/json' \
  -d '{
    "currency": "string",
    "extra_lines": [
      {
        "name": "string",
        "price": "string"
      }
    ],
    "line_items": [
      {
        "line_item_id": "string",
        "name": "string",
        "price": "string",
        "quantity": "string",
        "sku": "string"
      }
    ],
    "order_id": "string",
    "order_reference": "string",
    "process_id": "string",
    "return_process_platform_id": "string",
    "total_amount": {
      "amount": "string",
      "currency": "string"
    },
    "total_amount_shop": {
      "amount": "string",
      "currency": "string"
    }
  }'

Responses

OK

Bodyapplication/json
credit_note_idstring

Credit note id

ecommerce_idstring

Ecommerce id

process_idstring

Process id

Response
application/json
{
  "credit_note_id": "string",
  "ecommerce_id": "string",
  "process_id": "string"
}

AddReview

Request

Adds a review (approve/decline/missing) to a given process

Path
process_idstringrequired

ID of the process in where the review is being added. Required.

Bodyapplication/jsonrequired
process_idstring

ID of the process in where the review is being added. Required.

refund_overrideobject

Refund override

reviewsArray of objects(pb.ReviewLineItem)

Review data. Required.

curl -i -X POST \
  'https://docs.itsrever.com/_mock/apis/admin/v1/processes/{process_id}/reviews/' \
  -H 'Content-Type: application/json' \
  -d '{
    "process_id": "string",
    "refund_override": {
      "amount": {
        "amount": "string",
        "currency_code": "string"
      },
      "reason": "string",
      "requested": true
    },
    "reviews": [
      {
        "created_by_user": "string",
        "line_item_id": "string",
        "reject_reason": "string",
        "show_reject_reason": true,
        "status": "string"
      }
    ]
  }'

Responses

OK

Bodyapplication/json
object(pb.AddReviewResponse)
Response
application/json
{}

Creates a Return

Request

Creates a new return record using a valid reason name obtained from the 'Get Return Reasons' endpoint.

Security
ApiKeyAuth
Path
ecommerce_idstringrequired

ID of the ecommerce store where the return is being created.

Example: ecommerce_id
Bodyapplication/jsonrequired

Details of the return to be created.

customer_printed_order_idstring
emailstring(email)
line_itemsArray of objects
user_preferred_langstring
curl -i -X POST \
  https://docs.itsrever.com/_mock/apis/admin/v1/public/returns/ecommerce_id/import_return \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "customer_printed_order_id": "ORDER-1001",
    "email": "user@example.com",
    "line_items": [
      {
        "line_item_id": "9876543210987",
        "product_return_reason": "NOT_AS_EXPECTED",
        "quantity": 1
      }
    ],
    "user_preferred_lang": "EN"
  }'

Responses

OK - The return was created successfully.

Bodyapplication/json
statusstring
Example: "success"
return_idstring
Example: "ret_123456789"
Response
application/json
{
  "status": "success",
  "return_id": "ret_123456789"
}

Submit reviews for all items in a return process

Request

Notify REVER when a return has been reviewed. Reviews must cover every line item of the process.

Notes:

  • Reviews of a return process must be done in full; unreviewed items will block processing.
  • If an expected item was not received, set status: "MISSING".
  • Optionally override the refund amount with refund_override.
Security
ApiKeyAuth
Bodyapplication/jsonrequired
process_idstring

process id

refund_overrideobject(opspb.RefundOverride)
reviewsArray of objects(opspb.Review)

reviews to be processed

curl -i -X POST \
  https://docs.itsrever.com/_mock/apis/admin/v1/ops/ecommerce/review \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "process_id": "retp_eei390jfio39jcco",
    "refund_override": {
      "amount": {
        "amount": "45.07",
        "currency_code": "EUR"
      }
    },
    "reviews": [
      {
        "line_item_id": "abc123-lineitem",
        "location_id": "84954839489348",
        "reject_reason": "Item damaged during return",
        "rever_id": "review789",
        "should_restock": true,
        "show_reject_reason": true,
        "status": "DECLINED",
        "timestamp": "2025-04-16T14:30:00Z",
        "user": "warehouse-001"
      },
      {
        "line_item_id": "def456-lineitem",
        "reject_reason": "",
        "rever_id": "review102",
        "should_restock": false,
        "show_reject_reason": false,
        "status": "MISSING",
        "timestamp": "2025-04-16T15:00:00Z",
        "user": "store 123"
      }
    ]
  }'

Responses

OK - Reviews submitted.

Bodyapplication/json
object(opspb.ReviewItemsResponse)
Response
application/json
{}

UpdateLogistics

Request

Updates the logistics fields associated to a given return process

Path
process_idstringrequired

The process ID to update. Required.

Bodyapplication/jsonrequired
process_idstring

The process ID to update. Required.

userstring

The user that performed the update. Required.

user_selected_carrierstring

The new logistics carrier of the process. It's used by the process to request the creation to the provider of the shipping order using his carrier If it's already created, has no effect. Required.

user_selected_providerstring

The new logistics provider of the process. It's used by the process to request the creation of the shipping order to this provider. If it's already created, has no effect. Required.

curl -i -X POST \
  'https://docs.itsrever.com/_mock/apis/admin/v1/processes/{process_id}/logistics' \
  -H 'Content-Type: application/json' \
  -d '{
    "process_id": "string",
    "user": "string",
    "user_selected_carrier": "string",
    "user_selected_provider": "string"
  }'

Responses

OK

Bodyapplication/json
object(pb.UpdateLogisticsResponse)
Response
application/json
{}

GetReturnDocuments

Request

Returns all the documents uploaded for a given return process

Path
process_idstringrequired
curl -i -X GET \
  'https://docs.itsrever.com/_mock/apis/admin/v1/processes/{process_id}/documents'

Responses

OK

Bodyapplication/json
documentsArray of objects(pb.GetReturnDocumentsResponse_Document)
Response
application/json
{
  "documents": [
    { … }
  ]
}

AuthorizeReturnProcess

Request

Path
process_idstringrequired

gets the reverse delivery info

Bodyapplication/jsonrequired
authorizedboolean
process_idstring
refund_overrideobject(opspb.RefundOverride)
unauthorized_reasonstring
userstring
curl -i -X POST \
  'https://docs.itsrever.com/_mock/apis/admin/v1/processes/{process_id}/authorize' \
  -H 'Content-Type: application/json' \
  -d '{
    "authorized": true,
    "process_id": "string",
    "refund_override": {
      "amount": {
        "amount": "string",
        "currency_code": "string"
      },
      "reason": "string",
      "requested": true
    },
    "unauthorized_reason": "string",
    "user": "string"
  }'

Responses

OK

Bodyapplication/json
object(opspb.SubmitAuthorizationResponse)
Response
application/json
{}

GetAuthorizationStatus

Request

GetAuthorizationStatus returns the authorization status and details of a process

Path
process_idstringrequired
curl -i -X GET \
  'https://docs.itsrever.com/_mock/apis/admin/v1/processes/{process_id}/authorization/status'

Responses

OK

Bodyapplication/json
authorization_detailsobject(pb.GetAuthorizationStatusResponse_AuthorizationDetails)
authorization_statusstring(enum)
Enum"AUTHORIZATION_STATUS_UNSPECIFIED""AUTHORIZATION_STATUS_AUTHORIZATION_PENDING""AUTHORIZATION_STATUS_DOCUMENT_UPLOAD_PENDING""AUTHORIZATION_STATUS_AUTHORIZED""AUTHORIZATION_STATUS_NOT_AUTHORIZED""AUTHORIZATION_STATUS_NO_AUTHORIZATION_REQUIRED"
unauthorization_detailsobject(pb.GetAuthorizationStatusResponse_UnauthorizationDetails)
Response
application/json
{
  "authorization_details": {
    "refund_override_amount": { … },
    "refund_override_reason": "string",
    "user": "string"
  },
  "authorization_status": "AUTHORIZATION_STATUS_UNSPECIFIED",
  "unauthorization_details": {
    "reason": "string",
    "user": "string"
  }
}

Settings

Collection of methods for managing e-commerce configurations. It includes GET operations for e-commerce stores, warehouses, and other settings.

Operations

Returns

Public endpoints for creating/importing returns.

REVER all rights reserved.