Skip to content
/
GetReverseDeliveryInfo

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

UpdateLKSS

Request

Updates the Last Known Shipping Status (LKSS) of a return process based on logistics provider events.

Security
API Key
Bodyapplication/jsonrequired
lkssstring(enum)
Enum"NO_SHIPPING_STATUS""CREATED""COLLECTED""IN_WAREHOUSE""ERROR""CANCELED"
process_idstring
process_platform_idstring
curl -i -X POST \
  https://api.byrever.com/v1/ops/update_lkss \
  -H 'Content-Type: application/json' \
  -H 'x-rever-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "lkss": "NO_SHIPPING_STATUS",
    "process_id": "string",
    "process_platform_id": "string"
  }'

Responses

OK

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

GetPresignedURLLabel

Request

Returns a presigned URL to download the shipping label file associated with a return process.

Security
API Key
Path
process_idstringrequired

Id of the process to identify the label from

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

Responses

OK

Bodyapplication/json
urlstring

URL to download the label file

Response
application/json
{
  "url": "string"
}

GetReverseDeliveryInfo

Request

Get the reverse delivery information of a Return Process

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

Responses

OK

Bodyapplication/json
logistics_summaryobject(pb.LogisticsSummary)
Response
application/json
{
  "logistics_summary": {
    "carrier": "string",
    "pickup_address": { … },
    "pickup_reference": "string",
    "pickups_scheduled": "string",
    "return_method": "RETURN_METHOD_UNSPECIFIED",
    "status": "STATUS_UNSPECIFIED",
    "tracking_id": "string",
    "tracking_url": "string",
    "warehouse": { … }
  }
}

CreatePickup

Request

Creates a pickup for a given process_id, customer and address A logistic order must be created prior requesting a pickup Must specify the provider and carrier to be used to create the pickup:

  • Returns UNIMPLEMENTED (gRPC code 12) if the provider is OPS, meaning it didn't generated any action.
  • Returns InvalidArgument (gRPC code 3) if the combination of return-method, providerand carrier is not supported.
Security
API Key
Bodyapplication/jsonrequired
carrierstring

Carrier to be used for generating the pickup (DHL, UPS, Correos...) must be available for the given provider

currencystring

Currency code of the declared value, e.g. "EUR"

customerobject

Customer Important! the alias at the end is for API docs generation @Description A generic customer in the Rever platform @name api.Customer

declared_valuestring

Total declared value of the shipment in REVER money

ecommerce_idstring

Ecommerce associated to this logistic order

order_numberstring

Order number shown to the customer, used as the carrier's own reference for the collect. Some carriers require it.

pickup_addressobject

Address @Description generic address used in many scenarios @name api.Address

pickup_rangesArray of strings(enum)

Preferred times for the pickup a the customer address

Items Enum"NO_RANGE""RANGE_8_TO_12""RANGE_12_TO_16""RANGE_16_TO_20"
process_idstring

Id of the process that the pickup is associated to

providerstring

Provider to be used for generating the pickup (SendCloud, OPS, etc).

repickup_attemptinteger(int32)

Repickup attempt number. 0 means first pickup, >0 means repickup. Used to bypass duplicate-pickup guards for providers like GLS where a new collect code (tracking ID) is generated per pickup.

settingsobject

deprecated

curl -i -X POST \
  https://api.byrever.com/v1/logistics/pickup \
  -H 'Content-Type: application/json' \
  -H 'x-rever-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "carrier": "string",
    "currency": "string",
    "customer": {
      "email": "string",
      "first_name": "string",
      "last_name": "string",
      "platform_customer_id": "string",
      "rever_id": "string"
    },
    "declared_value": "string",
    "ecommerce_id": "string",
    "order_number": "string",
    "pickup_address": {
      "address_line_1": "string",
      "address_line_2": "string",
      "city": "string",
      "company": "string",
      "country": "string",
      "country_code": "string",
      "email": "string",
      "first_name": "string",
      "last_name": "string",
      "phone": "string",
      "postcode": "string",
      "rever_id": "string",
      "state_province": "string",
      "state_province_code": "string"
    },
    "pickup_ranges": [
      "NO_RANGE"
    ],
    "process_id": "string",
    "provider": "string",
    "repickup_attempt": 0,
    "settings": {
      "logistic_config": [
        {
          "carrier": "string",
          "provider": "string",
          "service_id": "string"
        }
      ],
      "return_method": "NO_RETURN_METHOD"
    }
  }'

Responses

OK

Bodyapplication/json
pickup_orderobject

Pickup order created if any

Response
application/json
{
  "pickup_order": {
    "carrier": "string",
    "id": "string",
    "pickup_range": { … },
    "provider": "string",
    "tracking_url": "string"
  }
}

SaveManuallyCreatedLogisticOrder

Request

SaveManuallyCreatedLogisticOrder creates a logistic order associated to a given process_id, and saves the label file in the database

Security
API Key
Bodyapplication/jsonrequired
labelstring(bytes)

The content of the label file, base64 encoded

label_extensionstring

The extension of the label file, just 3 letters Only "pdf", "png" and "jpg" are allowed

orderobject

The logistic order data with the process_id

curl -i -X POST \
  https://api.byrever.com/v1/logistics/orders \
  -H 'Content-Type: application/json' \
  -H 'x-rever-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "label": "string",
    "label_extension": "string",
    "order": {
      "carrier": "string",
      "from": {
        "address_line_1": "string",
        "address_line_2": "string",
        "city": "string",
        "company": "string",
        "country": "string",
        "country_code": "string",
        "email": "string",
        "first_name": "string",
        "last_name": "string",
        "phone": "string",
        "postcode": "string",
        "rever_id": "string",
        "state_province": "string",
        "state_province_code": "string"
      },
      "process_id": "string",
      "provider": "string",
      "return_method": "NO_RETURN_METHOD",
      "to": {
        "address_line_1": "string",
        "address_line_2": "string",
        "city": "string",
        "company": "string",
        "country": "string",
        "country_code": "string",
        "email": "string",
        "first_name": "string",
        "last_name": "string",
        "phone": "string",
        "postcode": "string",
        "rever_id": "string",
        "state_province": "string",
        "state_province_code": "string"
      },
      "tracking_id": "string",
      "tracking_url": "string"
    }
  }'

Responses

OK

Bodyapplication/json
orderobject

logistic order created

Response
application/json
{
  "order": {
    "carrier": "string",
    "currency_code": "string",
    "id": "string",
    "original_carriers": [ … ],
    "price": 0,
    "provider": "string",
    "requires_customs": true,
    "same_carrier_as_original": true,
    "shipments": [ … ]
  }
}

CreateOrderV2

Request

Creates a logistic order for a given process_id, customer and address. Must specify the provider and carrier to be used to create the pickup.

  • Returns UNIMPLEMENTED (gRPC code 12) if the provider is OPS, meaning it didn't generated any action.
  • Returns InvalidArgument (gRPC code 3) if the combination of return-method, providerand carrier is not supported.
Security
API Key
Bodyapplication/jsonrequired
carrierstring

Carrier to be used for generating the pickup (DHL, UPS, Correos...) kwown & available for the given provider

currencystring

Currency code (e.g. "EUR", "USD"). Falls back to EUR if empty.

customerobject

Customer Important! the alias at the end is for API docs generation @Description A generic customer in the Rever platform @name api.Customer

customer_addressobject

Address @Description generic address used in many scenarios @name api.Address

ecommerce_groupstring

ecommerce group

ecommerce_idstring

Ecommerce associated to this logistic order

ecommerce_order_idstring

Id of the original ecommerce order (if any) associated to this shipping

ecommerce_warehouse_addressobject

Address @Description generic address used in many scenarios @name api.Address

exchange_flowstring(enum)

Exchange flow of the return. Some carriers vary the label by this (e.g. CTT for Álvaro Moreno uses a different additional code on exchanges).

Enum"NO_EXCHANGE_FLOW""OPEN""ONE_ON_ONE""OPEN_WITH_GIFT_CARD""FULL"
legal_entityobject

Legal entity info for customs/importerDetails (from analytics invoicing endpoint)

line_itemsArray of objects(logistics.LogisticsLineItem)

Line items

line_items_typestring

Line items type used for customs/product data generation for some providers (e.g. UPS). Example values:

  • "random": send a single aggregated product line instead of real items
  • "real": send one product per returned item If empty, providers fall back to their default behaviour.
order_numberstring

Id of the original order (if any) associated to this shipping E-commerces uses this to match the original order when the package arrives to the warehouse

order_purchased_atstring(date-time)

When the original order was purchased. Used to scope order lookups on platforms that don't key orders by the shop's order number (e.g. Monta colourfulrebel, resolved via a date-windowed Reference search).

original_carriersArray of strings

Carriers that shipped the original outbound order (used to flag same-carrier returns).

original_trackingsstring

Original tracking numbers

pickup_rangesArray of strings(enum)

Pick-up time ranges. Only required for return_type = PICKUP

Items Enum"NO_RANGE""RANGE_8_TO_12""RANGE_12_TO_16""RANGE_16_TO_20"
platform_process_idstring

Id of the return process in the source platform. Some carriers use it as the client reference on the label (e.g. CTT for Álvaro Moreno).

process_idstring

Id of the process that the pickup is associated to

providerstring

Provider to be used for generating the pickup (SendCloud, OPS, etc).

return_typestring(enum)

Return method associated to the logistic order (PICKUP, DROP_OFF)

Enum"NO_RETURN_METHOD""HOME_PICK_UP""DROP_OFF_POINT""DELIVERY_PICKUP""IN_STORE"
settingsobject

deprecated

vat_numberstring

VAT Number

weight_in_gramsinteger(int32)

protolint:disable:next FIELD_NAMES_EXCLUDE_PREPOSITIONS Weight of the total sum of packags in grams

curl -i -X PUT \
  https://api.byrever.com/v1/logistics/orders \
  -H 'Content-Type: application/json' \
  -H 'x-rever-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "carrier": "string",
    "currency": "string",
    "customer": {
      "email": "string",
      "first_name": "string",
      "last_name": "string",
      "platform_customer_id": "string",
      "rever_id": "string"
    },
    "customer_address": {
      "address_line_1": "string",
      "address_line_2": "string",
      "city": "string",
      "company": "string",
      "country": "string",
      "country_code": "string",
      "email": "string",
      "first_name": "string",
      "last_name": "string",
      "phone": "string",
      "postcode": "string",
      "rever_id": "string",
      "state_province": "string",
      "state_province_code": "string"
    },
    "ecommerce_group": "string",
    "ecommerce_id": "string",
    "ecommerce_order_id": "string",
    "ecommerce_warehouse_address": {
      "address_line_1": "string",
      "address_line_2": "string",
      "city": "string",
      "company": "string",
      "country": "string",
      "country_code": "string",
      "email": "string",
      "first_name": "string",
      "last_name": "string",
      "phone": "string",
      "postcode": "string",
      "rever_id": "string",
      "state_province": "string",
      "state_province_code": "string"
    },
    "exchange_flow": "NO_EXCHANGE_FLOW",
    "legal_entity": {
      "address": "string",
      "company_name": "string",
      "country": "string",
      "email": "string",
      "full_name": "string",
      "phone": "string"
    },
    "line_items": [
      {
        "custom_attributes": {},
        "dimensions": {
          "height_cm": "string",
          "length_cm": "string",
          "width_cm": "string"
        },
        "ean": "string",
        "id": "string",
        "name": "string",
        "product_return_reason": "string",
        "quantity": 0,
        "sku": "string",
        "subtotal": "string",
        "total": "string",
        "unit_price": "string",
        "weight": "string"
      }
    ],
    "line_items_type": "string",
    "order_number": "string",
    "order_purchased_at": "2019-08-24T14:15:22Z",
    "original_carriers": [
      "string"
    ],
    "original_trackings": "string",
    "pickup_ranges": [
      "NO_RANGE"
    ],
    "platform_process_id": "string",
    "process_id": "string",
    "provider": "string",
    "return_type": "NO_RETURN_METHOD",
    "settings": {
      "logistic_config": [
        {
          "carrier": "string",
          "provider": "string",
          "service_id": "string"
        }
      ],
      "return_method": "NO_RETURN_METHOD"
    },
    "vat_number": "string",
    "weight_in_grams": 0
  }'

Responses

OK

Bodyapplication/json
orderobject

logistic order created

Response
application/json
{
  "order": {
    "carrier": "string",
    "currency_code": "string",
    "id": "string",
    "original_carriers": [ … ],
    "price": 0,
    "provider": "string",
    "requires_customs": true,
    "same_carrier_as_original": true,
    "shipments": [ … ]
  }
}

Processes

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

Operations

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.