Order Versioning

The Unified Order Service (UOS) provides comprehensive order version tracking. This guide explains how the versioning system works and how to use it.

How Order Versioning Works

Every time an order is created or updated, the UOS system:

  1. Assigns a new version number to the order
  2. Stores a complete snapshot of the order at that point in time
  3. Records metadata about what changed in this version
  4. Makes this history available through the API

This provides a complete audit trail of all changes made to an order throughout its lifecycle.

Accessing Order Version History

To view the complete version history of an order, send a GET request to the /v1/orders/{orderId}/history endpoint:

curl -X GET "https://api.uos.example.com/v1/orders/order-123/history" \
  -H "Authorization: Bearer YOUR_API_KEY"

The response will include metadata about each version:

{
  "order_id": "order-123",
  "current_version": 3,
  "created_at": "2023-06-01T12:00:00Z",
  "updated_at": "2023-06-01T14:30:00Z",
  "version_count": 3,
  "versions": [
    {
      "version": 1,
      "created_at": "2023-06-01T12:00:00Z",
      "changes": {
        "type": "created",
        "fields": ["all"]
      },
      "url": "/v1/orders/order-123/versions/1"
    },
    {
      "version": 2,
      "created_at": "2023-06-01T13:15:00Z",
      "changes": {
        "type": "status_updated",
        "fields": ["status"],
        "from": "pending",
        "to": "processing"
      },
      "url": "/v1/orders/order-123/versions/2"
    },
    {
      "version": 3,
      "created_at": "2023-06-01T14:30:00Z",
      "changes": {
        "type": "updated",
        "fields": ["shipping_info", "totals"]
      },
      "url": "/v1/orders/order-123/versions/3"
    }
  ]
}

Retrieving a Specific Order Version

To retrieve a specific version of an order, send a GET request to the /v1/orders/{orderId}/versions/{version} endpoint:

curl -X GET "https://api.uos.example.com/v1/orders/order-123/versions/2" \
  -H "Authorization: Bearer YOUR_API_KEY"

The response will include:

{
  "id": "version-record-id",
  "order_id": "order-123",
  "version": 2,
  "order_data": {
    // Complete order data at this version
  },
  "change_metadata": {
    "type": "status_updated",
    "fields": ["status"],
    "from": "pending",
    "to": "processing"
  },
  "created_at": "2023-06-01T13:15:00Z",
  "is_current_version": false
}

If you request the current version, the response will also include the current_order field with the full current order data.

Order Status History

The UOS system also provides a specialized endpoint for tracking only status changes. To view the chronological history of status changes for an order, send a GET request to the /v1/orders/{orderId}/status-history endpoint:

curl -X GET "https://api.uos.example.com/v1/orders/order-123/status-history" \
  -H "Authorization: Bearer YOUR_API_KEY"

The response will include all status transitions:

{
  "order_id": "order-123",
  "current_status": "processing",
  "status_changes": [
    {
      "id": "status-change-id-1",
      "from_status": null,
      "to_status": "pending",
      "changed_at": "2023-06-01T12:00:00Z",
      "changed_by": "api.create",
      "metadata": {}
    },
    {
      "id": "status-change-id-2",
      "from_status": "pending",
      "to_status": "processing",
      "changed_at": "2023-06-01T13:15:00Z",
      "changed_by": "user@example.com",
      "metadata": {
        "notes": "Order processing started"
      }
    }
  ]
}

Use Cases for Order Versioning

Audit Trails

Order versioning provides a complete audit trail of all changes, allowing you to see:

  • Who made each change
  • When each change was made
  • What was changed in each update

Dispute Resolution

If there's a discrepancy or dispute about an order, you can reference the version history to:

  • Confirm what the order contained at a specific point in time
  • Verify when and how order details were modified
  • Identify who made specific changes

Compliance

For regulatory compliance, order versioning helps:

  • Maintain records of all order modifications
  • Provide evidence for audits
  • Support data retention requirements

Business Analytics

Order version data can be used for business intelligence:

  • Analyze patterns in order modifications
  • Identify common order update scenarios
  • Measure time between order status changes

Best Practices

  • Reference version numbers in customer communications for clarity
  • Use the version history to understand the full context of an order
  • Always update orders through the API to ensure versioning is properly maintained
  • Consider version history when implementing order-related business logic
  • Combine version history with status history for complete order tracking
Last Updated: