Skip to main content

Magento configuration guide

The Magento Integration connects your Magento 2 store to Ingrid Returns, automating the full return lifecycle — from order lookup to refund and exchange creation.

I
Written by Iuliia Prylypko

What is it?

The Magento Integration connects your Magento 2 store to Ingrid Returns, automating the full return lifecycle — from order lookup to refund and exchange creation. No Magento plugins or webhooks are required; the integration connects via Magento's standard REST API.

It handles:

  1. Order retrieval — fetches order details from Magento when a customer initiates a return

  2. Refund creation — creates credit memos against paid invoices for automated refunds

  3. Exchange order creation — places new Magento orders for exchanges, with payment set to free

  4. Product data sync — fetches product information, including configurable/simple variant pairing

  5. Inventory check — verifies stock availability by SKU

  6. Customs data — reads HS code and country of manufacture from Magento product attributes for cross-border returns

Supported Magento version: Magento 2 (REST API v1)

Key benefits

  • Automated refunds — when a return is processed, a Magento credit memo is created automatically, without manual intervention

  • Automated exchanges — exchange orders are placed directly in Magento with the original shipping method preserved

  • Eligibility enforcement — only orders in the correct status are accepted for returns, reducing invalid requests

  • Cross-border ready — HS codes and country-of-manufacture data flow from Magento product attributes to carrier customs declarations automatically

  • Simple onboarding — no Magento plugins or webhooks required

Use Cases

1. Standard return with automated refund

A customer returns a product to your warehouse. Once the warehouse confirms receipt, Ingrid automatically creates a credit memo in Magento. Your payment provider (Klarna, Adyen, Stripe, etc.) processes the actual refund based on your store's payment configuration.

Result: Refund issued within minutes of warehouse receipt, zero manual steps in Magento Admin.

2. Exchange — different size or variant

A customer wants to exchange size M for size L. Ingrid creates a new Magento order with the replacement item, using the original shipping method. The exchange order is created with no additional charge, so your fulfilment team sees a standard order with no special handling required.

Result: Size exchange fully automated — no manual order creation needed.

3. Cross-border return with customs data

You ship from Sweden to Norway. Your carrier requires HS codes and country of manufacture on all return labels. The integration reads these values from your Magento product attributes and includes them automatically in the carrier customs declaration.

Result: Parcels clear customs without manual data entry or delays.

4. Returns during order processing

Your fulfilment pipeline doesn't always reach "complete" status before the return window opens. With the right configuration, customers can initiate returns on orders still in "processing" status.

Configuration Guide

What you need before setup

  1. Magento Admin access to create an integration user

  2. API resource permissions for: Orders, Products, Configurable Products, Inventory Source Items, Credit Memos, Categories

  3. OAuth credentials — generated when you activate the integration in Magento

  4. Single invoice per order — your Magento store must create exactly one invoice per order

  5. HS code and country of manufacture attribute codes (if cross-border shipping is in scope)

Step-by-step setup

In Magento Admin:

  1. Go to System → Integrations → Add New Integration

  2. Name it (e.g. "Ingrid Returns") and assign API resource access for the required scopes

  3. Activate the integration and copy all four OAuth credential values:

    • Consumer Key

    • Consumer Secret

    • Access Token

    • Access Token Secret

In Returns Back-office:

  1. Open the target shop and navigate to the Ecom settings tab

  2. Select Magento as the e-commerce platform

  3. Paste the API URL (your store's base domain, no trailing slash) and all four OAuth fields

  4. If your store sells cross-border and carriers require customs data: enter the Magento attribute codes for HS code and country of manufacture

    • To find the correct codes, go to Magento Admin → Catalog → Attributes → Attribute Code

  5. Save and verify by fetching a known test order

Configuration options

Setting

Description

Default

apiUrl

Your Magento store base URL (e.g. https://store.example.com)

Required

consumerKey

OAuth Consumer Key from Magento integration

Required

consumerSecret

OAuth Consumer Secret

Required

accessToken

OAuth Access Token

Required

accessTokenSecret

OAuth Access Token Secret

Required

allowReturnsDuringProcessing

Accept returns on orders in "processing" status (not just "complete")

false

hsCodeCustomAttributeKey

Magento attribute code for HS/tariff classification number

Optional

countryOfManufactureCustomAttributeKey

Magento attribute code for country of manufacture (ISO two-letter code)

Optional

Frequently Asked Questions

Q: Does this work with Magento 1?
A: No. The integration targets Magento 2 REST API v1 endpoints. Magento 1 uses a different API architecture and is not compatible.

Q: Can I connect multiple Magento stores?
A: Yes. Each Ingrid shop maps to one integration. For multiple Magento storefronts, configure separate shops in Ingrid, each with their own credentials.

Q: What happens if Magento is temporarily unreachable?
A: The system will retry the operation on its next scheduled cycle. Customers may see a temporary error when initiating a return.

Q: Can the integration handle partial refunds?
A: Yes. Partial line-item refunds (e.g. refunding 1 of 2 units) are supported as long as the order has a single invoice.

Q: Do OAuth tokens expire?
A: Magento OAuth integration tokens do not expire by default. However, if you re-generate or deactivate the integration in Magento Admin, all four OAuth fields must be updated in Returns Back-office simultaneously.

Q: What about exchange price differences?
A: Exchange orders are created as pre-paid. Any price difference (e.g. the customer selects a higher-value variant) is not collected through this integration and must be managed separately.

Q: Does the integration restock returned items in Magento?
A: No. Inventory restocking is not handled by this integration. To restock automatically, configure your warehouse management system to update Magento inventory upon receipt.

Related documentation

Did this answer your question?

Related Articles