Returns Public API

The Returns Public API allows e-commerce platforms to integrate with Ingrid's return management system where you can:

Retrieve order and return information
Report items that have been returned (received at your warehouse)
Marking items as externally refunded

Staging environment
https://dev.api.turnr.se

Production environment
https://api.turnr.se

Authentication

All API requests require authentication using an API key. You can generate an API key in the Returns backoffice at:

https://returns-portal.ingrid.com/settings/api-keys

Supply this API key in the request header for all requests:

x-api-key: "your_api_key"

API Endpoints

Optional parameter sort

The sort parameter is used in multiple endpoints allows you to specify the field and direction to sort the results by. The format is:

sort=field,direction

Where:

field is any property of the entity (e.g., id, createdAt, foreignId)
direction is either asc (ascending) or desc (descending)

Examples:

sort=createdAt,desc - Sort by creation date in descending order (newest first)
sort=createdAt,asc - Sort by creation date in ascending order (oldest first)
sort=id,desc - Sort by ID in descending order

You can also sort by multiple fields by providing multiple sort parameters:

sort=status,asc&sort=createdAt,desc - Sort by status ascending, then by creation date descending

Get Orders

Retrieves a paginated list of orders. Note that these orders in our system are pretty much clones of the e-commerce orders

GET /merchant/order
x-api-key: "your_api_key"

Optional query parameters

page - Page number (default: 0)

size - Page size (default: 0)

sort - Sort field (default: "id"). See Sort

afterId - Only return orders with ID greater than this value

afterDate - Only return orders created after this date (ISO 8601, YYYY-MM-DDThh:mm:ss)

{
  "content": [
    {
      "id": 286,
      "foreignId": "3653606244560",
      "createdAt": "2021-05-03T16:09:48.952212Z"
    },
    {
      "id": 316,
      "foreignId": "3653711200464",
      "createdAt": "2021-05-04T08:41:47.003653Z"
    }
  ],
  "pageable": {
    "sort": {
      "sorted": true,
      "unsorted": false,
      "empty": false
    },
    "offset": 0,
    "pageSize": 10,
    "pageNumber": 0,
    "unpaged": false,
    "paged": true
  },
  "totalPages": 2,
  "totalElements": 11,
  "last": false,
  "size": 10,
  "number": 0,
  "sort": {
    "sorted": true,
    "unsorted": false,
    "empty": false
  },
  "numberOfElements": 10,
  "first": true,
  "empty": false
}

Get Returns

Retrieves a paginated list of returns for a merchant.

GET /merchant/return
x-api-key: "your_api_key"

Optional query parameters

page - Page number (default: 0)

size - Page size (default: 0)

sort - Sort field (default: "id"). See Sort

afterId - Only return orders with ID greater than this value

afterDate - Only return orders created after this date (ISO 8601, YYYY-MM-DDThh:mm:ss)

{
  "content": [
    {
      "id": 256,
      "createdAt": "2021-05-03T16:09:48.952212Z",
      "status": "AWAITING_RETURN",
      "statusUrl": "https://returns.ingrid.com/turnrtest/status/3653606244560?email=mathias.gesar%40gmail.com&return=256",
      "order": {
        "id": 286,
        "foreignId": "3653606244560",
        "createdAt": "2021-05-03T16:09:48.952212Z"
      }
    },
    {
      "id": 286,
      "createdAt": "2021-05-04T08:41:47.003653Z",
      "status": "AWAITING_RETURN",
      "statusUrl": "https://returns.ingrid.com/turnrtest/status/3653711200464?email=mathias.gesar%40gmail.com&return=286",
      "order": {
        "id": 316,
        "foreignId": "3653711200464",
        "createdAt": "2021-05-04T08:41:47.003653Z"
      }
    }
  ],
  "pageable": {
    "sort": {
      "sorted": true,
      "unsorted": false,
      "empty": false
    },
    "offset": 0,
    "pageSize": 10,
    "pageNumber": 0,
    "unpaged": false,
    "paged": true
  },
  "totalPages": 2,
  "totalElements": 11,
  "last": false,
  "size": 10,
  "number": 0,
  "sort": {
    "sorted": true,
    "unsorted": false,
    "empty": false
  },
  "numberOfElements": 10,
  "first": true,
  "empty": false
}

Get Order Details

Retrieves details about a specific order. Note that this is the order in our system which pretty much is a clone of the e-commerce order

GET /merchant/order/{orderId}
x-api-key: "your_api_key"

Optional query parameters

idType - Type of ID used (default: "INGRID_ID"). Possible values:

-- INGRID_ID - Ingrid's internal order ID

-- FOREIGN_ID - Your order ID

-- FOREIGN_NUMBER - Your order number

-- FOREIGN_NAME - Your order name

{
  "id": 4624909,
  "foreignId": "6652600877399",
  "foreignName": "#1452",
  "foreignNumber": 1452,
  "orderRefund": {
    "currencyCode": "SEK",
    "amountRefunded": 654.0,
    "refundStatus": "COMPLETED",
    "transactions": [
      {
        "foreignId": "8249631113559",
        "refundType": "BASIC",
        "currencyCode": "SEK",
        "source": "TURNR",
        "totalAmount": 654.0,
        "itemsAmount": 654.0,
        "shippingRefundAmount": 0.0,
        "exchangeCost": 0.0,
        "returnCost": 0.0,
        "giftCardAddition": 0.0
      }
    ]
  },
  "createdAt": "2025-06-03T12:43:41.813922Z",
  "returns": [
    {
      "id": 536774,
      "createdAt": "2025-06-03T12:46:49.627205Z",
      "status": "COMPLETED",
      "statusUrl": "https://returns.ingrid.com/turnrtest/status/6652600877399?email=ommatte%40gmail.com&return=536774",
      "order": {
        "id": 4624909,
        "foreignId": "6652600877399",
        "foreignName": "#1452",
        "foreignNumber": 1452,
        "createdAt": "2025-06-03T12:43:41.813922Z"
      },
      "returnCosts": {
        "currencyCode": "SEK",
        "returnShipmentCost": 0,
        "returnHandlingCost": 0,
        "exchangeCost": 0,
        "failedDeliveryCost": 0,
        "totalCost": 0
      },
      "calculatedRefund": {
        "currencyCode": "SEK",
        "totalRefundAmount": 0,
        "lines": []
      },
      "refundTransactions": [
        {
          "foreignId": "8249631113559",
          "refundType": "BASIC",
          "currencyCode": "SEK",
          "source": "TURNR",
          "totalAmount": 654.0,
          "itemsAmount": 654.0,
          "shippingRefundAmount": 0.0,
          "exchangeCost": 0.0,
          "returnCost": 0.0,
          "giftCardAddition": 0.0
        }
      ],
      "items": [
        {
          "id": 937395,
          "foreignLineItemId": "16817219076439",
          "quantity": 1,
          "status": "RETURNED",
          "refundStatus": "REFUNDED",
          "purchasePriceAmount": {
            "currencyCode": "SEK",
            "amount": 155.0,
            "itemTax": 0.0
          },
          "productVariant": {
            "id": 623,
            "foreignProductId": "7067955560611",
            "foreignVariantId": "40874281140387",
            "properties": [
              {
                "type": "Size",
                "value": "40"
              }
            ],
            "sku": "S-VARD-1",
            "productTitle": "Eldflamssvärd",
            "variantTitle": "40"
          },
          "returnReasons": [
            {
              "id": 217,
              "reason": "Wrong color",
              "subReason": "Too light",
              "subReasonId": 131
            }
          ],
          "returnedToWarehouseAt": "2025-06-03T12:57:23.525924Z",
          "restockStatus": "NO_RESTOCK",
          "approvedForRestock": true
        },
        {
          "id": 937396,
          "foreignLineItemId": "16817219141975",
          "quantity": 1,
          "status": "RETURNED",
          "refundStatus": "REFUNDED",
          "purchasePriceAmount": {
            "currencyCode": "SEK",
            "amount": 499.0,
            "itemTax": 0.0
          },
          "productVariant": {
            "id": 664,
            "foreignProductId": "7166141628579",
            "foreignVariantId": "41143834312867",
            "properties": [
              {
                "type": "Size",
                "value": "S"
              }
            ],
            "sku": "12345",
            "productTitle": "Shirt - Lisa",
            "variantTitle": "S"
          },
          "customerComplaint": {
            "id": 38737,
            "status": "APPROVED",
            "complaintReason": {
              "id": 115,
              "reason": "Item is faulty"
            },
            "complaintText": "Did not look great",
            "image": {
              "id": 82970,
              "uuid": "ea639e76-efdb-43dd-ba0e-488ff7fca5aa",
              "downloadUrl": "https://storage.googleapis.com/turnr/ea639e76-efdb-43dd-ba0e-488ff7fca5aa?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=turnr-shopify-java-app%40turnr-core-prod.iam.gserviceaccount.com%2F20250612%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20250612T133922Z&X-Goog-SignedHeaders=host&x-goog-expires=900&X-Goog-Signature=BC3F171994E0497F835A5805632D5E15AB3F9B4C3C60238A7316DBDE7142241ACB6FEF64E0A2F88BB9E40012C40EA527A3A4E20AC1765ADDDD695B951522DCCFD7DF779E8F803C9D8B5B72DFB998D3AEF8D5548C845C9D4D679332BA905ABDC29943B3CE315A8B25D3F5B27ADB88565D22666398542C4FF3B440515E6AC55DC58313CDB91CE3AE0E95C442BEC71F3A770A82BDBD7FCB0F420C7BE7FAA645DC294B275DD9DE2370E090B765CF45CBF522ED05B71B90A7C36577FA39C863107530589F2B77A7F05010F7B0DF10C78F568B38EA47C9F98196316D83D558EBF66DBC28907FEC38D6F2419F9B69DB6F74EA2905730B7CB0D26E7B3B1455E073F70A7A"
            }
          },
          "returnReasons": [],
          "returnedToWarehouseAt": "2025-06-03T12:57:23.525943Z",
          "restockStatus": "NO_RESTOCK",
          "approvedForRestock": true
        }
      ],
      "shipments": [
        {
          "id": 468386,
          "foreignId": "TID-468386",
          "type": "C2B",
          "carrier": "TEST",
          "trackingReference": "TR-468386"
        }
      ],
      "exchanges": []
    }
  ],
  "items": [
    {
      "id": 937395,
      "foreignLineItemId": "16817219076439",
      "quantity": 1,
      "status": "RETURNED",
      "refundStatus": "REFUNDED",
      "purchasePriceAmount": {
        "currencyCode": "SEK",
        "amount": 155.0,
        "itemTax": 0.0
      },
      "productVariant": {
        "id": 623,
        "foreignProductId": "7067955560611",
        "foreignVariantId": "40874281140387",
        "properties": [
          {
            "type": "Size",
            "value": "40"
          }
        ],
        "sku": "S-VARD-1",
        "productTitle": "Eldflamssvärd",
        "variantTitle": "40"
      },
      "returnReasons": [
        {
          "id": 217,
          "reason": "Wrong color",
          "subReason": "Too light",
          "subReasonId": 131
        }
      ],
      "returnedToWarehouseAt": "2025-06-03T12:57:23.525924Z",
      "restockStatus": "NO_RESTOCK",
      "approvedForRestock": true
    },
    {
      "id": 937396,
      "foreignLineItemId": "16817219141975",
      "quantity": 1,
      "status": "RETURNED",
      "refundStatus": "REFUNDED",
      "purchasePriceAmount": {
        "currencyCode": "SEK",
        "amount": 499.0,
        "itemTax": 0.0
      },
      "productVariant": {
        "id": 664,
        "foreignProductId": "7166141628579",
        "foreignVariantId": "41143834312867",
        "properties": [
          {
            "type": "Size",
            "value": "S"
          }
        ],
        "sku": "12345",
        "productTitle": "Shirt - Lisa",
        "variantTitle": "S"
      },
      "customerComplaint": {
        "id": 38737,
        "status": "APPROVED",
        "complaintReason": {
          "id": 115,
          "reason": "Item is faulty"
        },
        "complaintText": "Did not look great",
        "image": {
          "id": 82970,
          "uuid": "ea639e76-efdb-43dd-ba0e-488ff7fca5aa",
          "downloadUrl": "https://storage.googleapis.com/turnr/ea639e76-efdb-43dd-ba0e-488ff7fca5aa?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=turnr-shopify-java-app%40turnr-core-prod.iam.gserviceaccount.com%2F20250612%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20250612T133922Z&X-Goog-SignedHeaders=host&x-goog-expires=900&X-Goog-Signature=BC3F171994E0497F835A5805632D5E15AB3F9B4C3C60238A7316DBDE7142241ACB6FEF64E0A2F88BB9E40012C40EA527A3A4E20AC1765ADDDD695B951522DCCFD7DF779E8F803C9D8B5B72DFB998D3AEF8D5548C845C9D4D679332BA905ABDC29943B3CE315A8B25D3F5B27ADB88565D22666398542C4FF3B440515E6AC55DC58313CDB91CE3AE0E95C442BEC71F3A770A82BDBD7FCB0F420C7BE7FAA645DC294B275DD9DE2370E090B765CF45CBF522ED05B71B90A7C36577FA39C863107530589F2B77A7F05010F7B0DF10C78F568B38EA47C9F98196316D83D558EBF66DBC28907FEC38D6F2419F9B69DB6F74EA2905730B7CB0D26E7B3B1455E073F70A7A"
        }
      },
      "returnReasons": [],
      "returnedToWarehouseAt": "2025-06-03T12:57:23.525943Z",
      "restockStatus": "NO_RESTOCK",
      "approvedForRestock": true
    }
  ],
  "shipments": [
    {
      "id": 468386,
      "foreignId": "TID-468386",
      "type": "C2B",
      "carrier": "TEST",
      "trackingReference": "TR-468386"
    }
  ],
  "exchanges": []
}

Get Return Details

Retrieves details about a specific return.

GET /merchant/return/{returnId}
x-api-key: "your_api_key"

{
  "id": 536774,
  "createdAt": "2025-06-03T12:46:49.627205Z",
  "status": "COMPLETED",
  "statusUrl": "https://returns.ingrid.com/turnrtest/status/6652600877399?email=ommatte%40gmail.com&return=536774",
  "order": {
    "id": 4624909,
    "foreignId": "6652600877399",
    "foreignName": "#1452",
    "foreignNumber": 1452,
    "createdAt": "2025-06-03T12:43:41.813922Z"
  },
  "returnCosts": {
    "currencyCode": "SEK",
    "returnShipmentCost": 0,
    "returnHandlingCost": 0,
    "exchangeCost": 0,
    "failedDeliveryCost": 0,
    "totalCost": 0
  },
  "calculatedRefund": {
    "currencyCode": "SEK",
    "totalRefundAmount": 0,
    "lines": []
  },
  "refundTransactions": [
    {
      "foreignId": "8249631113559",
      "refundType": "BASIC",
      "currencyCode": "SEK",
      "source": "TURNR",
      "totalAmount": 654.0,
      "itemsAmount": 654.0,
      "shippingRefundAmount": 0.0,
      "exchangeCost": 0.0,
      "returnCost": 0.0,
      "giftCardAddition": 0.0
    }
  ],
  "items": [
    {
      "id": 937395,
      "foreignLineItemId": "16817219076439",
      "quantity": 1,
      "status": "RETURNED",
      "refundStatus": "REFUNDED",
      "purchasePriceAmount": {
        "currencyCode": "SEK",
        "amount": 155.0,
        "itemTax": 0.0
      },
      "productVariant": {
        "id": 623,
        "foreignProductId": "7067955560611",
        "foreignVariantId": "40874281140387",
        "properties": [
          {
            "type": "Size",
            "value": "40"
          }
        ],
        "sku": "S-VARD-1",
        "productTitle": "Eldflamssvärd",
        "variantTitle": "40"
      },
      "returnReasons": [
        {
          "id": 217,
          "reason": "Wrong color",
          "subReason": "Too light",
          "subReasonId": 131
        }
      ],
      "returnedToWarehouseAt": "2025-06-03T12:57:23.525924Z",
      "restockStatus": "NO_RESTOCK",
      "approvedForRestock": true
    },
    {
      "id": 937396,
      "foreignLineItemId": "16817219141975",
      "quantity": 1,
      "status": "RETURNED",
      "refundStatus": "REFUNDED",
      "purchasePriceAmount": {
        "currencyCode": "SEK",
        "amount": 499.0,
        "itemTax": 0.0
      },
      "productVariant": {
        "id": 664,
        "foreignProductId": "7166141628579",
        "foreignVariantId": "41143834312867",
        "properties": [
          {
            "type": "Size",
            "value": "S"
          }
        ],
        "sku": "12345",
        "productTitle": "Shirt - Lisa",
        "variantTitle": "S"
      },
      "customerComplaint": {
        "id": 38737,
        "status": "APPROVED",
        "complaintReason": {
          "id": 115,
          "reason": "Item is faulty"
        },
        "complaintText": "Did not look great",
        "image": {
          "id": 82970,
          "uuid": "ea639e76-efdb-43dd-ba0e-488ff7fca5aa",
          "downloadUrl": "https://storage.googleapis.com/turnr/ea639e76-efdb-43dd-ba0e-488ff7fca5aa?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=turnr-shopify-java-app%40turnr-core-prod.iam.gserviceaccount.com%2F20250612%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20250612T134219Z&X-Goog-SignedHeaders=host&x-goog-expires=900&X-Goog-Signature=86F18D6922D118BB41B42D93748DA1554FA605AC10FC8B259436043F65ECA0D6E35615A7D261FB49AC82FC9F24C2F7033E00E0BA9FDD4604A6184FC8A4A96B5ED008B932EFC889BA82C59CF2AD4BC46BC6902D53AEA26EB2C85AF47B39CFEC197251A41141A682D8D78F8E47C4B22EEC767824503D5A623B7BAC8528DD888377B9F7431426BE434C2F2AEE81C815F90414BC0D773BB2F4FF02D364FDCB2C1CA0DFE50D95D65215291DECEB80A3293056F74F7E046DC08F1185B423D8E95E8922903B2208393D7A453F07F737D11E45B841BD0EBDB686EDFD20DD7787BE9448313B08DE4D7CF217CA0EB3785BC10E12F33D3E3FAD24028B9609623B462847FCDF"
        }
      },
      "returnReasons": [],
      "returnedToWarehouseAt": "2025-06-03T12:57:23.525943Z",
      "restockStatus": "NO_RESTOCK",
      "approvedForRestock": true
    }
  ],
  "shipments": [
    {
      "id": 468386,
      "foreignId": "TID-468386",
      "type": "C2B",
      "carrier": "TEST",
      "trackingReference": "TR-468386"
    }
  ],
  "exchanges": []
}

Report Returned Items

Reports items that have been returned by a customer.

POST /merchant/items/returned
Content-Type: application/json
x-api-key: "your_api_key"

{
  "foreignOrderId": "ORD123456789",
  "returnId": 987654,
  "trackingReference": "DHL1234567890",
  "items": [
    {
      "sku": "SKU001",
      "quantity": 1,
      "approved": true,
      "comment": "Item in good condition"
    },
    {
      "sku": "SKU002",
      "quantity": 1,
      "approved": false,
      "comment": "Item damaged"
    }
  ]
}

Only one of these values has to be set: foreignOrderId, returnId, or trackingReference.

200 OK

Get Refund Transactions

Retrieves a paginated list of refund transactions.

GET /merchant/refund/transaction
x-api-key: "your_api_key"

Optional query parameters

status - Filter by refund transaction status ("AWAITING_EXTERNAL_REFUND", "PENDING", "SUCCESS", "FAILED")
page - Page number (default: 0)
size - Page size (default: 20)
sort - Sort field. See Sort

{
  "content": [
    {
      "refundId": 123456,
      "createdAt": "2023-07-28T10:30:00Z",
      "order": {
        "id": 123456,
        "foreignId": "ORD123456789",
        "createdAt": "2023-07-26T14:30:00Z",
        "status": "COMPLETED"
      },
      "status": "AWAITING_EXTERNAL_REFUND",
      "currencyCode": "SEK",
      "amountToRefund": 59.98,
      "refundDetails": {
        "refundAmounts": {
          "totalItemRefundAmount": 59.98,
          "shippingRefundAmount": 0.0
        },
        "returnCosts": {
          "currencyCode": "SEK",
          "returnShipmentCost": 39.0,
          "returnHandlingCost": 0.0,
          "failedDeliveryCost": 0.0,
          "exchangeCost": 0.0,
          "totalReturnCost": 39.0
        },
        "items": [
          {
            "foreignOrderLineItemId": "ITEM001",
            "refundAmount": 59.98,
            "name": "T-Shirt"
          }
        ]
      }
    }
  ],
  "pageable": {
    "sort": {
      "unsorted": true,
      "sorted": false,
      "empty": true
    },
    "offset": 0,
    "pageSize": 20,
    "pageNumber": 0,
    "paged": true,
    "unpaged": false
  },
  "totalPages": 2,
  "totalElements": 38,
  "last": false,
  "size": 20,
  "number": 0,
  "sort": {
    "unsorted": true,
    "sorted": false,
    "empty": true
  },
  "numberOfElements": 20,
  "first": true,
  "empty": false
}

Mark Refund as Successful

Marks a refund transaction as successfully refunded.

POST /merchant/refund/transaction/{refundTransactionId}/refunded
x-api-key: "your_api_key"

{
  "refundId": 123456,
  "createdAt": "2023-07-28T10:30:00Z",
  "order": {
    "id": 123456,
    "foreignId": "ORD123456789",
    "createdAt": "2023-07-26T14:30:00Z",
    "status": "COMPLETED"
  },
  "status": "REFUNDED",
  "currencyCode": "SEK",
  "amountToRefund": 59.98,
  "refundDetails": {
    "refundAmounts": {
      "totalItemRefundAmount": 59.98,
      "shippingRefundAmount": 0.0
    },
    "returnCosts": {
      "currencyCode": "SEK",
      "returnShipmentCost": 39.0,
      "returnHandlingCost": 0.0,
      "failedDeliveryCost": 0.0,
      "exchangeCost": 0.0,
      "totalReturnCost": 39.0
    },
    "items": [
      {
        "foreignOrderLineItemId": "ITEM001",
        "refundAmount": 59.98,
        "name": "T-Shirt"
      }
    ]
  }
}

Last updated: Mon, Jun 16, 09:36 AM