---
title: "Magento configuration guide"
canonical: "https://ingrid-support.refined.site/space/KB/411697153/Magento%20configuration%20guide"
format: markdown
---
## 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:**

4. Open the target shop and navigate to the `Ecom` settings tab
5. Select **Magento** as the e-commerce platform
6. Paste the API URL (your store's base domain, no trailing slash) and all four OAuth fields
7. 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`
8. 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 |

![image](media://012e40b2-8321-476f-94dc-2725b569169f)

---

## 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

- [E-commerce Platform Integration](https://ingrid-ab.atlassian.net/wiki/spaces/KB/pages/403111937) — overview of all supported platforms
- [Returns Flow](https://ingrid-ab.atlassian.net/wiki/spaces/KB/pages/421658625) — how the full return process works
- [Exchange Flow](https://ingrid-ab.atlassian.net/wiki/spaces/KB/pages/423493635) — how exchanges are processed
- Developer documentation: [developer.ingrid.com/returns/integration/](https://developer.ingrid.com/returns/integration/)