1. Ordering

Order checkout integration event

The order checkout integration event enables customization of order total calculations, including taxes, shipping costs, fees, and promotion discounts. This feature recognizes that companies often have established requirements and existing relationships with third-party vendors for calculating these costs. Since there is no universal solution for these calculations, the integration provides flexibility to implement business-specific requirements.

Common scenarios

The integration addresses various business needs:

  1. Shipping cost variations:

    • Vendor-specific rates
    • Product type considerations
    • Packaging material requirements
    • Fulfillment-time factors

  2. Promotion management:

    • Item-specific discounts
    • Targeted price adjustments
    • Individual item vs. order-level promotions

  3. Tax handling:

    • Tax-exempt user groups
    • Multiple jurisdiction requirements
    • Special tax rules
    • Custom tax calculations

Integration overview

The integration connects your middleware application through predefined routes, providing control over order total calculations. The process includes:

  1. Cart management:

    • Item selection
    • Configuration options
    • Quantity adjustments

  2. Shipment organization:

    • Ship from address
    • Ship to address
    • Production lead time
    • Customer delivery requirements
    • Inventory availability
    • Fulfillment constraints

  3. Shipping options:

    • Method selection
    • Price comparison
    • Delivery time estimates
    • Service level options

  4. Cost calculations:

    • Tax computation
    • Line item pricing
    • Price break application
    • Promotion processing

Triggering behavior

The integration uses explicit triggering through POST /v1/orders/{direction}/{orderID}/calculate rather than automatic calculation. This approach provides several benefits:

  1. Performance optimization:

    • Prevents redundant calculations
    • Reduces API calls
    • Minimizes third-party service costs

  2. User experience:

    • Faster response times
    • Controlled calculation timing
    • Predictable behavior

  3. Resource management:

    • Efficient service usage
    • Controlled costs
    • Optimized processing

Security verification:

  • Each call includes X-oc-hash header
  • Signature uses integration event hash key
  • Validates serialized JSON payload
  • Uses HMACSHA256 encoding

Standard checkout flow

  1. Cart management:

    • Add items to order
    • Configure item options
    • Set quantities

  2. Address handling:

    • Set shipping addresses
    • Validate locations
    • Configure multiple addresses if needed

  3. Shipping estimation:

    POST /v1/orders/{direction}/{orderID}/estimateshipping
    • Retrieves available shipping methods
    • Calculates costs
    • Provides delivery estimates

  4. Method selection:

    • Present options to user
    • Show costs and transit times
    • Allow comparison

  5. Save shipping choices:

    POST /v1/orders/{direction}/{orderID}/shipmethods
    json
    {
  "ShipMethodSelections": [
    {
      "ShipEstimateID": "ShipEstimateID",
      "ShipMethodID": "ExampleShipMethod1"
    }
  ]
}

  6. Calculate totals:

    POST /v1/orders/{direction}/{orderID}/calculate
    • Computes all costs
    • Applies promotions
    • Validates totals

  7. Order submission:

    POST /v1/orders/{direction}/{orderID}/submit
    • Finalizes order
    • Triggers fulfillment
    • Processes payment

Important notes:

  • Order changes invalidate calculations
  • Recalculation required after changes
  • Changes include:
    • Shipping costs
    • Tax amounts
    • Promotion adjustments
    • Address updates
    • Quantity modifications
    • Unit price changes
    • Cost center updates
    • Order/line item XP changes

Order worksheet

The Order Worksheet serves as a comprehensive record of calculation data:

GET /v1/orders/{direction}/{orderID}/worksheet

Benefits:

  • Detailed cost breakdown
  • Tax calculation history
  • Shipping rate records
  • Promotion application details
  • Fee itemization
  • Historical reference
  • Audit trail
  • Refund calculation support

Implementation

Setup requirements:

  1. Integration configuration:

    • Create OrderCheckout Integration Event Type
    • Configure API Client connection
    • Set OrderCheckoutIntegrationEventID

  2. Endpoint hosting:

    • Implement required routes
    • Handle integration payloads
    • Process calculations
    • Return formatted responses

Standard payload structure:

json
{
  "ConfigData": {},  // Integration Event configuration
  "Environment": "Sandbox",
  "OrderCloudAccessToken": "eyJhbGciOiJSUzI1NiIsTdHJ5RDVEclEifQ...",
  "OrderWorksheet": {
    "LineItems": [],
    "Order": {},
    "OrderApprovedResponse": {},
    "OrderCalculateResponse": {},
    "OrderPromotions": [],
    "OrderSubmitForApprovalResponse": {},
    "OrderSubmitResponse": {},
    "ShipEstimateResponse": {}
  }
}

Integration endpoints

/ShippingRates

Triggered by: POST v1/orders/{direction}/{orderID}/estimateshipping

Purpose:

  • Calculate shipping options
  • Group items into shipments
  • Provide cost estimates
  • Define delivery timeframes

Response structure:

json
{
  "ShipEstimates": [
    {
      "ID": "ShipEstimateID",
      "SelectedShipMethodID": null,
      "ShipEstimateItems": [
        {
          "LineItemID": "SampleLineItemID",
          "Quantity": 1
        }
      ],
      "ShipMethods": [
        {
          "Cost": 10,
          "ID": "ExampleShipMethod1",
          "Name": "Example Shipping Method 1",
          "EstimatedTransitDays": 5,
          "xp": {}
        },
        {
          "Cost": 8,
          "ID": "ExampleShipMethod2",
          "Name": "Example Shipping Method 2",
          "EstimatedTransitDays": 7,
          "xp": {}
        }
      ],
      "xp": {}
    }
  ],
  "xp": {}
}

/OrderCalculate

Triggered by: POST v1/orders/{direction}/{orderID}/calculate

Purpose:

  • Calculate final totals
  • Apply tax rules
  • Process shipping costs
  • Handle fees
  • Override unit prices
  • Store calculation details

Response structure:

json
{
  "ShippingTotal": 10,
  "TaxTotal": 3,
  "FeeTotal": 0.42,
  "LineItemOverrides": [
    {
      "LineItemID": "SampleLineItemID",
      "UnitPrice": 6.00,
      "PromotionOverrides": [
        {
          "PromotionID": "SamplePromoID",
          "Amount": 3.00
        }
      ]
    }
  ],
  "xp": {
    "TaxBreakdown": {
      "LineItemID": "SampleLineItemID",
      "AvalaraReferenceID": "SampleReferenceID",
      "StateTax": 0.12,
      "CountyTax": 0.22,
      "MunicipalTax": 0
    },
    "FeeBreakdown": [
      {
        "LineItemID": "SampleLineItemID",
        "Name": "Facility Fee",
        "PerQuantity": true,
        "Amount": 0.05
      },
      {
        "LineItemID": "SampleLineItemID",
        "Name": "Tariff",
        "PerQuantity": true,
        "Amount": 0.37
      }
    ]
  }
}

Important: Middleware order updates must occur after sending the response to OrderCloud.

/OrderSubmit

Triggered by: POST v1/orders/{direction}/{orderID}/submit

Purpose:

  • Process final submission
  • Integrate with back-office systems
  • Initialize fulfillment
  • Record external references

Response structure:

json
{
  "xp": {
    "SomeKey": "SomeValue"
  }
}

/OrderSubmitForApproval

Triggered by: POST v1/orders/{direction}/{orderID}/submit

Purpose:

  • Handle approval workflow
  • Process pending orders
  • Notify approvers
  • Track approval status

Response structure:

json
{
  "xp": {
    "SomeKey": "SomeValue"
  }
}

/OrderApproved

Triggered by: POST v1/orders/{direction}/{orderID}/approve

Purpose:

  • Process approved orders
  • Initialize fulfillment
  • Update systems
  • Notify stakeholders

Response structure:

json
{
  "xp": {
    "SomeKey": "SomeValue"
  }
}
If you have suggestions for improving this article, let us know!