Custom Returns Integration

Overview

This guide helps you integrate your custom e-commerce platform or order management system with Redo by syncing orders through our dedicated orders endpoint. This integration allows you to programmatically send order data to Redo, enabling seamless returns and package protection for your customers. Synced orders also feed Redo order tracking. Once you send a fulfillment with tracking numbers, Redo tracks the shipment and sends tracking notifications according to your Redo settings.

When to Use This Integration

Use the custom integration orders endpoint when:

You have a custom-built e-commerce platform
Your platform isn’t directly supported by Redo
You need programmatic control over order synchronization
You’re building a middleware integration between your systems

Integration flow

The endpoint

POST https://api.getredo.com/v2.2/stores/{storeId}/custom/orders

Your storeId is in Settings → Developer in the Redo Dashboard, where you also generate the API secret. See Authentication for how to send it. The full request and response schema, every field, and a complete example payload live in Sync Custom Order. Syncing the same order id again updates the existing Redo order, so the endpoint is safe to call on every order create and update.

Getting the values right

Line item IDs

id identifies one line on one order, not a product. Use productId and sku for product identity — those are meant to repeat across orders.

Unique within an order — duplicates are rejected with a 400
Stable across re-syncs — returns reference it, so regenerating IDs orphans existing returns
Not reused across orders
No underscores

A per-order counter such as ORD1234-1, ORD1234-2 satisfies all of these.

Money

Send amounts as strings to avoid floating-point drift, and currency codes as ISO 4217. Line item priceSet is pre-tax and pre-discount.

Quantities, taxes and discounts

quantity is the amount ordered; returnableQuantity is how much is eligible for return, which may be lower. Line item taxLines and discounts are totals for all units on the line — quantity × per-unit — not per-unit values. Shipping lines follow the same rule.

Fulfillments

Fulfillments are what make items returnable. Unless your Redo settings allow returns on unfulfilled items, a line with no fulfillment never appears in the return portal. Send a fulfillment once the order ships, and include deliveryDate if your return window should start at delivery rather than at order creation. Include trackingNumbers and trackingUrls on the fulfillment — those drive order tracking and tracking notifications. Shipping lines do not affect what is returnable.

Metafields

Both the order and each line item accept an optional metafields array of namespaced key-value pairs:

metafields: [
  { namespace: "custom", key: "exclude_coverage", value: "true" }
]

Line item metafields are stored on the Redo order line and are read wherever Redo evaluates a metafield, which it addresses as namespace.key — return flow conditions, withdrawal exclusions, and coverage exclusion rules. Order-level metafields are stored on the order for reference. Send values as strings. Metafields are replaced on every re-sync, so send the full set each time.

Cancellations

To mark an order cancelled, re-sync it with cancelledAt set:

cancelledAt: "2026-02-01T00:00:00Z",
cancelReason: "customer"

Redo records the order with a voided financial status and stops producing order tracking updates for it. Clearing cancelledAt on a later sync reinstates the order. cancelledAt is what marks the order cancelled. cancelReason is optional and records why:

Reason	Use when
`customer`	The shopper asked to cancel the order.
`fraud`	You cancelled the order because you judged it fraudulent.
`inventory`	You could not supply the items, so you cancelled the order.
`declined`	Payment was declined, so the order was never completed.
`staff`	Someone on your team cancelled it, including to correct an order-entry mistake.
`other`	Any reason the values above do not describe.

Redo stores the reason as a record of the cancellation and does not behave differently based on which one you send, so pick the closest match and use other when nothing fits. Sending a value outside this list is rejected with a 400. Cancelling does not by itself close the return window. To stop items being returned, send returnableQuantity: 0 on every line item.

Refunds

Send refunds you have already issued against the order in the refunds array. Redo does not issue these refunds; it reads them to know what the shopper has already been paid back, and to derive the order’s financial status.

refunds: [
  {
    id: "refund-1",
    createdAt: "2026-02-01T00:00:00Z",
    note: "Damaged in transit",
    lineItems: [
      {
        lineItemId: "line-1",
        quantity: 1,
        subtotalSet: {
          shopMoney: { amount: "20.00", currencyCode: "USD" },
          presentmentMoney: { amount: "20.00", currencyCode: "USD" },
        },
        totalTaxSet: {
          shopMoney: { amount: "1.60", currencyCode: "USD" },
          presentmentMoney: { amount: "1.60", currencyCode: "USD" },
        },
      },
    ],
    shippingRefunds: [],
    orderLevelRefunds: [],
  },
]

lineItemId must match the id of a line item on the same order. A refund line referencing an unknown line item is ignored, so re-sync the order with its line items whenever you send refunds against them. Use shippingRefunds for refunded shipping and orderLevelRefunds for amounts refunded against the order as a whole, such as a goodwill adjustment. Both take an amountSet, an optional taxAmountSet, and an optional free-text reason. Send those amounts as positive values. Refunds are replaced on every re-sync, so send the full set each time, using a stable id per refund. Redo derives the order’s financial status from what you send: paid with no refunds, partially_refunded while the refunded total is below the order total, and refunded once it reaches it. A cancelled order is voided regardless of refunds.

Coverage

The Redo coverage line item

When a shopper has purchased Redo protection — returns, package protection, or both — you must include a line item with these exact values:

{
  id: string,                    // Unique ID for this line item
  vendor: "re:do",              // Exactly "re:do"
  sku: "x-redo",                // Exactly "x-redo"
  priceSet: { /* Full coverage price paid */ },
  tags: ["returns"],            // One or more: "returns", "package protection", "both"
  properties: [
    {
      name: "_redo_type",
      value: "returns"          // "returns", "package protection", or "both"
    }
  ],
  // ... other standard line item fields
}

priceSet must be the full amount the shopper paid for coverage. When one line item covers more than one type, send the combined total. If both are sent, _redo_type wins over tags. Keep them in sync.

Final sale

When the shopper buys final sale returns coverage, mark it alongside returns:

tags: ["returns", "final sale"]
// or
properties: [{ name: "_redo_type", value: "returns,final sale" }]

Final sale coverage always implies returns coverage. Without this, final sale only applies if your Redo settings cover every order.

Package Protection Plus

Shopper-paid — include the coverage line item with _redo_type: "package protection" (or "both"), priced at what the shopper paid.
Merchant-paid or all orders covered — send no coverage line item. Redo applies it based on your Redo settings.

Next steps

Get API credentials

In the Redo Dashboard, go to Settings → Developer and click Add API Client.

Map your orders

Follow Sync Custom Order for the field-by-field schema.

Send test orders

Validate with test orders, including one with a coverage line item, before going live.

Need help?

Contact support@getredo.com, or see the API Reference.

Getting Started

Integrations

Other

Custom Returns Integration

Overview

When to Use This Integration

Integration flow

The endpoint

Getting the values right

Line item IDs

Money

Quantities, taxes and discounts

Fulfillments

Metafields

Cancellations

Refunds

Coverage

The Redo coverage line item

Final sale

Package Protection Plus

Next steps

Need help?

​Overview

​When to Use This Integration

​Integration flow

​The endpoint

​Getting the values right

​Line item IDs

​Money

​Quantities, taxes and discounts

​Fulfillments

​Metafields

​Cancellations

​Refunds

​Coverage

​The Redo coverage line item

​Final sale

​Package Protection Plus

​Next steps

​Need help?

Overview

When to Use This Integration

Integration flow

The endpoint

Getting the values right

Line item IDs

Money

Quantities, taxes and discounts

Fulfillments

Metafields

Cancellations

Refunds

Coverage

The Redo coverage line item

Final sale

Package Protection Plus

Next steps

Need help?