InRetrn

What is InRetrn?

InRetrn is a returns platform that handles the consumer-facing part of a return. The customer looks up their order in the InRetrn portal, registers what they want to send back, and receives a return label. To do that, InRetrn needs the order history — which is what this integration delivers.

The integration covers three flows:

• Order export — orders are pushed to InRetrn as sales orders so they can be found in the returns portal.
• Return export — returns registered in Omnium are pushed to InRetrn as return orders.
• Returns from InRetrn — returns and exchanges registered in the InRetrn portal are written back into Omnium through the public Returns API.

Setup in Omnium

Connector

Add a connector under Configuration → Advanced Settings → Connectors. The connector Name must be inretrn — this is the value you reference from the workflow steps that trigger the export.

The username and token are combined and sent base64-encoded in the Authorization header on every request.

{
    "name": "inretrn",
    "host": "https://api.inretrn.com/",
    "username": "",
    "token": "",
    "properties": [
        {
            "key": "InretrnUseShippingAddress",
            "value": "false"
        }
    ]
}

Connector properties

Connector selection per market

Both exports resolve the connector from the order's market, in this order:

1. A global connector named or typed inretrn that lists the order's market in Enabled for markets.
2. A connector named or typed inretrn defined directly on the market.
3. A global connector named or typed inretrn with no market restriction.

This lets you run separate InRetrn accounts per market, or one account across all of them.

Order export

Trigger

Orders are exported by the Export Order workflow step with Connector set to inretrn. Add it to whichever order statuses should make the order available in the returns portal — typically the status where the order is shipped or completed.

{
  "Name": "ExportOrder",
  "Connector": "inretrn"
}

The order must have an order number. Orders without one are rejected.

Endpoint

Sales order

Buyer

The source address is the billing address, or the shipment address when InretrnUseShippingAddress is enabled. Whichever is chosen, the other one is used as fallback when it is missing.

Payments

One entry per payment on the order.

Order lines

Each order line is looked up as a product before it is mapped. The line's code is searched as both product id and SKU id, the results are narrowed to the order's market, and the product matching the market's content language is preferred. When the code matches a variant, the parent product supplies the item data and the variant supplies the variant data, with the parent as fallback for any empty variant field.

Freight lines

One additional order line is appended per shipment on the order:

Backfilling order history

Orders placed before the integration went live are not in InRetrn, so customers cannot look them up in the portal. Existing order history can be loaded in bulk — contact Omnium support to arrange it. Orders without order lines or without an order number are skipped.

Return export

Trigger

Returns are exported by the Export Order return workflow step with Connector set to inretrn. Add it to the return status where the return should be registered in InRetrn.

{
  "Name": "ExportOrder",
  "Connector": "inretrn"
}

After a successful export, the InRetrn return order number is stored on the return as the external id InretrnReturnId. Running the step again exports the return again — Omnium does not skip returns that already carry the external id.

Endpoint

Return order

Return lines

A return line whose code does not match any line on the original order is skipped, and an error is added to the order.

Returns registered in InRetrn

Returns that customers register in the InRetrn portal are pushed back into Omnium over the public Returns API:

These are the standard Returns API endpoints — no InRetrn-specific endpoints are involved. Configure the return statuses and workflow steps that credit the payment, update inventory and notify the customer as described in Return configuration.

Configuration reference

Product properties

Setting either property also changes the line's LineType to 2. Use them on products that should not follow the standard return rules, such as fees and gift cards.

Store and market properties

Order properties

Return properties

External seller reference

ExternalSellerReference identifies the selling entity in InRetrn. It is only resolved for orders that have a store:

1. When the order's store has the property InretrnExternalSellerStoreProperty, its value is used.
2. Otherwise the order's market is checked.

Orders without a store id are exported without a seller reference.

Country resolution

InRetrn requires a country on the buyer, so the country is resolved to an ISO 3166-1 alpha-2 code from the first of these that yields one:

1. The country code, then the country name, of the order's addresses — in the same order the buyer address is chosen.
2. The store's address, then the store's shipping address.
3. The market's country code.

Two-letter codes, three-letter codes and English country names all resolve. Values that are not countries — region groupings such as EU or Europe — are left unresolved rather than guessed, and the export then fails on InRetrn's own validation.

The same resolution is applied to the product's country of origin for ItemCountryOfOrigin.

Errors and troubleshooting

A failed export adds an error to the order, visible on the order in the Omnium GUI. The error is removed on the next successful export of the same kind.