Skip to content
/
SearchReturnProcesses

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
https://api.byrever.com

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

Create a return process

Request

Create a new return process using the order, email and items to be returned.

Notes:

  • Returns are unique: make sure a return doesn't exist for that line_item_id in the same order
  • Each portal has a unique ecommerce_id. Make sure you use a valid ecommerce_id.
  • You'll need to add a valid return reason in the line_item_id (see details below)
  • The user preferred languaged will be used to define the communications' language with the shopper. The default language is english but can be overriden
Security
API Key
Path
ecommerce_idstringrequired

ID of the ecommerce store where the return is being created. Each portal has a unique ecommerce_id (warranty, internal, in_store...)

Example: ecommerce_id
Bodyapplication/jsonrequired

Details of the return to be created.

customer_printed_order_idstringrequired

Original order name from the eCommerce platform

Example: "#12334"
emailstring(email)required

Email from the shopper. Must be the email used in the original purchase

Example: "johndoe@gmail.com"
line_itemsArray of objectsrequired
line_items[].​line_item_idstringrequired

The Line Item ID from the Platform, not the REVER line item ID.

Example: "ABC1234"
line_items[].​product_return_reasonstringrequired

Reason name. Retrieve available reasons via GET /v1/public/configs/return-reasons/find (Storefront API) and use the name field from that response.

Example: "TOO_SMALL"
line_items[].​quantityintegerrequired

Quantity of items for each line_item_id

Example: 2
user_preferred_langstring(ISO-639)

The language in which communication will be sent to the shopper.

Example: "en"
curl -i -X POST \
  https://api.byrever.com/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
process_idstring
Example: "retp_38Fv8eXCCjU7cG0XnrZ2DaWDqzj"
Response
application/json
{
  "process_id": "retp_38Fv8eXCCjU7cG0XnrZ2DaWDqzj"
}

Review 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.
  • Each quantity of the line_item_id needs to have a review line (if there's multiple quantity for the same line_item_id, they need to go on different review lines within the reviews array)
  • If an expected item was not received, set status as MISSING.
  • Optionally override the refund amount with refund_override.
Security
API Key
Bodyapplication/json
process_idstringrequired

REVER process_id of the return you are reviewing

Example: "retp_38Fv8eXCCjU7cG0XnrZ2DaWDqzj"
reviewsArray of objectsrequired

Reviews to be processed. Each quantity of the line_item_id needs to have a review line (if there's multiple quantity for the same line_item_id, they need to go on different review lines within the reviews array)

reviews[].​line_item_idstringrequired

ID of the line item. This property accepts both the line_item_id from REVER, the line_item_id from the eCommerce platform or the SKU

Example: "PD12341N32"
reviews[].​statusAPPROVED (string) or DECLINED (string) or MISSING (string)required

Review status. This is the outcome of the review and it's what will define any actions or communications.

One of:

Item received and approved.

string(APPROVED)
reviews[].​timestampstring(ISO 8601)required

timestamp

Example: "2019-08-24T14:15:22Z"
reviews[].​userstringrequired

Email of the user making the review

Example: "warehouse-agent1@brand.com"
reviews[].​reject_reasonstring

Required when status: DECLINED

Reason for rejection.

Example: "The T-Shirt was used and broken"
reviews[].​show_reject_reasonboolean

Available when status: DECLINED

Choose if you want to share the reject_reason with the shopper in the rejection email.

Example: true
refund_overrideobject

Optional Refund amount to be overriden. Only use in the cases where you want to edit the refund amount

curl -i -X POST \
  https://api.byrever.com/v1/ops/ecommerce/review \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "process_id": "retp_38Fv8eXCCjU7cG0XnrZ2DaWDqzj",
    "reviews": [
      {
        "line_item_id": "PD12341N32",
        "status": "DECLINED",
        "timestamp": "2025-04-16T14:30:00Z",
        "user": "warehouse-agent1@brand.com",
        "reject_reason": "The T-Shirt was used and broken",
        "show_reject_reason": true
      },
      {
        "line_item_id": "PD12341N32",
        "status": "APPROVED",
        "timestamp": "2025-04-16T14:30:00Z",
        "user": "warehouse-agent1@brand.com"
      },
      {
        "line_item_id": "LS87941L99",
        "status": "MISSING",
        "timestamp": "2025-04-16T14:30:00Z",
        "user": "warehouse-agent1@brand.com"
      }
    ],
    "refund_override": {
      "amount": {
        "amount": "1200",
        "currency_code": "EUR"
      },
      "reason": "The order is partially broken",
      "requested": true
    }
  }'

Responses

OK - Reviews submitted.

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

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://api.byrever.com/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://api.byrever.com/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://api.byrever.com/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"
}

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://api.byrever.com/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://api.byrever.com/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://api.byrever.com/v1/processes/{process_id}/authorize' \
  -H 'Content-Type: application/json' \
  -d '{
    "authorized": true,
    "process_id": "string",
    "refund_override": {
      "amount": {
        "amount": 1200,
        "currency_code": "EUR"
      },
      "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://api.byrever.com/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"
  }
}

MarkAsRefundedDeprecated

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://api.byrever.com/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"
}

AddReviewDeprecated

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://api.byrever.com/v1/processes/{process_id}/reviews/' \
  -H 'Content-Type: application/json' \
  -d '{
    "process_id": "string",
    "refund_override": {
      "amount": {
        "amount": "1200",
        "currency_code": "EUR"
      },
      "reason": "The order is partially broken",
      "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
{}

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.