Collect Your Trading Partner's Specs (Implementation Guide)

Every retailer sends you an EDI Implementation Guide (IG) — a PDF specifying exactly which segments, qualifiers, and codes they require. Never skip this. Even if you know X12 850 cold, Target's IG is different from Walmart's, which is different from Costco's.

Key items to extract from the IG before touching any code:

• Required vs. optional segments and elements
• Their ISA/GS qualifier codes (your sender ID)
• Product identifier qualifiers (VN = vendor item, BP = buyer's part number, etc.)
• Date format requirements (YYYYMMDD vs YYMMDD)
• Quantity/UOM codes they accept (EA, CA, DZ, etc.)
• Required acknowledgment SLA (usually 855 within 24 hours of receiving an 850)

Choose Your Integration Architecture

There are three viable approaches for connecting EDI to Shopify. Each has a real tradeoff:

Set Up File Transport (AS2, SFTP, or API)

EDI files need a secure transport mechanism. AS2 (Applicability Statement 2) is the industry standard for direct connections and is required by most large retailers. SFTP is common for smaller partners or internal tools.

{
  "as2Id": "YOURCOMPANY",
  "partnerId": "RETAILER",
  "url": "https://as2.retailer.com:4080/as2",
  "encryption": "AES-256-CBC",
  "signing": "SHA-256",
  "mdn": {
    "type": "sync",          // request synchronous MDN
    "signed": true
  },
  "certificates": {
    "your_private": "./certs/yourcompany.p12",
    "partner_public": "./certs/retailer.cer"
  }
}

Certificate exchange happens out-of-band — you'll email your public certificate to your partner's EDI team and receive theirs. Budget a full week for this process with large retailers due to their security review cycles.

Parse the EDI Document and Map Fields to Shopify

This is where the real engineering work happens. You need to extract every relevant field from the 850/ORDERS and map it to the Shopify Orders API. Here's a complete field mapping:

import { X12Parser } from 'node-x12';

async function edi850ToShopifyOrder(rawEdiString) {
  const parser = new X12Parser(true);
  const interchange = parser.parse(rawEdiString);
  const group = interchange.functionalGroups[0];
  const transaction = group.transactions[0]; // 850

  // Extract PO number from BEG segment, element 03
  const poNumber = transaction.get('BEG03');

  // Extract ship-to address from N1/N3/N4 loop
  const n1Loop = transaction.getLoop('N1', 'ST');
  const shippingAddress = {
    address1: n1Loop.get('N301'),
    address2: n1Loop.get('N302') || '',
    city:     n1Loop.get('N401'),
    province: n1Loop.get('N402'),
    zip:      n1Loop.get('N403'),
    country:  n1Loop.get('N404'),
  };

  // Extract line items from PO1 loops
  const lineItems = transaction.getLoops('PO1').map(po1 => ({
    sku:      po1.get('PO107'),         // VN qualifier = vendor SKU
    quantity: parseInt(po1.get('PO102')),
    price:    parseFloat(po1.get('PO104')),
    title:    po1.get('PID05') || '',   // from PID segment in loop
  }));

  // Resolve Shopify variant IDs from SKUs
  const resolvedItems = await Promise.all(
    lineItems.map(async item => {
      const variantId = await lookupVariantBySku(item.sku);
      if (!variantId) throw new Error(`SKU not found: ${item.sku}`);
      return { variant_id: variantId, quantity: item.quantity, price: item.price };
    })
  );

  return {
    order: {
      line_items: resolvedItems,
      shipping_address: shippingAddress,
      tags: [`edi-po:${poNumber}`, 'edi-order'],
      note_attributes: [
        { name: 'edi_po_number', value: poNumber },
        { name: 'edi_source', value: 'X12-850' },
      ],
      financial_status: 'pending',
    }
  };
}

Post the Order to Shopify via Admin API

With your mapped payload ready, post it to Shopify's Admin REST or GraphQL API. For B2B orders, use the send_receipt: false flag to suppress the customer-facing confirmation email (your trading partner expects EDI acknowledgments, not email).

const response = await fetch(
  `https://${SHOP}.myshopify.com/admin/api/2024-04/orders.json`,
  {
    method: 'POST',
    headers: {
      'X-Shopify-Access-Token': ACCESS_TOKEN,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      ...shopifyOrderPayload,
      send_receipt: false,      // suppress email to partner
      send_fulfillment_receipt: false,
      inventory_behaviour: 'decrement_obeying_policy',
    }),
  }
);

if (!response.ok) {
  const error = await response.json();
  // Log full error — Shopify returns field-level validation errors
  throw new Error(`Shopify order creation failed: ${JSON.stringify(error)}`);
}

const { order } = await response.json();
// Store order.id → poNumber mapping in your database for 855/856 generation
await savePoMapping({ shopifyOrderId: order.id, poNumber, partnerId });

Send the 855 / ORDRSP Acknowledgment

Most trading partners require an 855 Purchase Order Acknowledgment within 24–48 hours. This document tells the retailer you received their PO and whether you accept it in full, partially, or reject it. Missing the SLA on this is a chargeback risk.

ISA*00*          *00*          *ZZ*YOURCOMPANY    *ZZ*RETAILER       *260501*1000*^*00501*000000002*0*P*:
GS*PR*YOURCOMPANY*RETAILER*20260501*1000*2*X*005010
ST*855*0001
BAK*00*AC*PO-98765*20260501  ~ AC = Accepted, references original PO#
PO1*1*24*EA*29.99*VN*SKU-ABC123
ACK*IA*24*EA*202*20260515     ~ IA = Item Accepted
PO1*2*12*EA*49.99*VN*SKU-DEF456
ACK*IA*12*EA*202*20260515
CTT*2
SE*9*0001
GE*1*2
IEA*1*000000002

The BAK02 element is your acceptance code. AC = fully accepted. AD = accepted with changes. RJ = rejected. If you change quantities or dates, you must use AD and document exactly what changed on each PO1 line.

Automate the 856 ASN on Fulfillment

When Shopify marks an order as fulfilled (via webhook orders/fulfilled), your integration must immediately generate and transmit an 856 Advance Ship Notice. The ASN must include tracking numbers, carrier codes, and exact carton-level detail for many retailers. This document is time-sensitive — many partners require ASN receipt before the physical shipment arrives.

// Register webhook in Shopify
POST /admin/api/2024-04/webhooks.json
{
  "topic": "orders/fulfilled",
  "address": "https://your-integration.com/webhooks/fulfillment",
  "format": "json"
}

// In your webhook handler:
async function handleFulfillment(shopifyOrder, fulfillment) {
  const poMapping = await getPoMapping(shopifyOrder.id);

  const asnData = {
    shipmentId:  `ASN-${Date.now()}`,
    poNumber:    poMapping.poNumber,
    shipDate:    fulfillment.created_at,
    carrier:     mapCarrierCode(fulfillment.tracking_company),
    trackingNum: fulfillment.tracking_number,
    lines:       fulfillment.line_items.map(li => ({
      sku: li.sku, quantity: li.quantity,
    })),
  };

  const edi856 = generate856(asnData, poMapping.partnerId);
  await transmitViaAS2(edi856, poMapping.partnerId);
}

Set Up Monitoring, Alerting, and Reconciliation

EDI integrations fail silently in ways that cost real money. A malformed 850 that never creates a Shopify order is invisible unless you're actively monitoring. At minimum you need:

• Transaction logging with full raw document storage (7-year retention for most retail partners)
• Dead-letter queue for failed parsing with Slack/PagerDuty alert
• Daily reconciliation job: compare EDI PO count vs Shopify orders created in same window
• MDN (Message Disposition Notification) parsing to confirm AS2 delivery
• ISA control number sequence monitoring (gaps indicate missing files)