MarkAsRefundedExternally

REVER Admin API (1.0.0)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

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

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_idstring

Customer printed order ID

ecommerce_idstring

E-commerce ID

emailstring

line_itemsArray of objects(returns.ImportLineItem)

Line items

user_preferred_langstring

User preferred language

curl -i -X POST \
  https://api.byrever.com/v1/public/returns/ecommerce_id/import_return \
  -H 'Content-Type: application/json' \
  -H 'x-rever-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

errorobject

Structured error. Populated when the import failed with a user-actionable cause.

process_idstring

Process ID. Empty when the import failed.

Response

application/json

{
  "error": {
    "code": "IMPORT_RETURN_ERROR_CODE_UNSPECIFIED",
    "message": "string"
  },
  "process_id": "string"
}

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

override_authorizationboolean

when true, authorization approval is executed before processing the review

platform_process_idstring

process id, deprecated

process_idstring

process id

refund_overrideobject

optional refund override

reviewsArray of objects(opspb.ItemReviewGeneric)

reviews to be processed

curl -i -X POST \
  https://api.byrever.com/v1/ops/ecommerce/review \
  -H 'Content-Type: application/json' \
  -H 'x-rever-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"
      },
      {
        "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

{}

GetReturnSummaries

Request

Returns a paginated list of return process summaries, with optional filters (order ID, status, customer email, order number).

Security

API Key

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/summaries?page=0&order_id=string&status=string&customer_email=string&order_number=string' \
  -H 'x-rever-api-key: YOUR_API_KEY_HERE'

Responses

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": [
    { … }
  ]
}

GetReturnSummaryByPlatform

Request

Get a Return Summary by the e-commerce platform process ID. Useful when the caller knows the platform's internal ID (e.g. Shopify/Shopware order or return ID) but not REVER's internal process ID.

Security

API Key

Path

platform_process_idstringrequired

The process ID assigned by the e-commerce platform.

curl -i -X GET \
  'https://api.byrever.com/v1/processes/ecommerce/{platform_process_id}' \
  -H 'x-rever-api-key: YOUR_API_KEY_HERE'

Responses

Bodyapplication/json

return_summaryobject(pb.ReturnSummary)

Response

application/json

{
  "return_summary": {
    "basic_process_data": { … },
    "checkout_id": "string",
    "compensation": { … },
    "currency_code": "string",
    "customer": { … },
    "exchange_timing": "TIMING_UNSPECIFIED",
    "extra_line_items": { … },
    "is_claim": true,
    "keep_your_item_type": "KEEP_YOUR_ITEM_TYPE_UNSPECIFIED",
    "navigation": { … },
    "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": { … }
  }
}

GetReturnSummary

Request

Get a Return Summary

Security

API Key

Path

process_idstringrequired

curl -i -X GET \
  'https://api.byrever.com/v1/processes/{process_id}' \
  -H 'x-rever-api-key: YOUR_API_KEY_HERE'

Responses

Bodyapplication/json

return_summaryobject(pb.ReturnSummary)

Response

application/json

{
  "return_summary": {
    "basic_process_data": { … },
    "checkout_id": "string",
    "compensation": { … },
    "currency_code": "string",
    "customer": { … },
    "exchange_timing": "TIMING_UNSPECIFIED",
    "extra_line_items": { … },
    "is_claim": true,
    "keep_your_item_type": "KEEP_YOUR_ITEM_TYPE_UNSPECIFIED",
    "navigation": { … },
    "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)

Security

API Key

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

Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.

userstring

User doing the patch

curl -i -X PATCH \
  'https://api.byrever.com/v1/processes/{process_id}/patch' \
  -H 'Content-Type: application/json' \
  -H 'x-rever-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "patch": "string",
    "process_id": "string",
    "return_process_patch": {
      "@type": "string"
    },
    "user": "string"
  }'

Responses

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

MarkAsRefundedExternally

Request

Marks a return process as refunded externally (manual refund made outside the platform). Records the optional amount override and a required note explaining the reason.

Security

API Key

Bodyapplication/jsonrequired

amount_overrideobject

Optional: override the refund amount (if not provided, uses pending amount)

notestringrequired

Note explaining the reason for the manual refund

process_idstringrequired

Process ID to mark as refunded

curl -i -X POST \
  https://api.byrever.com/v1/ops/mark_as_refunded_externally \
  -H 'Content-Type: application/json' \
  -H 'x-rever-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "amount_override": {
      "amount": "string",
      "currency_code": "string"
    },
    "note": "string",
    "process_id": "string"
  }'

Responses

Bodyapplication/json

object(opspb.MarkAsRefundedExternallyResponse)

Response

application/json

{}

AddReview

Request

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

Security

API Key

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}/review' \
  -H 'Content-Type: application/json' \
  -H 'x-rever-api-key: YOUR_API_KEY_HERE' \
  -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

Bodyapplication/json

object(pb.AddReviewResponse)

Response

application/json

{}

UpdateLogistics

Request

Updates the logistics fields associated to a given return process

Security

API Key

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' \
  -H 'x-rever-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "process_id": "string",
    "user": "string",
    "user_selected_carrier": "string",
    "user_selected_provider": "string"
  }'

Responses

Bodyapplication/json

object(pb.UpdateLogisticsResponse)

Response

application/json

{}

GetReturnDocuments

Request

Returns all the documents uploaded for a given return process

Security

API Key

Path

process_idstringrequired

curl -i -X GET \
  'https://api.byrever.com/v1/processes/{process_id}/documents' \
  -H 'x-rever-api-key: YOUR_API_KEY_HERE'

Responses

Bodyapplication/json

documentsArray of objects(pb.GetReturnDocumentsResponse_Document)

Response

application/json

{
  "documents": [
    { … }
  ]
}

SubmitAuthorization

Request

Submits an authorization decision (approve or decline) for a return process. If declined, records the reason. Optionally accepts a refund override.

Security

API Key

Bodyapplication/jsonrequired

authorizedboolean

process_idstring

refund_overrideobject(opspb.RefundOverride)

unauthorized_reasonstring

userstring

curl -i -X POST \
  https://api.byrever.com/v1/ops/submit_authorization \
  -H 'Content-Type: application/json' \
  -H 'x-rever-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "authorized": true,
    "process_id": "string",
    "refund_override": {
      "amount": {
        "amount": "string",
        "currency_code": "string"
      },
      "reason": "string",
      "requested": true
    },
    "unauthorized_reason": "string",
    "user": "string"
  }'

Responses

Bodyapplication/json

object(opspb.SubmitAuthorizationResponse)

Response

application/json

{}

GetAuthorizationStatus

Request

GetAuthorizationStatus returns the authorization status and details of a process

Security

API Key

Path

process_idstringrequired

curl -i -X GET \
  'https://api.byrever.com/v1/processes/{process_id}/authorization_status' \
  -H 'x-rever-api-key: YOUR_API_KEY_HERE'

Responses

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 Admin API (1.0.0)CopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from Claude

Summary

Introduction

OpenAPI Specification

E-commerce IDs and Groups

Authentication

Authenticating via API Key

Rate Limiting

Logistics

Processes

Create a return process

RequestExpand all

Responses

Was this helpful?

Review a return process

RequestExpand all

Responses

Was this helpful?

GetReturnSummaries

Request

Responses

Was this helpful?

GetReturnSummaryByPlatform

Request

Responses

Was this helpful?

GetReturnSummary

Request

Responses

Was this helpful?

PatchReturnProcess

RequestExpand all

Responses

Was this helpful?

MarkAsRefundedExternally

RequestExpand all

Responses

Was this helpful?

AddReview

RequestExpand all

Responses

Was this helpful?

UpdateLogistics

Request

Responses

Was this helpful?

GetReturnDocuments

Request

Responses

Was this helpful?

SubmitAuthorization

RequestExpand all

Responses

Was this helpful?

GetAuthorizationStatus

Request

Responses

Was this helpful?

Settings

Returns

REVER Admin API (1.0.0)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Request

Request

Request

Request

Request

Request