Ingrid Returns Partner API (1.0.0)

Ingrid operates on an inverted integration model -- instead of Ingrid calling your APIs, you push data to Ingrid and Ingrid notifies you via webhooks when action is required on your side (e.g. issuing a refund). You then confirm completion back to Ingrid.

All requests require an x-api-key header containing your merchant API key.

All monetary values in the API are decimal numbers in the currency's major unit. For example, 19.99 means 19 euros and 99 cents, not 1999 cents. The currency is always specified alongside money amounts via a currencyCode field using ISO 4217 codes (e.g. "SEK", "EUR", "GBP").

This section describes the full lifecycle of an e-commerce integration with Ingrid Returns, from order placement through to refund completion.

Step 1: Sync your product catalog (mandatory)

Before pushing orders, sync your product catalog to Ingrid using POST /products. Each product should include its variants. Orders reference products by productId and variantId, so products must exist before orders that reference them can be created.

You only need to push each product once -- call POST /products again to update product data (title, images, variants, etc.) at any time.

Step 2: Push orders (mandatory)

When a customer places an order, push it to Ingrid using POST /orders. Line items reference products and variants by ID -- Ingrid uses the product data to show product information in the return portal.

When the order is fulfilled (shipped), call POST /orders again (or PATCH /orders/{orderId}) to add shipment and tracking information. Ingrid uses this to determine return eligibility and to track inbound return parcels.

Step 3: Customer initiates a return

Returns are typically initiated by the customer through Ingrid's return portal, which you embed on your site or link to from order confirmation emails. The portal handles reason selection, return shipping method, and label generation.

Alternatively, you can create returns programmatically via POST /orders/{orderId}/returns -- for example from your own customer service tool or a custom return flow.

You can track return progress by polling GET /returns or by subscribing to webhook events.

Step 4: Warehouse receives the return (choose one)

When the returned items physically arrive at your warehouse, someone needs to report what was received and in what condition. Ingrid supports three ways to do this -- choose the one that fits your operations:

Option A: Warehouse report via API (this API) If you run your own warehouse or have a custom WMS, submit a warehouse report via POST /warehouse-reports. Specify which return, order, or tracking reference the report is for, and for each returned item indicate whether it was received in acceptable condition (APPROVED) or not (DENIED).

Option B: Supported WMS integration Ingrid has built-in integrations with several warehouse management systems (e.g. Ongoing, ShipHero, ShipMonk, and others). If your WMS is supported, warehouse reports are created automatically when your warehouse processes the return. WMS integrations can be configured through the Ingrid backoffice.

Option C: Ingrid backoffice Quality Check If you prefer a manual workflow, warehouse staff can use the Ingrid backoffice to inspect returned items and submit a quality check report.

Regardless of which option you choose, the outcome is the same: approved items proceed to refund calculation, denied items do not.

Step 5: Refund (mandatory)

Once a warehouse report is processed, Ingrid calculates the refund amount based on the approved items and any configured deductions (return shipping cost, handling fee, etc.).

Ingrid marks the refund transaction as AWAITING_EXTERNAL_REFUND, meaning it is ready for you to issue. You have two options for discovering pending refunds:

• Webhooks (recommended): Register a REFUND_PENDING_EXTERNAL webhook. Ingrid sends a POST to your callback URL with the full refund details as soon as the refund is created -- no additional API call is needed.
• Polling: Call GET /refund-transactions?status=AWAITING_EXTERNAL_REFUND periodically to find refund transactions that need action.

Issue the refund to the customer in your payment system for the amount specified in totalAmount, then confirm it via POST /refund-transactions/{refundTransactionId}/complete. This marks the return as SUCCESS.

Step 6: Handle exchanges (optional)

Exchanges occur when a customer chooses to swap a returned item for a different variant (e.g. a different size or color) instead of receiving a refund. If your shop has exchanges enabled, this step runs alongside the refund flow.

How it works:

1. The customer selects a replacement variant during the return flow in the return portal.
2. Depending on your settings, the exchange can either be triggered immediately or later (for example, once the shipment is in transit, or the return arrived at the warehouse). Once the condition is met, and exchange is created with status AWAITING_EXTERNAL_HANDLING, meaning it is ready for you to act on.
3. Discover exchange orders that need handling -- two options:
   • Webhooks (recommended): Register an EXCHANGE_PENDING_EXTERNAL webhook. Ingrid sends a POST with the full exchange details as soon as the exchange is created.
   • Polling: Call GET /exchanges?status=AWAITING_EXTERNAL_HANDLING periodically.
4. For each exchange order, inspect the items array to see which variant the customer is exchanging to (exchangeToVariantId).
5. Create the replacement order in your own e-commerce / fulfillment system.
6. Call POST /exchanges/{exchangeOrderId}/complete with the replacement order details (completedOrderId, completedOrderNumber, completedOrderName).

Exchanges are independent of refunds -- a return can have both a refund (for non-exchanged items) and an exchange (for swapped items).

The Ingrid Returns API is how e-commerce platforms and merchants push the data that powers the Ingrid returns platform - product and order sync, return creation, warehouse reporting, refund confirmation, and exchange fulfillment. Once your data is in Ingrid, the full post-purchase experience is available, including the customer-facing return portal where shoppers register their returns. This API does not cover the return portal at the moment, but it will be added in a future change.

Ingrid operates on an inverted integration model - instead of Ingrid calling your APIs, you push data to Ingrid and Ingrid notifies you via webhooks when action is required on your side (e.g. issuing a refund). You then confirm completion back to Ingrid.

All requests require an x-api-key header containing your merchant API key. All monetary values are decimal numbers in the currency's major unit (e.g. 19.99 = 19 euros and 99 cents). Currency is specified via currencyCode using ISO 4217 codes.

Step 1 - Sync products: Push your product catalog via POST /products. Products must exist before orders that reference them.

Step 2 - Push orders: Create orders via POST /orders. Update with shipment and tracking data when fulfilled via PATCH /orders/{orderId}.

Step 3 - Customer initiates a return: Typically through Ingrid's return portal, or programmatically via POST /orders/{orderId}/returns.

Step 4 - Warehouse receives the return: Report received items via POST /warehouse-reports, a supported WMS integration, or the Ingrid backoffice.

Step 5 - Refund: Ingrid creates a refund transaction with status AWAITING_EXTERNAL_REFUND. Discover pending refunds via the REFUND_PENDING_EXTERNAL webhook or polling (GET /refund-transactions?status=AWAITING_EXTERNAL_REFUND). Issue the refund, then confirm via POST /refund-transactions/{refundTransactionId}/complete.

Step 6 - Exchanges (optional): Exchange orders are created with status AWAITING_EXTERNAL_HANDLING. Discover via the EXCHANGE_PENDING_EXTERNAL webhook or polling (GET /exchanges?status=AWAITING_EXTERNAL_HANDLING). Create the replacement order, then confirm via POST /exchanges/{exchangeOrderId}/complete.