Order Flow Tutorial - Complete Implementation Guide

This tutorial covers Steps 5-8: finding customer branches, selecting products, getting pricing, and submitting orders.

⏱️ Time to Complete: 2-3 hours

Before you start: Complete Steps 1-4 to get your access token and validated customer account.

🎯 What You'll Build

📋 Order Flow Checklist - Track Your Progress

Prerequisites (from Authentication Guide):

API credentials obtained

Access token retrieved

Customer validated

Branch locations explored

Steps 5-8 Progress:

🏪 Step 5: Customer branches retrieved

📦 Step 6: Products browsed at branch

💰 Step 7: Real-time pricing obtained

✅ Step 8: Order successfully submitted

Key Data Collected:

jobAccountNumber saved (from Step 5)

Product IDs identified (from Step 6)

Pricing validated (from Step 7)

Order ID received (from Step 8)

Integration Complete:

First test order submitted successfully

Order confirmation received

Webhook setup planned (for Production)

Error handling implemented

What you'll build:

🏪 Find customer branches with job accounts

📦 Browse available products

💰 Get real-time pricing

✅ Submit orders (sync & async)

🔄 Order Flow Overview

Step 5: Find Customer Branches & Job Accounts

❓ Why This Step Matters - Click to expand

Critical Information Retrieved:

🔑 Job Account Number - Required for ALL order submissions

🏢 Branch relationships specific to this customer

📍 Distance from customer ship-to addresses

🎯 Multiple job accounts per branch (if applicable)

Without this step:

❌ Cannot submit orders (missing jobAccountNumber)

❌ Don't know which branches serve this customer

❌ Can't optimize delivery routing

Real-World Example:

A construction company may have multiple projects (job accounts) at the same branch, each with different billing and shipping addresses.

💡 Best Practices for Step 5

Cache Strategy:

✅ Cache customer branch data for 24 hours

✅ Refresh when customer reports "branch not found"

✅ Store jobAccountNumber in customer session

User Experience:

✅ Let users see all available branches

✅ Show distance from ship-to address

✅ Default to nearest branch (lowest distance)

✅ Allow manual branch selection

Error Handling:

⚠️ If no branches returned → Customer not set up for branch access

⚠️ If multiple job accounts → Let user choose or default to first

⚠️ Contact SRS support to add branch access

API Call

Endpoint: GET /branches/v2/customerBranchLocations/{customerCode}

Example URL: https://services-qa.roofhub.pro/branches/v2/customerBranchLocations/CUST12345

Request Headers:

Authorization: Bearer {token}

Content-Type: application/json

Response Example

📋 Click to view response example

[
  {
    "branchCode": "CORAC",  // 🏪 Branch identifier
    "branchName": "AMERICAN ROOFING SUPPLY - RAPID CITY",  // 🏢 Branch display name
    "distanceFromShipToInMiles": 499.403,  // 📍 Distance from customer ship-to address
    "jobAccounts": [  // 🔑 CRITICAL - Job accounts for this customer at this branch
      {
        "jobAccountNumber": 43,  // 🎯 Required for Step 8 order submission!
        "jobAccountName": "TUSING BUILDERS & RFG (SOLON)"  // 📋 Job account description
      }
    ]
  },
  {
    "branchCode": "CORMN",
    "branchName": "AMERICAN ROOFING SUPPLY - MINNEAPOLIS",
    "distanceFromShipToInMiles": 234.567,
    "jobAccounts": [
      {
        "jobAccountNumber": 89,  // 🎯 Required for Step 8!
        "jobAccountName": "CONSTRUCTION PROJECT A"
      },
      {
        "jobAccountNumber": 90,  // 🎯 Multiple job accounts possible
        "jobAccountName": "REMODELING PROJECT B"
      }
    ]
  }
]

Critical Fields:

jobAccountNumber: Required for order submission in Step 8 (numeric value)
branchCode: Branch identifier for product/pricing queries
distanceFromShipToInMiles: Helps select nearest branch
jobAccounts: Array - customers can have multiple job accounts per branch

Save this: Store the jobAccountNumber from the desired job account - you'll need it for Step 8! Note: It's a numeric value, not a string.

Step 6: Get Available Products at Branch

❓ Why This Step Matters - Click to expand

Critical Information:

🏪 Branch-specific inventory - Not all products at all branches

🎨 Product variants - Colors, sizes, options

📏 Units of measure - SQ (Square), BD (Bundle), PC (Piece), etc.

🔄 Substitution rules - Whether alternatives allowed

Without this step:

❌ May request unavailable products

❌ Wrong unit of measure causes errors

❌ Can't show product options to users

❌ Miss substitution opportunities

Real-World Example:

A roofing shingle may be available in 15 colors at one branch but only 8 colors at another. This endpoint tells you exactly what's available where.

💡 Best Practices for Step 6

Caching Strategy:

✅ Cache product catalog per branch for 4-8 hours

✅ Refresh during off-peak hours (e.g., midnight)

✅ Invalidate cache when "product not found" errors occur

✅ Consider CDN for product images

User Experience:

✅ Show product images when available (productImageUrl)

✅ Display manufacturer and features prominently

✅ Group by category for easier browsing

✅ Filter by primary items first

✅ Show "Allow Substitution" badge when true

✅ Let users search by product name or manufacturer

Performance Tips:

⚡ This endpoint can return hundreds of products

⚡ Implement pagination in your UI

⚡ Use lazy loading for product images

⚡ Consider filtering by category first

⚡ Index products locally for fast search

Data Quality:

⚠️ Some products may have null images

⚠️ Product options can vary by variant

⚠️ UOM array may differ from variant UOM

⚠️ Always validate UOM before price request

API Call

Endpoint: GET /branches/v2/activeBranchProducts/{branchCode}

Example URL: https://services-qa.roofhub.pro/branches/v2/activeBranchProducts/ATL

Request Headers:

Authorization: Bearer {token}

Content-Type: application/json

Response Example

📋 Click to view response example

[
  {
    "productId": 6706,  // 🔑 Unique product identifier
    "productName": "Atlas GlassMaster 30 Shingles",  // 📦 Product display name
    "productOptions": [  // 🎨 Available color/size options
      "36\" x 12\" Black Shadow",
      "36\" x 12\" Hearthstone Gray",
      "36\" x 12\" Weathered Wood"
    ],
    "productVariant": [  // 🔄 Variants with UOM details
      {
        "variantId": 0,
        "selectedOption": "36\" x 12\" Black Shadow",
        "uoMs": ["SQ", "BD"]  // 📏 Available units of measure
      },
      {
        "variantId": 0,
        "selectedOption": "36\" x 12\" Hearthstone Gray",
        "uoMs": ["SQ", "BD"]
      },
      {
        "variantId": 0,
        "selectedOption": "36\" x 12\" Weathered Wood",
        "uoMs": ["BD", "SQ"]
      }
    ],
    "productDescription": "High-quality architectural shingles",  // 📝 Product description
    "productFeatures": [  // ✨ Key selling points
      "30-year warranty",
      "Wind resistance up to 130 mph",
      "Class A fire rating"
    ],
    "productUOM": ["SQ", "BD"],  // 📏 All available UOMs
    "productCategory": "Shingles",  // 🗂️ Category
    "manufacturer": "Atlas",  // 🏭 Manufacturer name
    "productImageUrl": "https://example.com/image.jpg",  // 🖼️ Product image (or null)
    "allowSubstitution": true,  // 🔄 Can substitute if out of stock
    "primaryItem": true  // ⭐ Is this the primary/default item
  },
  {
    "productId": 94860,
    "productName": "Atlas Pinnacle Impact IR Shingle",
    "productOptions": [
      "14\" x 42\" Desert Shake",
      "14\" x 42\" Weathered Wood"
    ],
    "productVariant": [
      {
        "variantId": 0,
        "selectedOption": "14\" x 42\" Desert Shake",
        "uoMs": ["BD"]
      },
      {
        "variantId": 0,
        "selectedOption": "14\" x 42\" Weathered Wood",
        "uoMs": ["BD"]
      }
    ],
    "productDescription": "Impact-resistant shingles with IR technology",
    "productFeatures": [
      "Impact resistant",
      "Energy efficient",
      "Premium warranty"
    ],
    "productUOM": ["BD"],
    "productCategory": "Shingles",
    "manufacturer": "Atlas",
    "productImageUrl": null,
    "allowSubstitution": false,
    "primaryItem": false
  }
]

Key Fields:

productId: Use this for pricing (Step 7) and order submission (Step 8)
productOptions: Available color/size variants
productVariant: Maps options to available UOMs
productUOM: Available units of measure (SQ=Square, BD=Bundle)
allowSubstitution: Whether alternative products can be substituted

Step 7: Get Real-Time Pricing & Availability

❓ Why This Step Matters - Click to expand

Critical Information:

💰 Customer-specific pricing - Prices vary by customer/contract

📦 Real-time availability - "In Stock" vs "Call for Availability"

🔄 UOM conversion - Handles unit conversions automatically

⏱️ Price validity - Prices change; always get fresh data

Without this step:

❌ Show wrong prices to customers

❌ Submit orders that will be rejected

❌ Can't display accurate stock status

❌ Miss pricing tiers and discounts

Real-World Scenario:

Customer A gets $12/ s q u a re f or p re mi u m s hin g l es (co n t r a c t orr a t e) . C u s t o m er Bp a ys$ 18/square (standard rate). Same product, different pricing!

💡 Best Practices for Step 7

When to Call Pricing API:

✅ Before checkout - Always get fresh pricing

✅ When quantity changes - Check for volume discounts

✅ When UOM changes - Validate conversion factors

✅ Before order submission - Final price confirmation

❌ Not on every page load - Cache for short period (5-10 minutes)

Caching Strategy:

⚡ Cache pricing for 5-10 minutes max

⚡ Cache per customer + branch + product combination

⚡ Invalidate on quantity/UOM changes

⚡ Always refresh before final order submission

⚡ Show "Price as of [timestamp]" to users

Batch Requests:

✅ Request pricing for multiple products in one call

✅ Recommended batch size: 20-50 products

✅ Larger quotes: Break into multiple batches

✅ Process batches in parallel for speed

Error Handling:

messageCode	Meaning	Action
`0`	Success	Proceed with order
`> 0`	Warning/Error	Check `message` field
`price = 0`	No pricing	Contact SRS or choose different product
`availableStatus = "Call"`	Limited stock	Warn user, allow order

UOM Conversion:

Display to Users:

✅ Show price with UOM: "$45.00 per SQ"

✅ Show availability status clearly

✅ Indicate if "Call for Availability" required

✅ Show quantity discounts if applicable

✅ Display "Price subject to change" disclaimer

API Call

Endpoint: POST /products/v2/price

Request Headers:

Authorization: Bearer {token}

Content-Type: application/json

Request Body

Click to expand: Full request body example below

📋 Click to view request body example

{
  "sourceSystem": "SOURCENAME",  // 🔑 Your integration identifier
  "customerCode": "DEMO001",  // 👤 Customer account number
  "branchCode": "HWPLY",  // 🏪 Branch code
  "transactionId": "SPR-1",  // 🎯 Unique transaction ID
  "jobAccountNumber": 1,  // 🔑 Job account number (numeric)
  "productList": [
    {
      "productId": 77673,  // 📦 Product ID from Step 6
      "productName": "Ace Insulation Plates",
      "productOptions": ["N/A"],
      "quantity": 1,
      "uom": "PC"
    }
  ]
}

Response Example

📋 Click to view response example

[
  {
    "itemCode": "ACEACEPLT3INI",  // 🔑 Internal item code
    "productId": 77673,  // 📦 Matches request product ID
    "productName": "Ace Insulation Plates",  // 📝 Product name
    "productOptions": ["N/A"],  // 🎨 Selected options
    "priceUOM": "PC",  // 📏 Base unit of measure for pricing
    "requestedUOM": "PC",  // 📏 Requested unit of measure
    "uomConversionFactor": 1,  // 🔄 Conversion factor (1 = no conversion)
    "price": 0.25,  // 💰 CRITICAL - Unit price for this customer
    "availableStatus": "Call for Availability",  // ✅ Stock status
    "transactionId": "SPR-1",  // 🎯 Matches request transaction ID
    "message": "",  // 📢 Additional messages (empty if no issues)
    "messageCode": 0  // 🔢 Message code (0 = success)
  }
]

Critical Fields:

price: Current unit price for this customer
availableStatus: Stock availability ("In Stock", "Call for Availability", etc.)
priceUOM: Base unit of measure for pricing
uomConversionFactor: Conversion multiplier between requested and price UOM
messageCode: 0 = success, other values indicate warnings/errors

Important: Prices are valid only at the time of the call. Get fresh pricing before order submission.

Step 8: Submit Order

❓ Understanding Order Submission - Click to expand

Synchronous vs Asynchronous

Key Differences:

Aspect	Synchronous	Asynchronous
Processing	Immediate	Queued
Response Time	1-3 seconds	Instant (queued)
Order ID	Immediate	Via webhook later
During Maintenance	❌ May fail	✅ Queued safely
Retry Logic	Manual	Automatic
Best For	Testing, low volume	Production, high volume
Webhook Required	No	Yes
Reliability	Medium	High

When to Use Each Method

Use Synchronous when:

🧪 Testing in Staging (required)

👶 Proof-of-concept/demo

📉 < 50 orders per day

⏱️ Need immediate confirmation

🚧 Can't implement webhooks yet

Use Asynchronous when:

🚀 Production deployment

📈 50+ orders per day

🔒 Maximum reliability required

⚙️ Can handle webhooks

🏭 Multiple integration points

💡 Want automatic retry on failures

Order Processing Flow

Staging vs Production Submission

Important: Staging environment supports synchronous orders only. Use synchronous submission for all testing.

Staging Environment (Testing)

Use synchronous order submission
Immediate response with Order ID
Perfect for development and testing
No webhook setup required

Production Environment (Live Orders)

Asynchronous submission recommended
Requires webhook endpoint setup
More reliable for production workloads
Orders processed even during maintenance

Synchronous (Staging & Production)	Asynchronous (Production Only - Recommended)
How it works: Order processed immediately Instant Order ID response Best for: Staging environment testing Low-volume integrations Simple implementations	How it works: Order queued for processing Status updates via webhooks Best for: Production deployments High-volume integrations Maximum reliability Requires webhook setup

Order Submission

Endpoint: POST /orders/v2/submit

Request Headers:

Authorization: Bearer {token}

Content-Type: application/json

Note: Order is processed synchronously in Staging, asynchronously in Production (based on configuration). There is no async flag in the request.

Request Body

Click to expand: Full request body example below

📋 Click to view full request body example

{
  "sourceSystem": "SOURCENAME",  // 🔑 REQUIRED - Your integration identifier
  "customerCode": "DEMO001",  // 🔑 REQUIRED - From Step 3
  "jobAccountNumber": 1,  // 🔑 REQUIRED - Numeric value from Step 5!
  "branchCode": "BRRIV",  // 🔑 REQUIRED - Branch code
  "accountNumber": "DEMO001",  // 🔑 REQUIRED - Customer account number
  "transactionID": "3932cdd6-38e7-4d19-a05c-cd866473bdea",  // 🔑 REQUIRED - Unique transaction ID
  "transactionDate": "2023-05-11T10:49:34.187",  // 🔑 REQUIRED - ISO 8601 format
  "notes": "",  // 🔑 REQUIRED - Order notes (can be empty string)
  "shipTo": {  // 🔑 REQUIRED - Ship-to address
    "name": "John",  // 🔑 REQUIRED
    "addressLine1": "1234 COUNTY LINE ROAD",  // 🔑 REQUIRED
    "addressLine2": "",  // 🔑 REQUIRED (can be empty)
    "addressLine3": "",  // 🔑 REQUIRED (can be empty)
    "city": "ONTARIO",  // 🔑 REQUIRED
    "state": "NY",  // 🔑 REQUIRED
    "zipCode": "14519"  // 🔑 REQUIRED
  },
  "poDetails": {  // 🔑 REQUIRED - PO and delivery details
    "poNumber": "5641-8Test",  // 🔑 REQUIRED - Purchase order number
    "reference": "5641: 7GP",  // 🔑 REQUIRED - Reference (can be empty)
    "jobNumber": "",  // 🔑 REQUIRED - Job number (can be empty)
    "orderDate": "2021-04-12",  // 🔑 REQUIRED - Order date (YYYY-MM-DD)
    "expectedDeliveryDate": "2021-04-15",  // 🔑 REQUIRED - Delivery date (YYYY-MM-DD)
    "expectedDeliveryTime": "Anytime",  // 🔑 REQUIRED - Delivery time (can be "Anytime")
    "orderType": "WHSE",  // 🔑 REQUIRED - "WHSE" (delivery) or "WILLCALL" (pickup)
    "shippingMethod": "Ground Drop"  // 🔑 REQUIRED - Shipping method
  },
  "orderLineItemDetails": [  // 🔑 REQUIRED - Line items array
    {
      "productId": 75664,  // 🔑 REQUIRED - Product ID from Step 6
      "productName": "CertainTeed Presidential Solaris Shingles",  // 🔑 REQUIRED - Product name
      "option": "Country Gray",  // 🔑 REQUIRED - Selected color/option
      "quantity": 1,  // 🔑 REQUIRED - Quantity (integer)
      "price": 12,  // 🔑 REQUIRED - Price (integer)
      "customerItem": "XXXX",  // 🔑 REQUIRED - Customer reference
      "uom": "SQ"  // 🔑 REQUIRED - Unit of measure
    },
    {
      "productId": 1443,
      "productName": "CertainTeed Landmark Solaris Non-AR Shingles",
      "option": "Burnt Sienna",
      "quantity": 1,
      "price": 12,
      "customerItem": "XXXX",
      "uom": "SQ"
    },
    {
      "productId": 75621,
      "productName": "CertainTeed SwiftStart Starter",
      "option": "N/A",
      "quantity": 1,
      "price": 12,
      "customerItem": "XXXX",
      "uom": "BD"
    }
  ],
  "customerContactInfo": {  // 🔑 REQUIRED - Customer contact details
    "customerContactName": "John Dough",  // 🔑 REQUIRED - Contact name
    "customerContactPhone": "9876543210",  // 🔑 REQUIRED - Phone number
    "customerContactEmail": "jdough@example.com",  // 🔑 REQUIRED - Email
    "customerContactAddress": {  // 🔑 REQUIRED - Contact address
      "addressLine1": "123 Main St",
      "city": "Salt Lake City",
      "state": "Utah",
      "zipCode": "84121"
    },
    "additionalContactEmails": [  // 🔑 REQUIRED - Additional emails array (can be empty)
      "test@example.com"
    ]
  }
}

Important: All fields marked as REQUIRED in the API must be provided. Some fields can be empty strings ("") but must be present in the request.

🚨 Common Order Submission Errors - Click to expand

Error 1: Missing Required Field

Symptom: 400 Bad Request - Missing required field: jobAccountNumber

Cause: Required field not included or null

Solution:

// ❌ Wrong
{
  "customerCode": "DEMO001"
  // jobAccountNumber missing
}

// ✅ Correct
{
  "customerCode": "DEMO001",
  "jobAccountNumber": 1  // Required numeric value
}

Error 2: Invalid Job Account Number

Symptom: Order submission failed - Invalid job account

Cause: Using wrong jobAccountNumber or string instead of number

Solution:

// ❌ Wrong - String value
{
  "jobAccountNumber": "1"  // Wrong: string
}

// ❌ Wrong - Non-existent number
{
  "jobAccountNumber": 999  // Doesn't exist for this customer
}

// ✅ Correct - Valid numeric value from Step 5
{
  "jobAccountNumber": 43  // From customerBranchLocations response
}

Error 3: Invalid Product ID

Symptom: Product not found at branch

Cause: Product ID doesn't exist or not available at this branch

Solution:

✅ Get product IDs from Step 6 (activeBranchProducts)

✅ Verify product is available at the selected branch

✅ Double-check productId is numeric, not string

Error 4: Invalid Date Format

Symptom: Invalid date format

Cause: Wrong date format in orderDate or expectedDeliveryDate

Solution:

// ❌ Wrong formats
{
  "orderDate": "04/12/2021",  // MM/DD/YYYY not accepted
  "expectedDeliveryDate": "2021.04.15"  // Wrong separator
}

// ✅ Correct format: YYYY-MM-DD
{
  "orderDate": "2021-04-12",
  "expectedDeliveryDate": "2021-04-15"
}

Error 5: Invalid Order Type

Symptom: Invalid orderType value

Cause: Wrong orderType or shippingMethod

Solution:

// ❌ Wrong
{
  "orderType": "Delivery",  // Wrong: must be code
  "shippingMethod": "Ground"  // Incomplete
}

// ✅ Correct
{
  "orderType": "WHSE",  // For delivery (or "WILLCALL" for pickup)
  "shippingMethod": "Ground Drop"  // From branch shippingMethods array
}

Error 6: Price Mismatch

Symptom: Price validation failed

Cause: Submitted price doesn't match current pricing

Solution:

✅ Always get fresh pricing from Step 7 before submission

✅ Don't cache prices for > 10 minutes

✅ Use exact price from pricing API response

✅ Check for price decimal vs integer (API expects integer: 12 not 12.00)

Error 7: Address Validation Failed

Symptom: Invalid shipping address

Cause: Missing or invalid address fields

Solution:

// ✅ All fields required (can be empty string but must exist)
{
  "shipTo": {
    "name": "John Doe",  // Required
    "addressLine1": "123 Main St",  // Required
    "addressLine2": "",  // Required (can be empty)
    "addressLine3": "",  // Required (can be empty)
    "city": "Denver",  // Required
    "state": "CO",  // Required (2-letter code)
    "zipCode": "80202"  // Required (5 or 9 digits)
  }
}

✅ Order Submission Checklist - Click to expand

Before Submitting:

Have valid jobAccountNumber from Step 5

Product IDs verified from Step 6

Fresh pricing obtained from Step 7 (< 10 min old)

All required fields populated

Date formats correct (YYYY-MM-DD)

Prices are integers, not decimals

Ship-to address is complete

Customer contact info included

PO number is unique

Transaction ID is unique

Field Validation:

jobAccountNumber is numeric (not string)

orderType is "WHSE" or "WILLCALL"

shippingMethod matches branch available methods

quantity are integers

price are integers (e.g., 12 not 12.00)

state is 2-letter code ("CO" not "Colorado")

UOM matches product available UOMs

After Submission:

Save orderID from response

Save transactionID from response

Log queueID if async

Set up webhook listener (Production)

Display confirmation to user

Store order in your database

Successful Response (200 OK)

📋 Click to view response example

{
  "message": "Order Submitted",  // ✅ Order successfully submitted
  "transactionID": "ANY-UNIQUE-STRING-02.19.2024.v2.4",  // 🎯 Your unique transaction ID (matches request)
  "orderID": "35818786",  // 🔑 SAVE THIS! - SRS order ID for tracking
  "queueID": "queue-abc123"  // 🔄 Queue identifier (null for sync, value for async)
}

Response Fields:

message - Confirmation message
transactionID - Your unique transaction ID (from request)
orderID - SRS order identifier - Use this to track order status via API or webhooks
queueID - Queue identifier (null for synchronous, has value for asynchronous processing)

Production Recommendation: Use asynchronous orders with webhooks. Contact SRS API Support Team to:

Request Production credentials
Provide webhook endpoint URLs
Schedule Production deployment

See Webhook Setup Guide for implementation details.

Order Confirmation: Customers receive a confirmation email with order number, delivery information, line items, and branch contact details.

🎉 You're Ready!

You've learned the complete integration flow! You can now:

✅ Validate customers

✅ Find customer branches and job accounts

✅ Browse available products

✅ Get real-time pricing

✅ Submit orders (sync and async)

🏆 Integration Milestones Achieved - Click to expand

Technical Skills Mastered:

✅ Complete 8-step SRS integration flow

✅ Customer validation and branch discovery

✅ Product catalog navigation

✅ Dynamic pricing retrieval

✅ Order payload construction

✅ Synchronous and asynchronous submission

✅ Webhook notification handling (design)

Business Capabilities Unlocked:

🚀 Automated order processing

🚀 Real-time inventory visibility

🚀 Customer-specific pricing

🚀 Multi-branch support

🚀 Scalable order submission

🚀 Production-ready architecture

What You Can Build Now:

🛠️ E-commerce checkout integration

🛠️ Mobile app order submission

🛠️ ERP/CRM synchronization

🛠️ Bulk order processing systems

🛠️ Customer self-service portals

🛠️ Automated reordering systems

📊 Performance Metrics to Track - Click to expand

Key Performance Indicators:

Metric	Target	How to Measure
API Response Time	< 500ms avg	Log timestamps per request
Order Success Rate	> 99%	(Successful / Total) * 100
Authentication Failures	< 0.1%	401 errors / total requests
Price Cache Hit Rate	> 80%	Cached / Total price requests
Token Refresh Rate	≈ 1/day	Token refresh events per day
Order Processing Time	< 5 sec (sync)	Submit to confirmation time
Webhook Delivery	< 30 sec	Event to webhook receipt time

Monitoring Setup:

AlertingThresholds:

🚨 Response time > 2 seconds

🚨 Error rate > 5%

🚨 Authentication failures > 1%

🚨 No orders in last 1 hour (if expecting traffic)

✨ Next Level: Production Optimization - Click to expand

Immediate Optimizations (Week 1):

✅ Implement token caching and auto-refresh

✅ Add comprehensive error logging

✅ Set up monitoring dashboard

✅ Create order confirmation emails

✅ Implement retry logic for transient failures

Short-term Improvements (Week 2-4):

✅ Set up webhook endpoints

✅ Implement asynchronous order processing

✅ Add product catalog caching

✅ Create customer-facing order tracking

✅ Build admin dashboard for order management

Long-term Enhancements (Month 2+):

🚀 Implement predictive ordering

🚀 Add ML-based product recommendations

🚀 Build analytics and reporting

🚀 Create mobile app integration

🚀 Develop multi-warehouse optimization

🚀 Implement automated reordering

Production Readiness Checklist:

All Staging tests passing

Error handling comprehensive

Monitoring and alerting configured

Webhook endpoints production-ready

Documentation updated

Team trained on system

Rollback plan documented

Production credentials obtained

Security audit completed

Load testing performed

🎯 Next Steps

🔔 Setup Webhooks for Production - Click to expand

Why Webhooks Matter:

✅ Real-time order status updates

✅ No polling required

✅ Reduced API calls

✅ Better user experience

✅ Automatic retry on delivery failure

Webhook Events You'll Receive:

Event	Description	When Triggered
`order.queued`	Order accepted to queue	Immediately after submission
`order.processing`	Order being prepared	When warehouse starts
`order.shipped`	Order dispatched	When truck leaves
`order.delivered`	Order completed	Upon delivery
`order.error`	Order failed	If processing error
`order.cancelled`	Order cancelled	If customer/SRS cancels

Webhook Payload Example:

{
  "eventType": "order.shipped",
  "orderID": "35818786",
  "transactionID": "YOUR-TRANSACTION-ID",
  "status": "SHIPPED",
  "timestamp": "2026-02-27T14:30:00Z",
  "trackingNumber": "1Z999AA10123456784",
  "carrier": "UPS",
  "estimatedDelivery": "2026-02-28"
}

Implementation Checklist:

Create webhook endpoint in your system

Implement signature verification

Handle all event types

Return 200 OK within 5 seconds

Implement idempotency (handle duplicates)

Add error logging

Test with webhook.site first

Provide URL to SRS API Support

Next: Read Webhook Setup Guide for complete implementation details.

⚠️ Error Handling Best Practices - Click to expand

Implement Retry Logic:

Error Categories:

Error Type	HTTP Code	Retry?	Action
Validation Errors	400	No	Fix request and resubmit
Authentication	401	Yes (once)	Refresh token and retry
Forbidden	403	No	Contact SRS support
Not Found	404	No	Verify endpoint URL
Rate Limit	429	Yes	Wait and retry with backoff
Server Error	500	Yes	Retry with exponential backoff
Service Unavailable	503	Yes	Retry after delay

Logging Best Practices:

Next: Read Error Handling Guide for comprehensive strategies.

🚀 Production Deployment Checklist - Click to expand

Pre-Deployment (Week Before):

All Staging tests passing (100+ test orders)

Error handling comprehensive

Logging and monitoring configured

Token refresh automation working

Webhook endpoints tested and verified

Load testing completed (2x expected volume)

Security audit passed

Team training completed

Documentation updated

Rollback plan documented

Request Production Access:

Email SRS API Support for Production credentials

Provide Production webhook URLs

Confirm expected order volume

Schedule deployment window

Request Production customer test accounts

Deployment Day:

Deploy code to Production environment

Update credentials (environment variables)

Verify webhook endpoints accessible

Submit 1-2 test orders

Verify webhook delivery

Monitor logs for errors

Gradual rollout (10% → 50% → 100%)

Post-Deployment (First Week):

Monitor error rates (< 1% target)

Track API response times (< 500ms avg)

Verify webhook delivery (< 30sec)

Review customer feedback

Optimize based on metrics

Document lessons learned

Monitoring Dashboards:

📏 Orders submitted per hour

📏 Success rate (target > 99%)

📏 Average response time

📏 Error rate by type

📏 Webhook delivery latency

📏 Token refresh events

Alerting Thresholds:

🚨 Error rate > 5%

🚨 Response time > 2 seconds

🚨 No orders in 1 hour (during business hours)

🚨 Webhook delivery failure

🚨 Authentication failures > 1%

📊 Success Metrics & KPIs - Click to expand

Track These Metrics:

Operational Metrics:

Orders submitted per day/week/month

Order success rate (target: > 99%)

Average order value

Average items per order

Most ordered products

Peak order times

Performance Metrics:

API response time (target: < 500ms)

Order processing time (target: < 5 sec sync)

Webhook delivery time (target: < 30 sec)

Cache hit rates (target: > 80%)

Token refresh frequency (target: ~1/day)

Quality Metrics:

Error rate (target: < 1%)

Customer complaint rate

Order accuracy rate

Address validation errors

Price discrepancies

Business Impact:

Time saved vs manual ordering

Labor cost reduction

Order processing cost per order

Customer satisfaction score

Integration ROI

Reporting Dashboard Example:

📏 Integration Health Dashboard
──────────────────────────────
Today's Orders:        157  (↑ 12% vs yesterday)
Success Rate:        99.4%  (🜢 Target: 99%)
Avg Response Time:    342ms (✅ Target: <500ms)
Webhook Delivery:      28s  (✅ Target: <30s)
Errors (24h):           1  (✅ Target: <2%)

Top Products:
  1. Shingles (45%)
  2. Underlayment (22%)
  3. Flashing (18%)
  
Peak Hours: 9-11 AM, 2-4 PM

🎯 Next Steps

Setup Webhooks

Learn how to receive real-time order status updates for asynchronous orders.

Error Handling

Learn how to handle common errors and edge cases.

Best Practices

Optimize your integration for production use.

Need Help?

📧 Contact SRS API Support - Click to expand

Email: APISupportTeam@srsdistribution.com

Include:

✅ Your client ID (NOT the secret!)

✅ Environment (Staging/QA or Production)

✅ Error details or question

✅ Request/response examples (sanitized)

✅ Transaction ID (if applicable)

✅ Steps to reproduce

Response time:

📅 Standard: 1-2 business days

🚨 Urgent (Production): Same day

Urgent Issues:

🚨 Production outages

🚨 Order processing failures

🚨 Authentication problems affecting customers

🚨 Security incidents

📚 Additional Resources - Click to expand

Guides:

📖 Webhook Setup Guide - Real-time updates

📖 Error Handling Guide - Comprehensive error strategies

📖 Best Practices Guide - Production optimization

📖 FAQ - Frequently asked questions

Code Examples:

💻 JavaScript/Node.js complete integration

💻 Python integration samples

💻 C# / .NET integration examples

💻 PHP integration code

💻 Java Spring Boot examples

Tools:

🔧 APIdog Interactive Docs - Test API live

🔧 Postman Collection - Pre-configured requests

🔧 Webhook.site - Test webhooks

🔧 Sample Payloads - Ready-to-use JSON

Videos:

🎥 Complete Order Flow Tutorial (25 min)

🎥 Webhook Implementation (15 min)

🎥 Production Deployment (30 min)

🎥 Troubleshooting Common Issues (20 min)

❓ Common Questions - Click to expand

Q: How many products can I include in one order?

A: Recommended maximum is 500 line items per order. For larger orders, split into multiple orders.

Q: Can I modify an order after submission?

A: No, orders cannot be modified after submission. You must contact SRS support to cancel and resubmit if needed.

Q: What's the difference between jobAccountNumber and accountNumber?

accountNumber = Customer account identifier (from Step 3)

jobAccountNumber = Specific job/project within that account (from Step 5)

Q: Why are prices integers instead of decimals?

A: The API expects prices as integers (e.g., 12 not 12.00). This is by design to avoid floating-point precision issues.

Q: Can I submit orders to multiple branches in one request?

A: No, each order is for a single branch. Submit separate orders for multiple branches.

Q: How long does synchronous order processing take?

A: Typically 1-3 seconds for validation and response. Actual fulfillment happens asynchronously afterward.

Q: What happens if my webhook endpoint is down?

A: SRS will retry delivery with exponential backoff. You can also poll for order status via API.

Q: Can I use my own product SKUs instead of SRS product IDs?

A: Not directly. You need to maintain a mapping between your SKUs and SRS product IDs obtained from Step 6.

Q: What date format should I use for orderDate?

A: Always use YYYY-MM-DD format (e.g., "2026-02-27").

Q: Can I test order submission without actually creating orders?

A: Yes! Use the Staging/QA environment - orders there don't affect production inventory or create real orders.

More questions? Check our FAQ or contact support.

Need Help?

Email: APISupportTeam@srsdistribution.com

Include: Your client ID, environment, error details, and request/response examples

Response time: 1-2 business days

You're ready for production!

📝 Quick Reference: Steps 5-8 Cheat Sheet - Click to expand

Order Flow at a Glance

5. GET CUSTOMER BRANCHES
   ↓
   GET /branches/v2/customerBranchLocations/{code}
   ↓
   Save: jobAccountNumber (REQUIRED for Step 8!)

6. GET PRODUCTS
   ↓
   GET /branches/v2/activeBranchProducts/{branchCode}
   ↓
   Save: productId, productUOM

7. GET PRICING
   ↓
   POST /products/v2/price
   Body: { customerCode, branchCode, productList }
   ↓
   Save: price, availableStatus

8. SUBMIT ORDER
   ↓
   POST /orders/v2/submit
   Body: { All required fields from Steps 1-7 }
   ↓
   Receive: orderID, transactionID
   ↓
   🎉 SUCCESS!

Quick Command Reference

Critical Fields by Step

Step	Save This	Type	Example	Use In
5	`jobAccountNumber`	number	`43`	Step 8
5	`branchCode`	string	`"BRRIV"`	Steps 6,7,8
6	`productId`	number	`75664`	Steps 7,8
6	`productUOM`	array	`["SQ","BD"]`	Steps 7,8
7	`price`	number	`12`	Step 8
7	`availableStatus`	string	`"In Stock"`	Display
8	`orderID`	string	`"35818786"`	Tracking

Data Flow Diagram

Step 3 (Auth Guide)          Step 5
┌────────────────┐       ┌────────────────┐
│ customerCode   │─────▶│ jobAccountNum  │
│ accountNumber  │       │ branchCode     │─────▼
└────────────────┘       └────────────────┘
                            │
                   Step 6   │   Step 7
                 ┌─────────┘─────────┐
                 │ productId      │
                 │ productUOM     │────▶┌───────────┐
                 └──────────────────┘     │ price     │
                                      │ available │
                                      └──────┬─────┘
                                             │
                                    Step 8   ▼
                                      ┌───────────┐
                                      │ ALL DATA  │
                                      │ Submit!   │
                                      └──────┬─────┘
                                             │
                                             ▼
                                      ┌───────────┐
                                      │ orderID   │
                                      │ 🎉 SUCCESS │
                                      └───────────┘

Common Pitfalls to Avoid

❌ Using jobAccountNumber as string instead of number

❌ Not getting fresh pricing before order submission

❌ Using wrong date format (must be YYYY-MM-DD)

❌ Forgetting required empty fields (addressLine2, addressLine3)

❌ Price as decimal instead of integer

❌ Product ID from wrong branch

❌ Not validating UOM from product list

❌ Missing transactionID uniqueness

Success Criteria

✅ Can retrieve customer branches
✅ Can browse products at any branch
✅ Can get real-time pricing
✅ Can submit valid orders
✅ Receive order confirmation
✅ Error handling working
✅ Ready for webhook implementation

🛠️ Order Payload Template Generator - Click to expand

Minimal Valid Order (Copy & Customize)

{
  "sourceSystem": "YOUR_SYSTEM_NAME",
  "customerCode": "FROM_STEP_3",
  "jobAccountNumber": 0,  // FROM_STEP_5 - NUMERIC!
  "branchCode": "FROM_STEP_5",
  "accountNumber": "FROM_STEP_3",
  "transactionID": "UNIQUE_ID_" + Date.now(),
  "transactionDate": new Date().toISOString(),
  "notes": "Test order",
  
  "shipTo": {
    "name": "Customer Name",
    "addressLine1": "123 Main St",
    "addressLine2": "",
    "addressLine3": "",
    "city": "City",
    "state": "ST",
    "zipCode": "12345"
  },
  
  "poDetails": {
    "poNumber": "PO-" + Date.now(),
    "reference": "Ref 123",
    "jobNumber": "Job 456",
    "orderDate": "2026-02-27",
    "expectedDeliveryDate": "2026-03-01",
    "expectedDeliveryTime": "Anytime",
    "orderType": "WHSE",
    "shippingMethod": "Ground Drop"
  },
  
  "orderLineItemDetails": [
    {
      "productId": 0,  // FROM_STEP_6
      "productName": "FROM_STEP_6",
      "option": "FROM_STEP_6",
      "quantity": 1,
      "price": 0,  // FROM_STEP_7 - INTEGER!
      "customerItem": "Your SKU",
      "uom": "FROM_STEP_6"  // Must be valid for product
    }
  ],
  
  "customerContactInfo": {
    "customerContactName": "Contact Name",
    "customerContactPhone": "1234567890",
    "customerContactEmail": "email@example.com",
    "customerContactAddress": {
      "addressLine1": "123 Contact St",
      "city": "City",
      "state": "ST",
      "zipCode": "12345"
    },
    "additionalContactEmails": []
  }
}

Field Validation Checklist

Before populating template:

Replace ALL "FROM_STEP_X" placeholders

jobAccountNumber is number, not string

productId is number, not string

quantity is integer

price is integer (12 not 12.00)

Dates are "YYYY-MM-DD" format

state is 2-letter code

All required empty strings present

transactionID is unique

poNumber is unique

UOM matches product available UOMs

orderType is "WHSE" or "WILLCALL"

You're ready for production!

Order Flow Tutorial

Order Flow Tutorial - Complete Implementation Guide#

🎯 What You'll Build#

🔄 Order Flow Overview#

Step 5: Find Customer Branches & Job Accounts#

API Call#

Response Example#

Step 6: Get Available Products at Branch#

API Call#

Response Example#

Step 7: Get Real-Time Pricing & Availability#

API Call#

Request Body#

Response Example#

Step 8: Submit Order#

Synchronous vs Asynchronous#

When to Use Each Method#

Order Processing Flow#

Staging vs Production Submission#

Order Submission#

Request Body#

Error 1: Missing Required Field#

Error 2: Invalid Job Account Number#

Error 3: Invalid Product ID#

Error 4: Invalid Date Format#

Error 5: Invalid Order Type#

Error 6: Price Mismatch#

Error 7: Address Validation Failed#

Successful Response (200 OK)#

🎉 You're Ready!#

🎯 Next Steps#

🎯 Next Steps#

Need Help?#

Need Help?#

Order Flow at a Glance#

Quick Command Reference#

Critical Fields by Step#

Data Flow Diagram#

Common Pitfalls to Avoid#

Success Criteria#

Minimal Valid Order (Copy & Customize)#

Field Validation Checklist#

Order Flow Tutorial - Complete Implementation Guide

🎯 What You'll Build

🔄 Order Flow Overview

Step 5: Find Customer Branches & Job Accounts

API Call

Response Example

Step 6: Get Available Products at Branch

API Call

Response Example

Step 7: Get Real-Time Pricing & Availability

API Call

Request Body

Response Example

Step 8: Submit Order

Synchronous vs Asynchronous

When to Use Each Method

Order Processing Flow

Staging vs Production Submission

Order Submission

Request Body

Error 1: Missing Required Field

Error 2: Invalid Job Account Number

Error 3: Invalid Product ID

Error 4: Invalid Date Format

Error 5: Invalid Order Type

Error 6: Price Mismatch

Error 7: Address Validation Failed

Successful Response (200 OK)

🎉 You're Ready!

🎯 Next Steps

🎯 Next Steps

Need Help?

Need Help?

Order Flow at a Glance

Quick Command Reference

Critical Fields by Step

Data Flow Diagram

Common Pitfalls to Avoid

Success Criteria

Minimal Valid Order (Copy & Customize)

Field Validation Checklist