Skip to main content

N1 Loop in EDI — Party Identification, Address Segments, and Common Errors

How does the N1 loop work in X12 EDI, and what are the common qualifier codes, address segments, and mapping errors?

A
Written by Ashwath Kirthyvasan
Updated over 3 weeks ago

Audience: EDI developers, B2B integration teams, Web EDI users

The N1 loop is the standard way X12 EDI transactions identify parties — who's shipping, who's receiving, who's billing. It appears in nearly every transaction type and is one of the most common sources of validation failures and trading partner rejections. Understanding how the N1 loop works, which qualifiers mean what, and how to diagnose errors will save significant troubleshooting time across your entire EDI integration.

What the N1 Loop Is

The N1 loop groups segments that together identify a party, their address, and contact details. N1 is the first and only mandatory segment in the loop — all others are optional and partner-specific.

  • N1 — Party identification: qualifier, name, and ID code (mandatory)

  • N2 — Additional name; used when the party name exceeds 60 characters or to carry a DBA/trade name

  • N3 — Street address; up to two iterations for address line 1 and 2

  • N4 — City, state, ZIP/postal code, and country

  • REF — Additional location identifiers such as GLN, DUNS+4, or tax ID

  • PER — Contact information: name, phone, and email

When the N1 loop contains only the N1 segment with no N3/N4, it means either a physical address isn't required for that party, or both partners have agreed to identify the location through a qualifier and ID in N103/N104 — for example, a GLN that the receiving system can look up internally.

A minimal N1 loop identified by GLN only:

N1*ST**9*0614141000005

A complete N1 loop with name and address:

N1*ST*ACME DISTRIBUTION CENTER*91*DEST-001
N3*1234 WAREHOUSE BLVD
N4*CHICAGO*IL*60601*US

An extended example with REF and PER:

N1*BY*BUYER COMPANY NAME*9*0614141000005
N3*500 MAIN STREET
N4*NEW YORK*NY*10001*US
REF*YB*BUYER-VENDOR-NUMBER
PER*BD*JOHN SMITH*TE*5551234567

N1 Segment Structure

The N1 segment is what defines the type of party the loop represents. N101 (Entity Identifier Code) is the qualifier that tells you — and your trading partner — what role this party plays in the transaction: ship-to, bill-to, buyer, shipper, and so on. The qualifier drives everything else: which fields are expected, whether a physical address is required, and how the receiving system matches the party to their records.

Common N101 Entity Qualifier Codes

N101 tells you which type of N1 loop you're looking at. Always refer to your trading partner's implementation guidelines — using the wrong qualifier is one of the most common causes of partner-side matching failures.

Code

Meaning

Common Transaction Types

ST

Ship-to

850, 856, 940, 945

SF

Ship-from

856, 214

BT

Bill-to

810, 850

BY

Buying party (buyer)

850

BS

Bill-to and ship-to (combined)

850, 810

SH

Shipper

204, 214

CN

Consignee

204, 214

PR

Payer

820

PE

Payee

820

Where Errors Come From

N1 loop issues surface in three different ways, and diagnosing which one you have determines how you fix it:

  • Orderful validation (transaction status: Invalid) — Orderful caught a mismatch against the trading partner's configured guideline before the transaction was delivered. Open the transaction and go to the Rules Editor tab to see the exact error path and message. If the fix is a rule in Orderful, it applies automatically — no resend needed. If the fix requires updating your source system or integration, resend after making the change.

  • 997 functional acknowledgment (acknowledgment status: Rejected) — The transaction was delivered to the partner but they rejected it via 997. Open the 997 in Orderful and check the AK3/AK4 segments for the segment ID and element position flagged. Fix the issue and resend.

  • Partner outreach (email, 824, or 864) — The transaction shows as Valid and Accepted in Orderful, because Orderful had no way to catch the error. The partner is reporting it separately. Identify the field from their description, apply the fix, and resend.

Note on guideline updates: If Orderful is flagging a validation error but your trading partner confirms in writing they don't require that field, segment, or qualifier — the guideline can be updated so Orderful stops enforcing it. This applies to any of the errors below. See How to Request Guideline Changes When Your Trading Partner Controls Field Requirements for the process.

Common Errors and How to Fix Them

Wrong N1 qualifier for an existing loop

What's happening: The N1 loop exists with address data, but N101 doesn't match what the trading partner's guideline expects. Your source system or integration is sending a qualifier that doesn't align with the configured relationship.

How this surfaces:

  • Orderful validation: Transaction status is Invalid. The Rules Editor shows something like:

    Path: transactionSets.0.N1_loop.0.partyIdentification.0.entityIdentifierCode
Error: BT is not a valid input.
Allowed values:
  BY    Buying party
  SF    Ship From
  ST    Ship To

  • 997 rejection: The partner rejected the transaction. In Orderful, open the 997 and check the AK3/AK4 segments. AK3 identifies the segment with the problem, AK4 identifies the element. For example:

    AK3*N1*5**8~
AK4*1**7*BT~

    This means: segment N1, element 1 (N101), error code 7 (invalid code value), received value BT.

  • Partner outreach: Transaction shows Valid and Accepted in Orderful but the partner emails or sends a text-based EDI response describing the issue in plain text, for example: "N1 qualifier BT not recognized — expected BY for buyer identification."

How to fix it:

  • If the qualifier is close but wrong (e.g., sending BT when the partner expects BY) — use a REPLACE rule on the entityIdentifierCode field:

    REPLACE($transactionSets.*.N1_loop.*.partyIdentification.*.entityIdentifierCode, "BT", "BY")

  • If the partner doesn't need this N1 loop at all — use a conditional DELETE rule targeting the specific qualifier so only that loop is removed. For example, to delete only the BT loop:

    IF(INCLUDES($transactionSets.*.N1_loop.*.partyIdentification.*.entityIdentifierCode, "BT"), DELETE())

    Without the condition, the DELETE rule would remove all N1 loops.

If caught by Orderful (status: Invalid), the rule applies automatically — no resend needed. If the partner reported it, resend after applying the fix.

Missing N1 loop entirely

What's happening: A required N1 loop is absent from the transaction. This can mean no N1 loops are present at all, or that other N1 loops exist but a specific qualifier is missing.

How this surfaces:

  • Orderful validation: Transaction status is Invalid. If no N1 loops are present at all, the Rules Editor shows something like:

    Path: transactionSets.0.N1_loop
Error: Loop is mandatory

    If other N1 loops are present but a specific qualifier is missing, the error is more specific:

    For each group of possible element 'entityIdentifierCode' values [SF], [ST],
there must be at least one matching loop. Unused code groups: [SF]

    This means an N1*ST loop was found but no N1*SF loop — the ship-from party is absent.

  • Partner outreach: Partner reports a missing bill-to, ship-to, or other required party during testing or via 997.

How to fix it — depends on whether the address is static or dynamic:

  • If the address is always the same (e.g., your AP address on every 810 invoice) — use Add {} To Array in the Rules Editor to add the N1 loop and hard-code the values with SET rules. Example for a bill-to address:

    SET("BT")                          → entityIdentifierCode
SET("ACME CORP ACCOUNTS PAYABLE")  → name
SET("123 BILLING STREET")          → addressInformation (N3)
SET("NEW YORK")                    → cityName (N4)
SET("NY")                          → stateOrProvinceCode (N4)
SET("10001")                       → postalCode (N4)

    No resend needed if caught by Orderful — the rule applies automatically.

  • If the address changes per transaction (e.g., ship-to varies by order) — update your ERP or connector to include the party data when creating transactions, then map it to the correct N1 loop fields. Resend after the fix.

N1 loop at the wrong hierarchy level

What's happening: In transactions like the 856 ASN, the N1 loop can appear at multiple HL levels — the shipment level (applying to the whole document) or the order level (inside an HL loop, applying to a specific PO). Placing an N1 loop at the order level when it should be at the shipment level, or vice versa, causes the wrong address to apply to the wrong portion of the transaction.

For example, in a cross-dock 856, an N1*ST (ship-to) may be required at the shipment level to identify the final destination, but your integration is only sending it at the order level — leaving the shipment-level party blank.

How this surfaces:

  • Orderful validation: Transaction status is Invalid. The error appears scoped to the HL order-level path, not at the transaction root — indicating the N1 loop is missing at that specific level:

    Path: transactionSets.0.HL_loop.1.N1_loop
Error: Loop is mandatory

  • Partner outreach: Partner reports during testing that all lines show the same ship-to when different destinations were expected, or that a required address is missing at a specific level. The transaction may show Valid in Orderful.

  • 997 rejection: Partner rejects with a reference to an unexpected or missing segment position.

How to fix it:

  1. Check your trading partner's guidelines for where they expect each N1 qualifier — shipment level, order level, or item level

  2. The HL index in the validation error path (e.g., HL_loop.1) tells you which specific loop is missing the N1. Open the transaction in Orderful and use the search bar in the Rules Editor to inspect the HL structure and confirm which level is missing the N1 loop

  3. If the N1 data is already present at another HL level — use Add {} To Array under the HL level that is missing the N1 loop, then write a LOOKUPV2 rule for each N1 field that retrieves the value from the level where it exists. The third argument of the inner LOOKUPV2 is the path where the rule is written. For example, to populate the order-level N1 loop by looking up from the shipment level (S):

    entityIdentifierCode:
IF(EQUALS(LOOKUPV2($transactionSets.*.HL_loop, "S", $transactionSets.*.HL_loop.*.hierarchicalLevel.*.hierarchicalLevelCode, $transactionSets.*.HL_loop.*.N1_loop.*.partyIdentification.*.entityIdentifierCode), "ST"),
LOOKUPV2($transactionSets.*.HL_loop, "S", $transactionSets.*.HL_loop.*.hierarchicalLevel.*.hierarchicalLevelCode, $transactionSets.*.HL_loop.*.N1_loop.*.partyIdentification.*.entityIdentifierCode))name:
IF(EQUALS(LOOKUPV2($transactionSets.*.HL_loop, "S", $transactionSets.*.HL_loop.*.hierarchicalLevel.*.hierarchicalLevelCode, $transactionSets.*.HL_loop.*.N1_loop.*.partyIdentification.*.entityIdentifierCode), "ST"),
LOOKUPV2($transactionSets.*.HL_loop, "S", $transactionSets.*.HL_loop.*.hierarchicalLevel.*.hierarchicalLevelCode, $transactionSets.*.HL_loop.*.N1_loop.*.partyIdentification.*.name))

    Repeat the same LOOKUPV2 pattern for each field in the N1 loop that needs to be populated (N3 address, N4 city/state/ZIP, etc.).

  4. If the address isn't in the transaction at all — update your source system or integration to include it at the correct level and resend.

Missing N3 or N4 — address incomplete

What's happening: The N1 segment is present but N3 and N4 are either absent from the payload or not enabled for that qualifier in the trading partner's guideline.

How this surfaces:

  • Orderful validation: Transaction status is Invalid. The Rules Editor shows something like:

    Path: transactionSets.0.N1_loop.0.partyAddress.0.addressInformation
Error: Segment is mandatory

  • Partner outreach: Partner reports receiving the party name or ID but no physical address.

How to fix it:

  1. Verify your source data includes complete address information for the party

  2. Check that your mapping outputs N3 and N4 following the N1 for parties that require a physical address

  3. If the address data is always the same for that party — use Add {} To Array in the Rules Editor to add N3 and N4 as hard-coded segments under the N1 loop using SET rules. No resend needed if caught by Orderful — the rule applies automatically.

  4. If the address changes per transaction — update your source system or integration to include it and resend.

Wrong N103/N104 identification code

What's happening: The N103 qualifier or N104 value doesn't match what the trading partner expects — for example, sending a seller-assigned code (91) when the partner expects a GLN (9), or sending a store number or DC code that doesn't exist in their system.

How this surfaces:

  • Orderful validation: Transaction status is Invalid if the guideline enforces a specific qualifier. The Rules Editor shows something like:

    Path: transactionSets.0.N1_loop.0.partyIdentification.0.identificationCodeQualifier
Error: 91 is not a valid input.
Allowed values:
  9     GLN (Global Location Number)

  • Partner outreach: Transaction shows Valid but partner reports during testing that the location code doesn't resolve in their system.

How to fix it:

  1. Confirm with your trading partner which N103 qualifier they expect for each party

  2. Confirm the exact N104 value (GLN, store number, DC number, DUNS) they have on file for each location

  3. If the qualifier needs to be remapped, use a REPLACE rule:

    REPLACE($transactionSets.*.N1_loop.*.partyIdentification.*.identificationCodeQualifier, "91", "9")

    No resend needed if caught by Orderful — the rule applies automatically. If the partner reported it, resend after the fix.

  4. GLNs must be 13-digit GS1 numbers; DUNS numbers must be exactly 9 digits

What to Send Orderful Support

Contact [email protected] with:

  • Transaction ID showing the problem

  • Trading partner name and relationship details

  • Current incorrect output — screenshot or raw EDI snippet showing the N1 loop as received

  • Expected format from your trading partner's requirements or guidelines

  • Specific N1 qualifiers your trading partner expects and at which level (shipment, order, item)

  • Sender and receiver ISA IDs from the transaction header

Frequently Asked Questions

My N1 loop has no N3 or N4 — is that valid?

It depends on your trading partner's requirements. When both partners agree to identify the party through a code in N103/N104 (such as a GLN), a physical address in N3/N4 may not be required — the receiving system looks up the address internally. But many partners do require N3/N4 for specific qualifiers regardless. Check the guidelines for the relationship to confirm what's expected.

Can I map multiple N1 qualifiers to the same address?

Yes, but each qualifier serves a distinct purpose. Don't use N1*ST for ship-from data or N1*SF for ship-to data — the receiving system uses the qualifier to determine how to process the address. Some partners use combined qualifiers like BS (bill-to and ship-to) for scenarios where a single address serves both roles.

Why does the 940 have both DE (depositor) and ST (ship-to) qualifiers?

DE identifies the company that owns the goods at the warehouse. ST identifies where the goods should be shipped. These are different parties — a common mapping error reads ship-to data from N1*DE instead of N1*ST.

The same N1 qualifier appears multiple times in my transaction. Is that valid?

Yes, and it's common. Multiple occurrences of the same qualifier appear at different HL hierarchy levels, not as duplicates at the same level. In a cross-dock 856, for example, each order-level HL loop typically has its own N1*ST (ship-to) and sometimes N1*SF (ship-from) identifying the destination and origin for that specific PO. This is the expected structure for multi-destination ASNs.

My trading partner uses a qualifier I don't recognize. What do I do?

Contact your trading partner to confirm the qualifier and its meaning. Non-standard qualifiers may require guideline customization in Orderful — contact [email protected] with the qualifier and examples of how your partner uses it.

Did this answer your question?