Ingrid Returns - Developer Integration Guide

﻿
OverviewThis guide provides a comprehensive explanation of the Ingrid Returns API endpoints and webhooks to help developers manage and track returns for merchants. It covers the return process, best practices for using webhooks and API calls, includes examples for all webhooks, and provides detailed references for each API endpoint. By following this guide, developers can seamlessly integrate these APIs, improving operational efficiency and the customer experience.
﻿
API Reference:  Ingrid Returns API Reference ﻿
﻿
How a Return WorksOverview of the Return ProcessThe return process within Ingrid Returns follows a typical lifecycle, from the customer initiating a return to final completion, which may involve refunds, exchanges, or restocking of items. Below is an outline of the return lifecycle:
.1Return Initiation:
Customer Action: The customer initiates a return via the merchant's platform.
System Action: Ingrid Returns creates a new return record, assigning it a unique returnId, and the return enters the AWAITING_RETURN state.
.2Return in Transit:
Customer Action: The customer ships the items using a return label or carrier.
System Action: The return status updates to IN_TRANSIT, tracking the item’s journey back to the warehouse.
.3Warehouse Arrival and Inspection:
System Action: Upon arrival at the warehouse, the items are inspected.
Merchant Action: After inspection, items may be approved or rejected, and their status is updated.
.4Refund or Exchange Processing:
System Action: If approved, the return moves into AWAITING_REFUND or depending on the exchange policyAWAITING_EXCHANGE. Rejected items will create a warehouse remark in Ingrid Returns Backoffice that needs to be handled.
.5Return Completion:
System Action: After processing, the return enters the COMPLETED state, and refunds or exchanges are finalized.
Return workflow summary.1Customer initiates return
.2Item is shipped
.3Warehouse inspects item
.4Approval/Rejection
.5Refund/Exchange processing
.6Return completed
﻿
AuthenticationAll API requests require an API key in the x-api-key header for authentication. Ensure that the API key is valid and included in every request to the endpoints.
﻿
API Endpoints1. Retrieve a List of ReturnsEndpoint: GET https://api.turnr.se/merchant/return
Fetch a paginated list of returns, with filtering options based on date and ID.
Request Parameters
Headers:
x-api-key (string, required): Your API key.
Query Parameters:
afterId (integer, optional): Include returns created after the specified return ID.
afterDate (string, optional, date-time format): Include returns created after the specified date.
page (integer, required): Page number to retrieve.
size (integer, required): Number of results per page.
sort (array of strings, optional): Sorting criteria for the results.
Example Request
GET https://api.turnr.se/merchant/return?page=1&size=10 HTTP/1.1 
Host: api.turnr.se 
x-api-key: YOUR_API_KEY 
Response Properties
totalPages (integer): Total number of pages.
totalElements (integer): Total number of return records.
size (integer): Number of records per page.
content (array): List of return records.
Each item in content includes:
id (integer): Return ID.
createdAt (string, date-time): Return creation timestamp.
status (string): Current status of the return
statusUrl (string): URL for tracking the return status.
order (object):
id (integer): Ingrid Returns order ID.
foreignId (string): External order ID.
foreignName (string): Name or description of the order.
foreignNumber (integer): External order number.
createdAt (string, date-time): Order creation timestamp.
Example Response
{
  "totalPages": 5,
  "totalElements": 50,
  "size": 10,
  "content": [
    {
      "id": 261868,
      "createdAt": "2024-09-18T12:00:00Z",
      "status": "AWAITING_RETURN",
      "statusUrl": "https://tracking.turnr.se/return/261868",
      "order": {
        "id": 12345,
        "foreignId": "23965dbb5e9592ba1c19be0651ee9c5a",
        "foreignName": "Order #1001",
        "foreignNumber": 1001,
        "createdAt": "2024-09-15T09:30:00Z"
      }
    }
    // Additional return records...
  ]
}
﻿
2. Retrieve a Specific ReturnEndpoint: GET https://api.turnr.se/merchant/return/{returnId}
Get detailed information about a specific return, including costs, refund transactions, and items involved.
Request Parameters
Headers:
x-api-key (string, required): Your API key.
Path Parameters:
returnId (integer, required): Return ID to retrieve.
Example Request
GET https://api.turnr.se/merchant/return/261868 HTTP/1.1 
Host: api.turnr.se 
x-api-key: YOUR_API_KEY
Response Properties
id (integer): Return ID.
createdAt (string, date-time): Return creation timestamp.
status (string): Current status of the return
statusUrl (string): URL for tracking the return.
order (object):
id (integer): Ingrid Returns order ID.
foreignId (string): External order ID.
foreignName (string): Name associated with the order.
foreignNumber (integer): External order number.
createdAt (string, date-time): Order creation timestamp.
returnCosts (object):
currencyCode (string): Currency code (e.g., SEK).
returnShipmentCost (number): Shipping cost for the return.
returnHandlingCost (number): Handling cost for the return.
totalCost (number): Total cost of the return.
refundTransactions (array):
Each transaction includes:
foreignId (string): External refund transaction ID.
refundType (string): Type of refund (e.g., GIFT_CARD, BASIC).
currencyCode (string): Currency used.
totalAmount (number): Total refunded amount.
items (array):
Each item includes:
id (integer): Item ID.
foreignLineItemId (string): External line item ID.
status (string): Item status
purchasePriceAmount (object):
currencyCode (string): Currency used.
amount (number): Price of the item.
productVariant (object):
sku (string): Stock Keeping Unit.
productTitle (string): Product title.
variantTitle (string): Variant title.
Example Response
{
    "id": 261868,
    "createdAt": "2024-09-26T19:47:01.273523Z",
    "status": "AWAITING_RETURN",
    "statusUrl": "https://returns.turnr.se/merchant/status/124",
    "order": {
        "id": 254843,
        "foreignId": "980ab3e70810976cfd544fa785ebcba3",
        "foreignNumber": 1520547,
        "createdAt": "2024-09-23T15:41:29.346454Z"
    },
    "returnCosts": {
        "currencyCode": "EUR",
        "returnShipmentCost": 10.00,
        "returnHandlingCost": 0,
        "exchangeCost": 0,
        "failedDeliveryCost": 0,
        "totalCost": 10.00
    },
    "refundTransactions": [],
    "items": [
        {
            "id": 448715,
            "foreignLineItemId": "3393728",
            "status": "AWAITING_RETURN",
            "purchasePriceAmount": {
                "currencyCode": "EUR",
                "amount": 85.00,
                "itemTax": 13.57
            },
            "productVariant": {
                "id": 28580,
                "foreignProductId": "33",
                "foreignVariantId": "1498-231",
                "productNumber": "10005",
                "properties": [
                    {
                        "type": "Variant",
                        "code": "1001",
                        "value": "Black"
                    },
                    {
                        "type": "Size",
                        "code": "M",
                        "value": "M"
                    }
                ],
                "sku": "51009M",
                "productTitle": "Black Skirt",
                "variantTitle": "Black M"
            },
            "returnReasons": [
                {
                    "id": 363,
                    "subReasonId": 496
                }
            ]
        }
    ],
    "shipments": [
        {
            "id": 227022,
            "type": "C2B",
            "carrier": "DHL_EXPRESS",
            "trackingUrl": "https://express.api.dhl.com/mydhlapi/shipments/2521800172/tracking",
            "trackingReference": "2521800172",
            "customsType": "NO_CUSTOMS"
        }
    ],
    "exchanges": []
}
﻿
﻿
3. Update Items Checked at the WarehouseEndpoint: POST https://api.turnr.se/merchant/items/returned
Update the return status of items after they have been checked at the warehouse. Specify approval status and provide additional comments.
Request Parameters
Headers:
x-api-key (string, required): Your API key.
Body (application/json):
foreignOrderId (string, required): External order ID.
returnId (integer, required): Return ID.
trackingReference (string, optional): Tracking number associated with the return.
items (array, required): List of items being reported.
Each item includes:
sku (string, required): Stock Keeping Unit.
quantity (integer, required): Quantity being returned.
approved (boolean, required): Approval status after inspection.
comment (string, optional): Additional comments.
Example Request
POST https://api.turnr.se/merchant/items/returned HTTP/1.1 
Host: api.turnr.se 
Content-Type: application/json 
x-api-key: YOUR_API_KEY 
﻿
{ 
"foreignOrderId": "23965dbb5e9592ba1c19be0651ee9c5a", 
"returnId": 261868, 
"items": [ 
  { "sku": "100011001M", 
  "quantity": 1, 
  "approved": true, 
  "comment": "Item in perfect condition." }
   ] 
} 
Response Properties
status (string): Operation result, typically "OK" if successful.
Example Response
json
Copy code
{ "status": "OK"}
﻿
}
﻿
Retrieve Exchange Orders InformationTo accurately manage exchange orders for bookkeeping purposes in your store’s ERP system, you can retrieve exchange order details associated with completed returns. This section explains how to fetch exchange order information via the API and integrate it into your accounting processes.
﻿
Endpoint: GET https://api.turnr.se/merchant/return/{returnId}
﻿
Retrieve detailed information about a specific return, including any associated exchange orders. It’s recommended to perform this action after the return has a status of COMPLETED to ensure all return updates are finalized.
Request Parameters
Headers:
x-api-key (string, required): Your API key.
Path Parameters:
returnId (integer, required): Return ID to retrieve.
Example Request
GET https://api.turnr.se/merchant/return/261868 HTTP/1.1 
Host: api.turnr.se 
x-api-key: YOUR_API_KEY
Response Properties, (exchange order specific):
﻿
• id (integer): Return ID.
• createdAt (string, date-time): Return creation timestamp.
• status (string): Current status of the return. Ensure it is COMPLETED before processing.
• statusUrl (string): URL for tracking the return.
• order (object):
• id (integer): Ingrid Returns order ID.
• foreignId (string): External order ID.
• foreignNumber (integer): External order number.
• createdAt (string, date-time): Order creation timestamp.
• exchanges (array): List of exchange orders associated with the return.
﻿
Each exchange order includes:
﻿
• id (integer): Exchange ID.
• foreignDraftOrderId (string): External draft order ID.
• foreignOrderId (string): External order ID for the new exchange order.
• foreignOrderNumber (string): External order number.
• items (array): List of exchange items.
﻿
Each item in items includes:
﻿
• id (integer): Exchange item ID.
• orderItemId (integer): Associated original order item ID.
• fromProductVariant (object): Original product variant being exchanged.
• sku (string): SKU of the original item.
• productTitle (string): Product title of the original item.
• variantTitle (string): Variant title of the original item.
• toProductVariant (object): New product variant the customer wants.
• sku (string): SKU of the new item.
• productTitle (string): Product title of the new item.
• variantTitle (string): Variant title of the new item.
Fields in fromProductVariant and toProductVariant:
﻿
• id (integer): Product variant ID.
• foreignProductId (string): External product ID.
• foreignVariantId (string): External variant ID.
• productNumber (string): Product number.
• properties (array): List of product properties.
• sku (string): Stock Keeping Unit.
• productTitle (string): Product title.
• variantTitle (string): Variant title.
﻿
Example Response
{
  "id": 261868,
  "createdAt": "2024-09-26T19:47:01.273523Z",
  "status": "COMPLETED",
  "statusUrl": "https://returns.turnr.se/merchant/status/124",
  "order": {
    "id": 254843,
    "foreignId": "980ab3e70810976cfd544fa785ebcba3",
    "foreignNumber": 1520547,
    "createdAt": "2024-09-23T15:41:29.346454Z"
  },
  "exchanges": [
    {
      "id": 12345,
      "foreignDraftOrderId": "DRAFT12345",
      "foreignOrderId": "NEWORDER12345",
      "foreignOrderNumber": "1002",
      "items": [
        {
          "id": 67890,
          "orderItemId": 448715,
          "fromProductVariant": {
            "id": 28580,
            "foreignProductId": "33",
            "foreignVariantId": "1498-231",
            "productNumber": "10005",
            "properties": [
              {
                "type": "Color",
                "code": "BLK",
                "value": "Black",
                "imageSrc": "https://example.com/images/black.png",
                "hexColor": "#000000",
                "translations": {
                  "en": "Black",
                  "sv": "Svart"
                },
                "displayPriority": 1
              }
            ],
            "sku": "51009M",
            "productTitle": "Black Skirt",
            "variantTitle": "Black M"
          },
          "toProductVariant": {
            "id": 28581,
            "foreignProductId": "33",
            "foreignVariantId": "1498-232",
            "productNumber": "10006",
            "properties": [
              {
                "type": "Color",
                "code": "BLK",
                "value": "Black",
                "imageSrc": "https://example.com/images/black.png",
                "hexColor": "#000000",
                "translations": {
                  "en": "Black",
                  "sv": "Svart"
                },
                "displayPriority": 1
              }
            ],
            "sku": "51009L",
            "productTitle": "Black Skirt",
            "variantTitle": "Black L"
          }
        }
      ]
    }
  ]
}
Processing Exchange Orders for Bookkeeping
﻿
To handle exchange orders in your ERP system for accurate bookkeeping, follow these steps:
﻿
1. Ensure Return Completion: Verify that the return’s status is COMPLETED before processing exchange orders.
2. Retrieve Return Details: Use the provided endpoint to get detailed information about the return and associated exchanges.
3. Extract Exchange Data: Access the exchanges array from the response to obtain exchange order details.
4. Process Each Exchange Order:
• Identify New Orders: Use foreignOrderId and foreignOrderNumber to create or update orders in your ERP system.
• Record Original and New Items: Log details of both the original items (fromProductVariant) and the new items (toProductVariant) in your accounting records.
• Update Inventory (this is usually done automatically by the ecommerce platform):
• Decrease Stock: Adjust stock levels for the new items being sent out to the customer.
• Increase Stock: If applicable, adjust stock levels for the returned items after they have been inspected and restocked.
• Handle Financial Transactions:
• Price Differences: Account for any differences in price between the original and new items.
• Additional Costs: Include any additional handling or shipping costs associated with the exchange.
• Tax Implications: Ensure that tax calculations are accurate based on the exchanged items.
• Finalize Accounting Entries: Record the exchange transaction in your financial system, ensuring compliance with accounting standards.
5. Update ERP System: Mark the exchange order as processed in your ERP to maintain accurate records.
﻿
Notes
﻿
• Data Accuracy: Processing exchanges after return completion ensures that all data is final and accurate.
• Compliance: Ensure that all bookkeeping entries comply with local accounting regulations and standards.
• Inventory Management: Properly adjust inventory levels to reflect both the returned items and the new items sent to the customer.
• Customer Records: Update customer accounts with the exchange details for transparency and future reference.
﻿
Example Workflow
﻿
1. Receive Return Completion Notification: Optionally, set up webhooks to be notified when a return reaches the COMPLETED status.
2. Fetch Return Details: Use the returnId to retrieve return details, including exchanges.
3. Process Exchange Orders: Follow the steps outlined above to handle the exchange orders in your ERP system.
4. Confirm Processing: Update your records to reflect that the exchange has been processed and accounted for.
﻿
By integrating this process into your bookkeeping practices, you can ensure that exchange orders resulting from returns are accurately reflected in your financial and inventory records.
﻿
﻿
WebhooksWebhooks allow you to receive real-time notifications when key events occur during the return process. Below are the available webhooks, along with example payloads.
Webhook Examples1. RETURN_CREATED
Triggered when a return is created by the customer.
Example Payload:
{
  "type": "RETURN_CREATED",
  "triggeredAt": "2024-09-18T12:00:00Z",
  "returnId": "261868",
  "foreignOrderId": "23965dbb5e9592ba1c19be0651ee9c5a",
  "lineItems": [{ "sku": "100011001M", "quantity": 1 }]
}
3. RETURN_ARRIVED (Post-Inspection)
Triggered after the return has been inspected at the warehouse.
Example Payload:
{
  "type": "RETURN_ARRIVED",
  "triggeredAt": "2024-09-18T16:05:17.034470979Z",
  "returnId": "261868",
  "foreignOrderId": "23965dbb5e9592ba1c19be0651ee9c5a",
  "lineItems": [
    {
      "sku": "100011001M",
      "quantity": 1,
      "returnedToWarehouseAt": "2024-09-18T16:05:16.964408537Z",
      "restockStatus": "NO_RESTOCK",
      "approvedForRestock": true
    }
  ]
}
4. RETURN_COMPLETED
Triggered when the return process is fully completed.
Example Payload:
{
  "type": "RETURN_COMPLETED",
  "triggeredAt": "2024-09-18T16:10:42.888799023Z",
  "returnId": "261868",
  "foreignOrderId": "23965dbb5e9592ba1c19be0651ee9c5a",
  "lineItems": [
    {
      "sku": "100011001M",
      "quantity": 1,
      "returnedToWarehouseAt": "2024-09-18T16:05:16.964408537Z",
      "refundStatus": "REFUNDED",
      "approvedForRestock": true
    }
  ]
}
﻿
﻿
Best Practices for Webhooks and API CallsWebhook-Driven Approach.1Receive Webhook: When a webhook is received (e.g., RETURN_CREATED), extract the returnId from the payload.
.2Fetch Detailed Information: Use the returnId to call GET https://api.turnr.se/merchant/return/{returnId} for comprehensive details.
.3Process Data: Update your system with the latest return information.
Benefits:
Real-time updates: Immediate notification of return events.
Efficiency: Reduces unnecessary API calls.
Security Considerations:
Validate Webhooks: Ensure webhook authenticity by validating signatures.
Use HTTPS: Always secure your webhook endpoints.
Polling ApproachIf webhooks cannot be used, implement a polling mechanism:
.1Schedule API Calls: Regularly call GET https://api.turnr.se/merchant/return to check for new or updated returns.
.2Use Filters: Apply afterId or afterDate parameters to retrieve only recent data.
Drawbacks:
Latency: Updates are not real-time.
Increased Load: More frequent API calls.
﻿
Status ExplanationsReturn StatusesPENDING: Return created, awaiting processing.
AWAITING_RETURN: Return created, awaiting handling.
AWAITING_REFUND: Return approved, refund is pending.
COMPLETED: Return process is finalized.
CANCELLED: Return was cancelled.
QUALITY_CHECK: Items are undergoing quality inspection.
COMPLAINT_CHECK: Additional check due to a complaint.
Item StatusesNEW: Item returned, awaiting processing.
AWAITING_RETURN: Return created, awaiting consumer to hand in the package to carrier.
IN_TRANSIT: Items are in transit back to the warehouse.
AWAITING_MANUAL_CHECK: Awaiting manual inspection.
ARRIVED_AT_WAREHOUSE: Item have arrived and are awaiting inspection.
QUALITY_CHECK: Undergoing quality inspection.
RETURNED: Successfully returned and processed.
LOST_IN_TRANSIT: Item lost during shipment. If all items are marked in this state, the refund process will proceed as normal.
CANCELLED: Return request cancelled.
NO_RETURN_NEEDED: The customer keeps the item, no return shipment is booked. If all items are marked in this state, the refund process will proceed as normal.
Refund StatusesEXCHANGE_NO_REFUND: Item exchanged, no refund issued.
PENDING: Refund is pending.
REFUNDED: Refund has been issued.
HANDLED_EXTERNALLY: Processed outside of Ingrid Returns.
Refund TypesGIFT_CARD: Refund issued as store credit.
BASIC: Standard refund to original payment method.
﻿
Additional ResourcesAPI Reference:  Ingrid Returns API Reference ﻿
﻿
﻿
Ingrid Returns - Developer Integration Guide

﻿

Overview

How a Return Works

Overview of the Return Process

Return workflow summary

Authentication

API Endpoints

1. Retrieve a List of Returns

2. Retrieve a Specific Return

3. Update Items Checked at the Warehouse

Retrieve Exchange Orders Information

Webhooks

Webhook Examples

Best Practices for Webhooks and API Calls

Webhook-Driven Approach

Polling Approach

Status Explanations

Return Statuses

Item Statuses

Refund Statuses

Refund Types

Additional Resources
