# Shopify Wholesale EDI Setup Guide — Connect Walmart, Target, Amazon, Costco & Home Depot

> **Official Supplier Onboarding Guide • ANSI X12 4010 & 5010**
> For merchants, logistics coordinators, and autonomous AI agents.
> Production Service: `https://www.ediengineapp.com`

---

## 1. Overview & Data Flow Architecture

When wholesale retailers issue purchase orders, they transmit an **ANSI X12 850 (Purchase Order)** over AS2 or SFTP. In response, they mandate an **ANSI X12 856 (Advance Ship Notice / ASN)** upon warehouse dispatch, and an **ANSI X12 810 (Commercial Invoice)** for accounts payable settlement.

### Architecture Flow:
1. **Inbound 850 (Purchase Order):**
   Retailer (Walmart/Target) ──[850 PO]──▶ **EDI Engine** ──[Shopify Order API]──▶ **Your Shopify Store**
2. **Outbound 856 (Advance Ship Notice):**
   Your Warehouse Fulfills ──[Webhook]──▶ **EDI Engine** ──[856 ASN Stream]────▶ **Retailer DC**
3. **Outbound 810 (Commercial Invoice):**
   Accounts Payable Settles ◀──[810 Invoice Stream]── **EDI Engine** ◀──[Order Paid]

### Why Shopify Native?
Orders appear directly in your Shopify Admin (`admin.shopify.com/orders`) tagged by retailer (`Walmart`, `Target`, `Costco`) with the buyer's distribution center shipping address, Net 30 wholesale line item pricing, and original PO numbers. Existing 3PL warehouse apps (ShipBob, Deliverr, Whiplash, Flexport) fulfill them without custom software.

---

## 2. Prerequisites

1. **Active Shopify Store:** A store domain such as `your-brand.myshopify.com`.
2. **Retailer Supplier Agreement:** The onboarding packet from your retail buyer containing your **Vendor Number / Supplier Code** (e.g., `VN-88231`).
3. **Primary Shipping Carrier:** Standard SCAC code for your freight or parcel carrier (`UPSN` for UPS, `FDEG` for FedEx, `RDWY` for R+L Carriers, `ODFL` for Old Dominion).

---

## 3. Step 1: Link Your Shopify Store

EDI Engine requests standard Shopify Partner API scopes:
* `write_orders`: Ingests wholesale purchase orders with wholesale pricing and DC addresses.
* `read_fulfillments`: Detects tracking numbers and SCAC codes to generate outbound 856 ASNs.
* `write_draft_orders`: Holds un-onboarded vendor POs in native Shopify Quarantine for authorization.

---

## 4. Step 2: Supported Retail Channels

All connected retailers route orders concurrently into your Shopify store without collision:

| Retailer | Format Standard | Retailer ISA ID | Compliance & Routing Rules |
| :--- | :--- | :--- | :--- |
| **Walmart US** | ANSI X12 4010 | `01:007934420` | Requires 4-char DC numeric code in N1*ST. Strict SCAC format. |
| **Target Stores** | Target POL Guide | `08:6111470100` | DPCI barcode mapping and T-prefix distribution center codes. |
| **Amazon Vendor Central** | Amazon VC Spec | `ZZ:AMAZON` | ASIN/UPC validation and Amazon FC codes (e.g. ONT8, BWI2). |
| **The Home Depot** | THD Supplier Hub | `01:006922880` | Department numbers and Rapid Deployment Center (RDC) routing. |
| **Costco Wholesale** | ANSI X12 4010 | `ZZ:COSTCO` | Pallet cross-dock carton counts and Depot # identifier. |
| **Custom Partner** | ANSI X12 4010/5010 | `ZZ:CUSTOM` | Regional distributors and boutique department stores. |

---

## 5. Step 3: Vendor Number & Carrier Rules

Enter your assigned **Vendor Number** (found on page 1 of your supplier agreement) and choose your primary carrier SCAC. Click **Save**. Settings are persisted in local and server storage.

---

## 6. Step 4: Test & Verify Connection (1-Click Action)

Click **Send Test Order to Shopify →**. In one single action, the engine:
1. Audits the inbound 850 stream against the retailer's formatting rules.
2. Verifies line item UPC mapping, quantities, and Net 30 wholesale pricing.
3. Creates a real test order in your Shopify store (e.g. `#WALMART-WMT-987654321`).
4. Generates the sample 850, 856 ASN, and 810 Invoice files for your Retailer Certification Kit.

Click **Open in Shopify Admin ↗** to review the created order directly in your store.

---

## 7. Retailer Portal Sign-Off & Cutover (User Sign-Off)

Major retail corporations (Walmart, Costco, Target, Amazon) require their own EDI analyst or automated test portal to approve sample files before activating live purchase order routing:
1. **Download the 3 Certification Files:** Download the generated `.edi` files (850 PO, 856 ASN, and 810 Invoice).
2. **Upload to Retailer Testing Sandbox:** Submit the files into Walmart Retail Link, Costco Vendor Portal, or email them to your assigned EDI coordinator.
3. **Mark Live Production:** Once the retailer confirms sign-off, click **Mark Retailer Live in Production**. The channel changes from `● Store Verified` to `● Live Production`.

---

## 8. Enterprise Security Quarantine (Shopify Native Draft Orders)

If an inbound purchase order arrives from an un-onboarded trading partner or unrecognized ISA Sender ID:
* The order is held in Quarantine and created directly in your native **Shopify Draft Orders** list (`admin.shopify.com/store/YOUR-STORE/draft_orders`) tagged `EDI-Quarantine`.
* Store owners receive native Shopify push notifications on desktop and mobile.
* Clicking **"Create order"** inside Shopify automatically authorizes the partner and onboards them into your active channel roster.

---

## 9. Chargeback Prevention & Pre-Flight Validation

* **Walmart Retail Link Penalties:** \$250/PO for missing SCAC or invalid PRO tracking format; \$5.00/carton for unmapped UPCs.
* **Target Routing Fines:** 5% deduction of invoice value for ASN transmitted after shipment arrives at DC.
* **EDI Engine Chargeback Guard:** Intercepts every outbound 856 ASN before transmission, verifying SCAC length, tracking checksums, and ship-to codes, ensuring **zero chargebacks**.

---

## 10. Autonomous AI Agent Setup (AEO & Sidekick API)

Autonomous assistants (Shopify Sidekick, ChatGPT Actions, Claude MCP, Gemini Agents, Cursor, Devin) can autonomously configure, test, and manage retail connections without human UI clicks.

### Single-Call Autonomous Setup Endpoint:
```bash
curl -X POST https://www.ediengineapp.com/api/v1/agent/setup \
  -H "Content-Type: application/json" \
  -d '{
    "shop_domain": "your-brand.myshopify.com",
    "retailer": "Walmart",
    "vendor_number": "VN-88231",
    "carrier_scac": "UPSN",
    "auto_test": true
  }'
```

### Tool Manifest for AI Agent Discovery:
Point your agent harness or MCP server to `https://www.ediengineapp.com/.well-known/agent-manifest.json` to discover all tool schemas:
* `get_retailer_catalog`: List supported wholesale partners and specs.
* `configure_retailer`: Onboard retailer with vendor ID and carrier SCAC.
* `send_test_order`: Ingest compliant test purchase order into Shopify.
* `get_certification_kit`: Retrieve 850/856/810 files for retailer vendor portal.
* `promote_to_live`: Switch retailer to Live Production.
* `check_compliance_health`: Audit all channels for chargeback risks.

---

## 11. Frequently Asked Questions

### Do I need to sign a multi-year contract or pay per-character VAN fees?
No. Unlike legacy VAN brokers (SPS Commerce, TrueCommerce) that require 12-36 month consulting contracts and bill per-kilo-character fees, EDI Engine operates directly against Shopify's Admin API with zero long-term lock-in and no per-character surcharges.

### How does my 3PL warehouse fulfill wholesale orders?
Wholesale purchase orders appear directly in your normal Shopify Orders list tagged by retailer (e.g. Walmart, Target) with wholesale line items and the retailer distribution center address. Existing 3PL warehouse apps (ShipBob, Deliverr, Whiplash, Flexport) process them like normal orders. When they add tracking, EDI Engine automatically generates the 856 ASN.

### How long does retailer testing and portal sign-off take?
Typically 2 to 5 business days. Once you download the 3-file certification packet (850, 856, 810) and upload it to the retailer vendor portal, their EDI team validates formatting and approves you for live production.

### Can I connect multiple retail partners at the same time?
Yes. Walmart, Target, Amazon, Costco, Home Depot, and custom regional wholesalers all route into your Shopify store concurrently, each tagged cleanly with the retailer's purchase order number.

### What happens if a retailer transmits an unmapped SKU or UPC?
The order is safely intercepted into Shopify Draft Orders tagged EDI-Quarantine with an actionable notification so your warehouse never ships incorrect products or incurs retailer chargeback fines.

### Can I add custom boutique distributors or regional wholesalers?
Yes. In Step 2, click **+ Add Retailer** and switch to the **Custom Partner** tab. Enter their name, ISA Sender ID, and DC code. The bridge will automatically generate ANSI X12 4010 or 5010 ingestion.