Workflow Overview
The Order-to-Cash flow involves four key transaction types:
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 850 PO │────▶│ 855 POA │────▶│ 856 ASN │────▶│ 810 Invoice │
│ (Retailer) │ │ (Supplier) │ │ (Supplier) │ │ (Supplier) │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
│ │ │ │
│ │ │ │
Buyer Confirm Ship goods Bill for
places receipt & & notify goods
order acceptance shipped
| Step | Transaction | Direction | Purpose |
|---|---|---|---|
| 1 | 850 Purchase Order | Inbound | Retailer orders products |
| 2 | 855 PO Acknowledgment | Outbound | You confirm/modify the order |
| 3 | 856 Advance Ship Notice | Outbound | You notify shipment details |
| 4 | 810 Invoice | Outbound | You bill for shipped goods |
Step 1: Receive the Purchase Order (850)
Detect New Orders
Using the Inbox (v4):
curl -X GET "https://api.orderful.com/v4/inbox?transactionType=850" \
-H "orderful-api-key: YOUR_API_KEY" \
-H "orderful-version: v4"Using Polling (v3):
curl -X GET "https://api.orderful.com/v3/transactions?direction=inbound&transactionType=850&deliveryState=pending" \
-H "orderful-api-key: YOUR_API_KEY"Get the Full PO Content
curl -X GET "https://api.orderful.com/v3/transactions/12345/message" \
-H "orderful-api-key: YOUR_API_KEY"Example Response:
{
"purpose": "original",
"purchaseOrderType": "standalone",
"purchaseOrderNumber": "PO-2024-001234",
"purchaseOrderDate": "2024-01-15",
"releaseNumber": "REL-001",
"contractNumber": "CNT-2024-ABC",
"acknowledgmentType": "withDetail",
"conditionsAndRestrictions": [
{
"conditionType": "shipComplete",
"action": "confirm",
"services": "twoDayService",
"maxOrderValue": "50000.00"
}
],
"parties": {
"buyer": {
"name": "Acme Corporation",
"additionalName1": "Procurement Department",
"identificationCode": "123456789",
"identificationCodeType": "duns",
"addressLine1": "123 Main Street",
"addressLine2": "Suite 500",
"city": "Chicago",
"stateOrProvinceCode": "IL",
"postalCode": "60601",
"countryCode": "US",
"zoneType": "commercial",
"contacts": [
{
"type": "primary",
"name": "John Smith",
"phoneNumber": "312-555-0100",
"email": "[email protected]"
},
{
"type": "orderInquiry",
"name": "Order Desk",
"phoneNumber": "312-555-0200",
"email": "[email protected]"
}
]
},
"shipTo": {
"name": "Acme Corporation - Warehouse",
"identificationCode": "987654321",
"identificationCodeType": "duns",
"addressLine1": "456 Warehouse Boulevard",
"city": "Elk Grove Village",
"stateOrProvinceCode": "IL",
"postalCode": "60007",
"countryCode": "US",
"zoneType": "commercial",
"contacts": [
{
"type": "receiving",
"name": "Receiving Department",
"phoneNumber": "847-555-0300"
}
]
},
"billTo": {
"name": "Acme Corporation",
"identificationCode": "123456789",
"identificationCodeType": "duns",
"addressLine1": "123 Main Street",
"addressLine2": "Accounts Payable",
"city": "Chicago",
"stateOrProvinceCode": "IL",
"postalCode": "60601",
"countryCode": "US"
},
"shipFrom": {
"name": "Global Suppliers Inc.",
"identificationCode": "555123456",
"identificationCodeType": "duns",
"addressLine1": "789 Manufacturing Drive",
"city": "Dallas",
"stateOrProvinceCode": "TX",
"postalCode": "75201",
"countryCode": "US"
},
"accountsPayable": {
"name": "Acme Corporation - AP",
"addressLine1": "123 Main Street",
"addressLine2": "Finance Department",
"city": "Chicago",
"stateOrProvinceCode": "IL",
"postalCode": "60601",
"countryCode": "US"
},
"soldTo": {
"name": "Acme Corporation",
"identificationCode": "123456789",
"identificationCodeType": "duns",
"addressLine1": "123 Main Street",
"city": "Chicago",
"stateOrProvinceCode": "IL",
"postalCode": "60601",
"countryCode": "US"
},
"supplier": {
"name": "Global Suppliers Inc.",
"additionalName1": "Sales Division",
"identificationCode": "555123456",
"identificationCodeType": "duns",
"addressLine1": "789 Manufacturing Drive",
"city": "Dallas",
"stateOrProvinceCode": "TX",
"postalCode": "75201",
"countryCode": "US",
"zoneType": "commercial",
"contacts": [
{
"type": "primary",
"name": "Sarah Johnson",
"phoneNumber": "214-555-0400",
"email": "[email protected]"
}
]
}
},
"buyersCurrency": {
"currencyCode": "USD",
"exchangeRate": "1.00"
},
"sellersCurrency": {
"currencyCode": "USD",
"exchangeRate": "1.00"
},
"notes": {
"general": {
"description": "General order notes",
"text": [
"Please ensure all items are properly packaged",
"Include packing slip with shipment"
]
},
"orderInstructions": {
"description": "Order specific instructions",
"text": [
"All items must be shipped together",
"Use standard carrier for delivery"
]
},
"shippingInstructions": {
"description": "Shipping instructions",
"text": [
"Deliver during business hours only",
"Contact receiving department 24 hours before delivery"
]
}
},
"paperwork": [
{
"reportType": "materialDataSheet",
"reportTransmissionType": "withShipmentPackage",
"copiesNeeded": 2,
"isoLanguageCode": "en",
"description": "Material safety data sheets required"
},
{
"reportType": "technicalInformation",
"url": "https://example.com/tech-specs",
"description": "Technical specifications available online"
}
],
"packaging": [
{
"characteristicType": "palletType",
"description": "Standard 48x40 pallets required",
"unitLoadOption": "palletized"
},
{
"characteristicType": "shippingPackageLabeling",
"description": "Include PO number on all labels",
"agencyType": "uniformCodeCouncil"
}
],
"termsOfSale": {
"type": "basicDiscountOffered",
"basisDate": "invoiceDate",
"discountPercent": "2.0",
"discountDaysDue": 10,
"discountDueDate": "2024-02-25",
"netDaysDue": 30,
"netDueDate": "2024-02-15",
"discountAmount": "200.00",
"description": "2/10 Net 30 payment terms",
"paymentMethodType": "check"
},
"references": {
"accountNumber": {
"value": "ACC-12345",
"description": "Buyer account number"
},
"customerOrderNumber": {
"value": "CUST-ORD-789",
"description": "Customer order reference"
},
"vendorNumber": {
"value": "VND-456",
"description": "Vendor number"
},
"departmentNumber": {
"value": "DEPT-10",
"description": "Department code"
},
"storeNumber": {
"value": "STORE-001",
"description": "Store location"
},
"promotionNumber": {
"value": "PROMO-2024-Q1",
"description": "Promotion identifier"
}
},
"dates": {
"purchaseOrderDate": "2024-01-15",
"requestedShipDate": "2024-02-01",
"requestedDeliveryDate": "2024-02-05",
"earliestShipDate": "2024-01-28",
"latestShipDate": "2024-02-05",
"earliestDeliveryDate": "2024-02-01",
"latestDeliveryDate": "2024-02-10",
"cancelAfterDate": "2024-02-15",
"customerOrderDate": "2024-01-10"
},
"carrierDetails": {
"routing": [
{
"sequenceType": "origin",
"standardCarrierAlphaCode": "FEDX",
"transportationMethod": "commonCarrier",
"locationType": "origin",
"location": "Dallas, TX",
"serviceLevel": "ground",
"transitDirectionType": "sellerToBuyer",
"transitTimeType": "workingDays",
"transitTime": "3"
}
],
"freeOnBoard": [
{
"methodOfPayment": "prepaidBySeller",
"locationType": "origin",
"locationDescription": "Dallas, TX",
"titlePassageType": "origin",
"titlePassageDescription": "Dallas, TX",
"transportationTermsSource": "tradeTerms",
"transportationTerms": "freeOnBoard",
"riskOfLoss": "toDestinationBuyer"
}
],
"specialHandling": [
{
"handlingType": "fragile",
"description": "Handle with care"
},
{
"handlingType": "temperatureControl",
"description": "Maintain temperature between 60-70°F"
}
]
},
"allowances": [
{
"type": "volume",
"amount": "500.00",
"percent": "5.0",
"percentBasis": "basePrice",
"methodOfHandling": "paidByVendor",
"description": "Volume discount for orders over $10,000"
}
],
"charges": [
{
"type": "freight",
"amount": "250.00",
"methodOfHandling": "prepaid",
"description": "Prepaid freight charges"
}
],
"monetaryAmounts": {
"gross": "10500.00",
"net": "10000.00"
},
"taxes": {
"stateProvincialTax": {
"amount": "650.00",
"percent": "6.5",
"jurisdictionType": "state",
"jurisdictionCode": "IL"
},
"localTax": {
"amount": "100.00",
"percent": "1.0",
"jurisdictionType": "local",
"jurisdictionCode": "CHI"
}
},
"lineItems": [
{
"purchaseOrderLineId": "1",
"quantity": {
"value": "100",
"unitOfMeasure": "each"
},
"unitCostPrice": "45.00",
"unitPriceBasis": "perEach",
"additionalPricing": [
{
"priceType": "promotional",
"unitPrice": "42.00",
"unitPriceBasis": "perEach",
"quantityPerUnitPrice": "1"
}
],
"productIds": {
"buyerItemNumber": "ACME-12345",
"vendorItemNumber": "GSI-78901",
"gtin13": "1234567890123",
"buyerItemIds": [
{
"type": "sku",
"value": "SKU-ACME-12345"
}
]
},
"productAttributes": {
"description": "Premium Widget - Blue",
"colorCode": "BLU",
"colorDescription": "Blue",
"sizeCode": "LG",
"sizeDescription": "Large",
"materialCode": "STEEL",
"materialDescription": "Stainless Steel"
},
"outerPack": {
"numberOfUnits": "10",
"size": "12",
"sizeUOM": "each",
"packageForm": "box",
"packageMaterial": "corrugated",
"weightUOM": "pound",
"grossWeight": "50",
"netWeight": "45",
"dimensionUOM": "inch",
"length": "24",
"width": "18",
"height": "12",
"packageId": "PKG-001"
},
"innerPack": {
"numberOfUnits": "1",
"size": "1",
"sizeUOM": "each",
"packageForm": "box",
"packageMaterial": "corrugated",
"weightUOM": "pound",
"grossWeight": "5",
"netWeight": "4.5"
},
"packaging": [
{
"characteristicType": "typeOfPackage",
"description": "Corrugated cardboard box",
"unitLoadOption": "palletized"
}
],
"dates": {
"requestedShipDate": "2024-02-01",
"requestedDeliveryDate": "2024-02-05",
"earliestShipDate": "2024-01-28"
},
"references": {
"departmentNumber": {
"value": "DEPT-10",
"description": "Department"
},
"storeNumber": {
"value": "STORE-001",
"description": "Store location"
}
},
"destinationQuantities": {
"locationType": "warehouse",
"unitOfMeasure": "each",
"quantityByLocation": [
{
"destinationId": "WH-001",
"quantity": "60"
},
{
"destinationId": "WH-002",
"quantity": "40"
}
]
},
"allowances": [
{
"type": "quantityDiscount",
"amount": "50.00",
"percent": "1.0",
"methodOfHandling": "paidByVendor",
"description": "Quantity discount for 100+ units"
}
],
"charges": [
{
"type": "handling",
"amount": "25.00",
"methodOfHandling": "prepaid",
"description": "Special handling charge"
}
],
"monetaryAmounts": {
"gross": "4500.00",
"net": "4450.00"
},
"sublineItems": [
{
"sublineId": "1-1",
"quantity": {
"value": "50",
"unitOfMeasure": "each"
},
"productIds": {
"buyerItemNumber": "ACME-12345-A",
"vendorItemNumber": "GSI-78901-A"
},
"unitCostPrice": "45.00",
"unitPriceBasis": "perEach"
}
],
"notes": {
"general": {
"description": "Line item notes",
"text": [
"Ensure proper packaging",
"Include installation instructions"
]
},
"shippingInstructions": {
"description": "Shipping notes",
"text": [
"Ship in original packaging",
"Do not stack more than 5 high"
]
}
},
"paperwork": [
{
"reportType": "materialDataSheet",
"copiesNeeded": 1,
"description": "MSDS required for this item"
}
],
"conditionsAndRestrictions": [
{
"conditionType": "shipComplete",
"action": "confirm"
}
],
"carrierDetails": {
"routing": [
{
"sequenceType": "origin",
"transportationMethod": "commonCarrier",
"serviceLevel": "ground"
}
],
"freeOnBoard": [
{
"methodOfPayment": "prepaidBySeller",
"locationType": "origin"
}
]
}
},
{
"purchaseOrderLineId": "2",
"quantity": {
"value": "250",
"unitOfMeasure": "case"
},
"unitCostPrice": "18.50",
"unitPriceBasis": "perEach",
"productIds": {
"buyerItemNumber": "ACME-67890",
"vendorItemNumber": "GSI-23456",
"gtin14": "12345678901234"
},
"productAttributes": {
"description": "Standard Widget - Red",
"colorCode": "RED",
"colorDescription": "Red",
"sizeCode": "MD",
"sizeDescription": "Medium"
},
"outerPack": {
"numberOfUnits": "25",
"size": "1",
"sizeUOM": "case",
"packageForm": "box",
"packageMaterial": "corrugated",
"weightUOM": "pound",
"grossWeight": "30",
"netWeight": "28"
},
"dates": {
"requestedShipDate": "2024-02-01",
"requestedDeliveryDate": "2024-02-05"
},
"monetaryAmounts": {
"gross": "4625.00",
"net": "4625.00"
},
"notes": {
"general": {
"description": "Standard item",
"text": [
"Standard packaging acceptable"
]
}
}
},
{
"purchaseOrderLineId": "3",
"quantity": {
"value": "50",
"unitOfMeasure": "each"
},
"unitCostPrice": "17.50",
"productIds": {
"buyerItemNumber": "ACME-11111",
"vendorItemNumber": "GSI-33333",
"gtin12": "123456789012"
},
"monetaryAmounts": {
"gross": "875.00",
"net": "875.00"
}
}
]
}Process in Your System
- Parse the PO data
- Check inventory availability
- Validate pricing
- Create a sales order in your ERP/OMS
Confirm Receipt
After successful processing, acknowledge the delivery:
curl -X POST "https://api.orderful.com/v4/transactions/12345/deliveries/67890/approve" \
-H "orderful-api-key: YOUR_API_KEY" \
-H "orderful-version: v4"Step 2: Send Purchase Order Acknowledgment (855)
The POA tells the retailer whether you can fulfill the order. Send it within the timeframe specified in your trading partner agreement (typically 24-48 hours).
Acknowledgment Scenarios
| Scenario | Code | Description |
|---|---|---|
| Full acceptance | AC + all lines IA | Accept order as-is |
| Partial acceptance | AC + mixed codes | Some items accepted, others modified |
| Changes made | AC + lines with IC | Accepted with changes (qty, date, etc.) |
| Rejection | RJ | Entire order rejected |
Example: Full Acceptance
curl -X POST "https://api.orderful.com/v4/transactions" \
-H "orderful-api-key: YOUR_API_KEY" \
-H "orderful-version: v4" \
-H "Content-Type: application/json" \
-d '{
"sender": { "isaId": "YOUR_ISA_ID" },
"receiver": { "isaId": "RETAILCORP" },
"stream": "live",
"transactionType": "855",
"relatedTransactionId": 12345,
"message": {
"purchaseOrderAcknowledgment": {
"acknowledgmentType": "AC",
"purchaseOrderNumber": "PO-2026-78901",
"acknowledgedDate": "2026-01-15",
"estimatedShipDate": "2026-01-25",
"lineItems": [
{
"lineNumber": "001",
"acknowledgmentCode": "IA",
"vendorPartNumber": "WIDGET-A",
"acknowledgedQuantity": 500,
"unitPrice": 12.50
},
{
"lineNumber": "002",
"acknowledgmentCode": "IA",
"vendorPartNumber": "WIDGET-B",
"acknowledgedQuantity": 300,
"unitPrice": 12.50
}
]
}
}
}'Example: Partial Acceptance (Backorder)
{
"message": {
"purchaseOrderAcknowledgment": {
"acknowledgmentType": "AC",
"purchaseOrderNumber": "PO-2026-78901",
"lineItems": [
{
"lineNumber": "001",
"acknowledgmentCode": "IA",
"acknowledgedQuantity": 500
},
{
"lineNumber": "002",
"acknowledgmentCode": "IB",
"acknowledgedQuantity": 200,
"backorderQuantity": 100,
"estimatedBackorderDate": "2026-02-15",
"note": "100 units on backorder, shipping 200 now"
}
]
}
}
}Step 3: Send Advance Ship Notice (856)
When you ship the order, send an ASN with carton-level detail. This enables the retailer to receive goods efficiently.
ASN Structure
Shipment (856)
├── Shipment Header (carrier, dates, totals)
├── Order Reference (PO number)
└── Hierarchical Levels
├── Shipment Level (HL-S)
│ └── Order Level (HL-O)
│ └── Pack Level (HL-P) - Cartons/Pallets
│ └── Item Level (HL-I) - Line items
Example: Complete ASN
curl -X POST "https://api.orderful.com/v4/transactions" \
-H "orderful-api-key: YOUR_API_KEY" \
-H "orderful-version: v4" \
-H "Content-Type: application/json" \
-d '{
"sender": { "isaId": "YOUR_ISA_ID" },
"receiver": { "isaId": "RETAILCORP" },
"stream": "live",
"transactionType": "856",
"relatedTransactionId": 12345,
"message": {
"shipNotice": {
"shipmentIdentifier": "SHIP-2026-001234",
"shipDate": "2026-01-25",
"estimatedDeliveryDate": "2026-01-28",
"shipmentWeight": 125.5,
"weightUnit": "LB",
"carrier": {
"name": "FastFreight Logistics",
"scac": "FFRL",
"serviceLevel": "GROUND",
"proNumber": "PRO123456789",
"trackingNumbers": ["1Z999AA10123456784"]
},
"shipFrom": {
"name": "Your Company Warehouse",
"address": {
"street": "100 Industrial Way",
"city": "Manufacturing City",
"state": "TX",
"postalCode": "75001"
}
},
"shipTo": {
"locationCode": "DC-005",
"name": "Retail Corp DC #5",
"address": {
"street": "456 Warehouse Blvd",
"city": "Commerce City",
"state": "CA",
"postalCode": "90211"
}
},
"purchaseOrderNumber": "PO-2026-78901",
"packages": [
{
"packageType": "CTN",
"packageId": "SSCC00123456789012345671",
"weight": 65.5,
"weightUnit": "LB",
"contents": [
{
"lineNumber": "001",
"vendorPartNumber": "WIDGET-A",
"upc": "012345678901",
"quantity": 500
}
]
},
{
"packageType": "CTN",
"packageId": "SSCC00123456789012345672",
"weight": 60.0,
"weightUnit": "LB",
"contents": [
{
"lineNumber": "002",
"vendorPartNumber": "WIDGET-B",
"upc": "012345678902",
"quantity": 300
}
]
}
]
}
}
}'GS1-128 Labels
Most retailers require GS1-128 (UCC-128) labels on each carton. The SSCC (Serial Shipping Container Code) in the ASN must match the barcode on the physical carton.
Step 4: Send Invoice (810)
After shipment, send the invoice. Many retailers have strict timing requirements (e.g., invoice within 48 hours of ship date).
Example: Complete Invoice
curl -X POST "https://api.orderful.com/v4/transactions" \
-H "orderful-api-key: YOUR_API_KEY" \
-H "orderful-version: v4" \
-H "Content-Type: application/json" \
-d '{
"sender": { "isaId": "YOUR_ISA_ID" },
"receiver": { "isaId": "RETAILCORP" },
"stream": "live",
"transactionType": "810",
"relatedTransactionId": 12345,
"message": {
"invoice": {
"invoiceNumber": "INV-2026-001234",
"invoiceDate": "2026-01-25",
"invoiceType": "original",
"purchaseOrderNumber": "PO-2026-78901",
"shipDate": "2026-01-25",
"paymentTerms": {
"termsType": "NET",
"netDays": 30,
"discountPercent": 2,
"discountDays": 10,
"description": "2% 10 Net 30"
},
"remitTo": {
"name": "Your Company Inc",
"address": {
"street": "100 Corporate Drive",
"city": "Business City",
"state": "CA",
"postalCode": "90001"
}
},
"lineItems": [
{
"lineNumber": "001",
"vendorPartNumber": "WIDGET-A",
"upc": "012345678901",
"description": "Premium Widget - Blue",
"quantity": 500,
"unitOfMeasure": "EA",
"unitPrice": 12.50,
"lineTotal": 6250.00
},
{
"lineNumber": "002",
"vendorPartNumber": "WIDGET-B",
"upc": "012345678902",
"description": "Premium Widget - Red",
"quantity": 300,
"unitOfMeasure": "EA",
"unitPrice": 12.50,
"lineTotal": 3750.00
}
],
"summary": {
"totalLineItems": 2,
"totalQuantity": 800,
"subtotal": 10000.00,
"freightAmount": 150.00,
"taxAmount": 0.00,
"totalAmount": 10150.00
}
}
}
}'Handling Exceptions
Scenario: Partial Shipment
If you can't ship everything at once:
- 855 POA: Indicate partial acceptance or backorder
- 856 ASN: Send for items being shipped now
- 810 Invoice: Invoice only for shipped items
- Repeat 3-4: Send additional ASN/Invoice when backorder ships
Scenario: Order Changes
If the retailer sends an order change (860):
- Receive and process the 860
- Send an 865 (PO Change Acknowledgment)
- Adjust your fulfillment accordingly
Scenario: Returns
For return authorizations, implement the 180/944 or 180/812 flow as required by your trading partner.
Timeline Best Practices
| Event | Recommended Timing |
|---|---|
| 855 POA | Within 24 hours of receiving 850 |
| 856 ASN | Same day as shipment (before goods arrive) |
| 810 Invoice | Within 48 hours of shipment |
Note: Timing requirements vary by trading partner. Check your specific partner's guidelines.
Monitoring Your Integration
Check Transaction Status
curl -X GET "https://api.orderful.com/v3/transactions/12345" \
-H "orderful-api-key: YOUR_API_KEY"View in Orderful Portal
Monitor your transactions in real-time:
- Go to Transactions in the Orderful portal
- Filter by transaction type, date, or status
- Click any transaction to see full details

Next Steps
- Testing Guide - Test your O2C flow end-to-end
- Webhook Configuration - Set up real-time notifications
- Error Handling - Handle edge cases gracefully
- Going Live Checklist - Production readiness checklist
