Legacy Alternative: OrderfulJSON

What is OrderfulJSON?

OrderfulJSON is a JSON representation of X12 EDI segments and elements. It provides:

Full EDI Control: Access to all EDI segments, elements, and qualifiers
Partner-Specific Mapping: Create custom mappings for complex requirements
EDI Expertise Leverage: Use your team's existing EDI knowledge
JSON Convenience: Work with JSON while maintaining EDI fidelity

When to Use OrderfulJSON

Choose OrderfulJSON when:

✅ You need precise control over EDI segment structure
✅ Your trading partners have complex, non-standard requirements
✅ Your team has existing EDI expertise
✅ You're migrating from a legacy EDI system
✅ Partner-specific customizations are required
✅ You need to match exact EDI specifications

💡
Tip: For most integrations, Mosaic is simpler and handles partner requirements automatically. Use OrderfulJSON when you specifically need EDI-level control.

Prerequisites

Before starting, ensure you have:

Completed the Quick Start Guide
Your API key from Settings → API Credentials
Understanding of X12 EDI segment structure (ST, BEG, REF, N1, PO1, etc.)
A test trading partnership configured

Architecture Overview

┌─────────────────┐     ┌─────────────┐     ┌──────────────────┐
│  Trading Partner │────▶│  Orderful   │────▶│  Your System     │
│  (Sends X12)     │     │  (Converts) │     │  (Gets JSON)     │
└─────────────────┘     └─────────────┘     └──────────────────┘
        │                      │                     │
        │    850 (PO)          │                     │
        │─────────────────────▶│                     │
        │                      │  Webhook/Poll       │
        │                      │  OrderfulJSON       │
        │                      │────────────────────▶│
        │                      │                     │
        │    855 (POA)         │                     │
        │◀─────────────────────│  POST OrderfulJSON │
        │                      │◀────────────────────│
        │                      │  (Converts to X12)  │

OrderfulJSON Structure

OrderfulJSON follows the X12 EDI hierarchy:

{
  "heading": {
    "transactionSetHeader_ST": { ... },
    "beginningSegment_XXX": { ... },
    "reference_REF": [ ... ],
    "name_N1Loop": [ ... ]
  },
  "detail": {
    "baselineItemData_PO1Loop": [ ... ]
  },
  "summary": {
    "transactionTotals_CTT": { ... },
    "transactionSetTrailer_SE": { ... }
  }
}

Segment Naming Convention

Segments are named using the pattern: {segmentDescription}_{EDISegmentID}

Examples:

transactionSetHeader_ST
beginningSegmentForPurchaseOrder_BEG
reference_REF
name_N1

Element Naming Convention

Elements are named using the pattern: {elementDescription}_{elementPosition}

Examples:

transactionSetIdentifierCode_01 (ST01)
purchaseOrderNumber_03 (BEG03)
identificationCodeQualifier_03 (N103)

Step 1: Receiving Inbound Transactions

Option A: Webhooks (Recommended)

Configure webhooks in Settings → Webhooks to receive real-time notifications:

Webhook Payload:

{
  "event": "transaction.created",
  "data": {
    "transactionId": 12345,
    "transactionType": "850",
    "direction": "inbound",
    "stream": "live"
  }
}

Option B: Polling

Poll the transactions endpoint:

curl -X GET "https://api.orderful.com/v3/transactions?direction=inbound&status=new" \
  -H "orderful-api-key: YOUR_API_KEY"

Step 2: Get Transaction Content in OrderfulJSON

Retrieve the full OrderfulJSON payload:

curl -X GET "https://api.orderful.com/v3/transactions/12345/message" \
  -H "orderful-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

Response (850 Purchase Order):

{
  "heading": {
    "transactionSetHeader_ST": {
      "transactionSetIdentifierCode_01": "850",
      "transactionSetControlNumber_02": "0001"
    },
    "beginningSegmentForPurchaseOrder_BEG": {
      "transactionSetPurposeCode_01": "00",
      "purchaseOrderTypeCode_02": "SA",
      "purchaseOrderNumber_03": "PO-2024-001234",
      "date_05": "20240115"
    },
    "reference_REF": [
      {
        "referenceIdentificationQualifier_01": "DP",
        "referenceIdentification_02": "DEPT-123"
      }
    ],
    "dateTimeReference_DTM": [
      {
        "dateTimeQualifier_01": "010",
        "date_02": "20240125"
      }
    ],
    "name_N1Loop": [
      {
        "name_N1": {
          "entityIdentifierCode_01": "BY",
          "name_02": "Acme Retail Corp",
          "identificationCodeQualifier_03": "92",
          "identificationCode_04": "ACME001"
        },
        "additionalNameInformation_N2": [
          {
            "name_01": "Purchasing Department"
          }
        ],
        "addressInformation_N3": [
          {
            "addressInformation_01": "123 Retail Way"
          }
        ],
        "geographicLocation_N4": [
          {
            "cityName_01": "Commerce City",
            "stateOrProvinceCode_02": "CA",
            "postalCode_03": "90210",
            "countryCode_04": "US"
          }
        ]
      },
      {
        "name_N1": {
          "entityIdentifierCode_01": "ST",
          "name_02": "Acme Distribution Center #5",
          "identificationCodeQualifier_03": "92",
          "identificationCode_04": "DC-001"
        },
        "addressInformation_N3": [
          {
            "addressInformation_01": "456 Warehouse Blvd"
          }
        ],
        "geographicLocation_N4": [
          {
            "cityName_01": "Indianapolis",
            "stateOrProvinceCode_02": "IN",
            "postalCode_03": "46201",
            "countryCode_04": "US"
          }
        ]
      }
    ]
  },
  "detail": {
    "baselineItemData_PO1Loop": [
      {
        "baselineItemData_PO1": {
          "assignedIdentification_01": "1",
          "quantityOrdered_02": "100",
          "unitOrBasisForMeasurementCode_03": "EA",
          "unitPrice_04": "24.99",
          "productServiceIDQualifier_06": "VP",
          "productServiceID_07": "VPN-98765",
          "productServiceIDQualifier_08": "BP",
          "productServiceID_09": "SKU-12345"
        },
        "productItemDescription_PID": [
          {
            "itemDescriptionType_01": "F",
            "description_05": "Widget Model A - Blue"
          }
        ]
      },
      {
        "baselineItemData_PO1": {
          "assignedIdentification_01": "2",
          "quantityOrdered_02": "50",
          "unitOrBasisForMeasurementCode_03": "EA",
          "unitPrice_04": "35.00",
          "productServiceIDQualifier_06": "VP",
          "productServiceID_07": "VPN-54321",
          "productServiceIDQualifier_08": "BP",
          "productServiceID_09": "SKU-67890"
        },
        "productItemDescription_PID": [
          {
            "itemDescriptionType_01": "F",
            "description_05": "Widget Model B - Red"
          }
        ]
      }
    ]
  },
  "summary": {
    "transactionTotals_CTT": {
      "numberOfLineItems_01": "2"
    },
    "transactionSetTrailer_SE": {
      "numberOfIncludedSegments_01": "14",
      "transactionSetControlNumber_02": "0001"
    }
  }
}

Step 3: Confirm Delivery

After processing, approve the delivery:

curl -X POST "https://api.orderful.com/v3/deliveries/67890/approve" \
  -H "orderful-api-key: YOUR_API_KEY"

Step 4: Send Response Transactions

Sending a Purchase Order Acknowledgment (855)

curl -X POST "https://api.orderful.com/v3/transactions" \
  -H "orderful-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "direction": "outbound",
    "senderId": "YOUR_ISA_ID",
    "senderQualifier": "ZZ",
    "receiverId": "PARTNER_ISA_ID",
    "receiverQualifier": "ZZ",
    "transactionType": "855",
    "stream": "test",
    "message": {
      "heading": {
        "transactionSetHeader_ST": {
          "transactionSetIdentifierCode_01": "855",
          "transactionSetControlNumber_02": "0001"
        },
        "beginningSegmentForPurchaseOrderAcknowledgment_BAK": {
          "transactionSetPurposeCode_01": "00",
          "acknowledgmentType_02": "AC",
          "purchaseOrderNumber_03": "PO-2024-001234",
          "date_04": "20240115",
          "date_06": "20240116"
        },
        "reference_REF": [
          {
            "referenceIdentificationQualifier_01": "DP",
            "referenceIdentification_02": "DEPT-123"
          }
        ]
      },
      "detail": {
        "poAcknowledgment_POLoop": [
          {
            "poAcknowledgment_PO": {
              "assignedIdentification_01": "1",
              "quantityOrdered_02": "100",
              "unitOrBasisForMeasurementCode_03": "EA",
              "unitPrice_04": "24.99",
              "productServiceIDQualifier_06": "VP",
              "productServiceID_07": "VPN-98765"
            },
            "acknowledgment_ACK": [
              {
                "lineItemStatusCode_01": "IA",
                "quantity_02": "100",
                "unitOrBasisForMeasurementCode_03": "EA"
              }
            ]
          },
          {
            "poAcknowledgment_PO": {
              "assignedIdentification_01": "2",
              "quantityOrdered_02": "50",
              "unitOrBasisForMeasurementCode_03": "EA",
              "unitPrice_04": "35.00",
              "productServiceIDQualifier_06": "VP",
              "productServiceID_07": "VPN-54321"
            },
            "acknowledgment_ACK": [
              {
                "lineItemStatusCode_01": "IA",
                "quantity_02": "50",
                "unitOrBasisForMeasurementCode_03": "EA"
              }
            ]
          }
        ]
      },
      "summary": {
        "transactionTotals_CTT": {
          "numberOfLineItems_01": "2"
        },
        "transactionSetTrailer_SE": {
          "numberOfIncludedSegments_01": "10",
          "transactionSetControlNumber_02": "0001"
        }
      }
    }
  }'

Line Item Status Codes (ACK01):

Code	Meaning
`IA`	Item Accepted
`IB`	Item Backordered
`IC`	Item Accepted - Change Made
`ID`	Item Deleted
`IE`	Item Accepted - Estimated Delivery
`IR`	Item Rejected
`IW`	Item on Hold

Sending an Advance Ship Notice (856)

curl -X POST "https://api.orderful.com/v3/transactions" \
  -H "orderful-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "direction": "outbound",
    "senderId": "YOUR_ISA_ID",
    "senderQualifier": "ZZ",
    "receiverId": "PARTNER_ISA_ID",
    "receiverQualifier": "ZZ",
    "transactionType": "856",
    "stream": "test",
    "message": {
      "heading": {
        "transactionSetHeader_ST": {
          "transactionSetIdentifierCode_01": "856",
          "transactionSetControlNumber_02": "0001"
        },
        "beginningSegmentForShipNotice_BSN": {
          "transactionSetPurposeCode_01": "00",
          "shipmentIdentification_02": "SHIP-2024-001",
          "date_03": "20240120",
          "time_04": "1430"
        },
        "dateTimeReference_DTM": [
          {
            "dateTimeQualifier_01": "011",
            "date_02": "20240125"
          }
        ],
        "hierarchicalLevel_HLLoop": [
          {
            "hierarchicalLevel_HL": {
              "hierarchicalIDNumber_01": "1",
              "hierarchicalLevelCode_03": "S"
            },
            "carrierDetails_TD5": [
              {
                "routingSequenceCode_01": "O",
                "identificationCodeQualifier_02": "2",
                "identificationCode_03": "FFRT",
                "transportationMethodTypeCode_04": "M"
              }
            ],
            "carrierDetails_TD3": [
              {
                "equipmentDescriptionCode_01": "TL"
              }
            ],
            "referenceIdentification_REF": [
              {
                "referenceIdentificationQualifier_01": "CN",
                "referenceIdentification_02": "1Z999AA10123456784"
              },
              {
                "referenceIdentificationQualifier_01": "BM",
                "referenceIdentification_02": "BOL-2024-001"
              }
            ],
            "name_N1Loop": [
              {
                "name_N1": {
                  "entityIdentifierCode_01": "SF",
                  "name_02": "Your Warehouse"
                },
                "addressInformation_N3": [
                  {
                    "addressInformation_01": "789 Shipping Lane"
                  }
                ],
                "geographicLocation_N4": [
                  {
                    "cityName_01": "Warehouse City",
                    "stateOrProvinceCode_02": "TX",
                    "postalCode_03": "75001",
                    "countryCode_04": "US"
                  }
                ]
              }
            ]
          },
          {
            "hierarchicalLevel_HL": {
              "hierarchicalIDNumber_01": "2",
              "hierarchicalParentIDNumber_02": "1",
              "hierarchicalLevelCode_03": "O"
            },
            "referenceIdentification_REF": [
              {
                "referenceIdentificationQualifier_01": "PO",
                "referenceIdentification_02": "PO-2024-001234"
              }
            ]
          },
          {
            "hierarchicalLevel_HL": {
              "hierarchicalIDNumber_01": "3",
              "hierarchicalParentIDNumber_02": "2",
              "hierarchicalLevelCode_03": "P"
            },
            "marksAndNumbers_MAN": [
              {
                "marksAndNumbersQualifier_01": "GM",
                "marksAndNumbers_02": "00012345678901234567"
              }
            ],
            "measurementsOrDimensions_MEA": [
              {
                "measurementReferenceIDCode_01": "PD",
                "measurementQualifier_02": "G",
                "measurementValue_03": "25.5",
                "unitOrBasisForMeasurementCode_C0001_04": "LB"
              }
            ]
          },
          {
            "hierarchicalLevel_HL": {
              "hierarchicalIDNumber_01": "4",
              "hierarchicalParentIDNumber_02": "3",
              "hierarchicalLevelCode_03": "I"
            },
            "itemIdentification_LIN": {
              "productServiceIDQualifier_02": "VP",
              "productServiceID_03": "VPN-98765"
            },
            "itemDetailShipment_SN1": {
              "numberOfUnitsShipped_02": "100",
              "unitOrBasisForMeasurementCode_03": "EA"
            }
          }
        ]
      },
      "summary": {
        "transactionSetTrailer_SE": {
          "numberOfIncludedSegments_01": "22",
          "transactionSetControlNumber_02": "0001"
        }
      }
    }
  }'

Sending an Invoice (810)

curl -X POST "https://api.orderful.com/v3/transactions" \
  -H "orderful-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "direction": "outbound",
    "senderId": "YOUR_ISA_ID",
    "senderQualifier": "ZZ",
    "receiverId": "PARTNER_ISA_ID",
    "receiverQualifier": "ZZ",
    "transactionType": "810",
    "stream": "test",
    "message": {
      "heading": {
        "transactionSetHeader_ST": {
          "transactionSetIdentifierCode_01": "810",
          "transactionSetControlNumber_02": "0001"
        },
        "beginningSegmentForInvoice_BIG": {
          "date_01": "20240120",
          "invoiceNumber_02": "INV-2024-001234",
          "purchaseOrderNumber_04": "PO-2024-001234"
        },
        "reference_REF": [
          {
            "referenceIdentificationQualifier_01": "DP",
            "referenceIdentification_02": "DEPT-123"
          }
        ],
        "name_N1Loop": [
          {
            "name_N1": {
              "entityIdentifierCode_01": "ST",
              "name_02": "Acme Distribution Center #5"
            },
            "addressInformation_N3": [
              {
                "addressInformation_01": "456 Warehouse Blvd"
              }
            ],
            "geographicLocation_N4": [
              {
                "cityName_01": "Indianapolis",
                "stateOrProvinceCode_02": "IN",
                "postalCode_03": "46201"
              }
            ]
          }
        ],
        "termsOfSaleDeferredTermsOfSale_ITD": [
          {
            "termsTypeCode_01": "01",
            "termsBasisDateCode_02": "3",
            "termsNetDays_07": "30",
            "termsDescription_12": "NET30"
          }
        ]
      },
      "detail": {
        "baselineItemDataInvoice_IT1Loop": [
          {
            "baselineItemDataInvoice_IT1": {
              "assignedIdentification_01": "1",
              "quantityInvoiced_02": "100",
              "unitOrBasisForMeasurementCode_03": "EA",
              "unitPrice_04": "25.00",
              "productServiceIDQualifier_06": "VP",
              "productServiceID_07": "VPN-98765",
              "productServiceIDQualifier_08": "BP",
              "productServiceID_09": "SKU-12345"
            },
            "productItemDescription_PID": [
              {
                "itemDescriptionType_01": "F",
                "description_05": "Widget Model A - Blue"
              }
            ]
          },
          {
            "baselineItemDataInvoice_IT1": {
              "assignedIdentification_01": "2",
              "quantityInvoiced_02": "50",
              "unitOrBasisForMeasurementCode_03": "EA",
              "unitPrice_04": "35.00",
              "productServiceIDQualifier_06": "VP",
              "productServiceID_07": "VPN-54321",
              "productServiceIDQualifier_08": "BP",
              "productServiceID_09": "SKU-67890"
            },
            "productItemDescription_PID": [
              {
                "itemDescriptionType_01": "F",
                "description_05": "Widget Model B - Red"
              }
            ]
          }
        ]
      },
      "summary": {
        "totalMonetaryValueSummary_TDS": {
          "amount_01": "4250.00"
        },
        "taxInformation_TXI": [
          {
            "taxTypeCode_01": "ST",
            "monetaryAmount_02": "340.00"
          }
        ],
        "transactionTotals_CTT": {
          "numberOfLineItems_01": "2"
        },
        "transactionSetTrailer_SE": {
          "numberOfIncludedSegments_01": "16",
          "transactionSetControlNumber_02": "0001"
        }
      }
    }
  }'

Common EDI Segment Reference

Transaction Set Header (ST)

"transactionSetHeader_ST": {
  "transactionSetIdentifierCode_01": "850",  // Transaction type
  "transactionSetControlNumber_02": "0001"   // Unique control number
}

Name and Address (N1 Loop)

"name_N1Loop": [{
  "name_N1": {
    "entityIdentifierCode_01": "BY",  // BY=Buyer, ST=ShipTo, SF=ShipFrom
    "name_02": "Company Name",
    "identificationCodeQualifier_03": "92",  // Qualifier type
    "identificationCode_04": "COMPANY001"
  },
  "addressInformation_N3": [{
    "addressInformation_01": "123 Main St"
  }],
  "geographicLocation_N4": [{
    "cityName_01": "City",
    "stateOrProvinceCode_02": "ST",
    "postalCode_03": "12345",
    "countryCode_04": "US"
  }]
}]

Date/Time Reference (DTM)

"dateTimeReference_DTM": [{
  "dateTimeQualifier_01": "010",  // 010=Requested ship date
  "date_02": "20240125",          // CCYYMMDD format
  "time_03": "1430"               // HHMM format (optional)
}]

Common Date Qualifiers:

010: Requested Ship Date
011: Delivery Date
017: Estimated Delivery Date
063: Do Not Deliver Before
064: Do Not Deliver After

Reference (REF)

"reference_REF": [{
  "referenceIdentificationQualifier_01": "PO",  // Reference type
  "referenceIdentification_02": "PO-12345"      // Reference value
}]

Common Reference Qualifiers:

PO: Purchase Order Number
DP: Department Number
IA: Internal Vendor Number
CN: Carrier's Reference Number (PRO/Bill of Lading)
BM: Bill of Lading Number

Error Handling

Validation Errors

OrderfulJSON validation errors reference specific EDI segments and elements:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Transaction validation failed",
    "details": [
      {
        "path": "message.heading.beginningSegmentForPurchaseOrder_BEG.purchaseOrderNumber_03",
        "message": "Field is required",
        "segment": "BEG",
        "element": "03"
      }
    ]
  }
}

Common Errors

Error Code	Cause	Solution
`MISSING_REQUIRED_SEGMENT`	Required EDI segment missing	Add the required segment (e.g., ST, SE, BEG)
`INVALID_ELEMENT_VALUE`	Element value doesn't match allowed values	Check X12 spec for valid codes
`SEGMENT_ORDER_ERROR`	Segments in wrong order	Reorder segments per X12 specification
`CONTROL_NUMBER_MISMATCH`	ST02 doesn't match SE02	Ensure control numbers match

Best Practices

1. Maintain Segment Order

Follow X12 specifications for segment ordering:

{
  "heading": {
    "transactionSetHeader_ST": { ... },      // Always first
    "beginningSegment_XXX": { ... },         // Transaction-specific
    "reference_REF": [ ... ],                // References
    "dateTimeReference_DTM": [ ... ],        // Dates
    "name_N1Loop": [ ... ]                   // Name/Address loops
  },
  "detail": { ... },                         // Line items
  "summary": {
    "transactionTotals_CTT": { ... },
    "transactionSetTrailer_SE": { ... }      // Always last
  }
}

2. Use Control Numbers Correctly

ST02 (Transaction Set Control Number) must match SE02
Increment control numbers for each transaction
Use unique control numbers within functional groups

3. Include Required Segments

Every transaction must include:

ST - Transaction Set Header
Beginning segment (e.g., BEG, BAK, BSN, BIG)
SE - Transaction Set Trailer

4. Validate Element Lengths

Respect EDI element length constraints:

Purchase Order Number (BEG03): Max 22 characters
Invoice Number (BIG02): Max 22 characters
Item identifiers: Usually max 48 characters

5. Test with Partners

Partner requirements vary. Always test with:

Partner's test environment
Sample transactions they provide
Edge cases (backorders, changes, cancellations)

Mapping Resources

X12 Segment Documentation

For detailed segment specifications:

Element Qualifiers

Common qualifier codes:

Entity Identifier Codes (N101): BY, ST, SF, SU, BT
ID Code Qualifiers (N103): 92 (Assigned by buyer), 91 (Assigned by seller), 01 (DUNS)
Unit of Measure: EA (Each), CS (Case), PL (Pallet), LB (Pound)

Migration from Mosaic

If you need to migrate from Mosaic to OrderfulJSON:

Retrieve Mosaic transaction via v4 API
Convert to OrderfulJSON using mapping logic
Test with partners to ensure compatibility
Update integration to use OrderfulJSON format

💡
Tip: Consider whether full EDI control is truly needed. Mosaic handles most partner requirements automatically.

Next Steps

Integration Patterns - Advanced integration patterns
Order to Cash Workflow - Complete workflow walkthrough
X12 Passthrough Guide - Raw X12 integration
EDI Specifications - Full X12 documentation

Legacy Alternative: OrderfulJSON

What is OrderfulJSON?

When to Use OrderfulJSON

Tip: For most integrations, Mosaic is simpler and handles partner requirements automatically. Use OrderfulJSON when you specifically need EDI-level control.

Prerequisites

Architecture Overview

OrderfulJSON Structure

Segment Naming Convention

Element Naming Convention

Step 1: Receiving Inbound Transactions

Option A: Webhooks (Recommended)

Option B: Polling

Step 2: Get Transaction Content in OrderfulJSON

Step 3: Confirm Delivery

Step 4: Send Response Transactions

Sending a Purchase Order Acknowledgment (855)

Sending an Advance Ship Notice (856)

Sending an Invoice (810)

Common EDI Segment Reference

Transaction Set Header (ST)

Name and Address (N1 Loop)

Date/Time Reference (DTM)

Reference (REF)

Error Handling

Validation Errors

Common Errors

Best Practices

1. Maintain Segment Order

2. Use Control Numbers Correctly

3. Include Required Segments

4. Validate Element Lengths

5. Test with Partners

Mapping Resources

X12 Segment Documentation

Element Qualifiers

Migration from Mosaic

Tip: Consider whether full EDI control is truly needed. Mosaic handles most partner requirements automatically.

Next Steps