Skip to main content

Data Models

Understanding Karla's data structures and their relationships is essential for effective integration. This section provides comprehensive documentation of all data models, their properties, and how they interconnect.

Core Entities​

Karla's API is built around several core entities that represent different aspects of the post-purchase experience:

Primary Entities​

  • Shop - Your store configuration and settings
  • Order - Customer purchase information
  • Shipment - Delivery tracking and status
  • Campaign - Marketing campaigns during delivery

Supporting Models​

  • Customer - Customer profile and preferences
  • Product - Product information and variants
  • Address - Shipping and billing addresses
  • Event
    • Claim Event - Events happening on a claim
    • Shipment Event - Events happening on a shipment
  • Tracking - Simplified Shipment, specific to order trackings

Entity Relationships​

The diagram below shows how Karla's core entities relate to each other, with clear distinction between actors, entities, and data models:

System Components​

Actors (External Users)

  • Customer - Places orders and creates claims
  • Merchant Admin - Configures campaigns and shop settings

Core Entities (Business Objects)

  • Shop - Merchant's store container
  • Order - Customer purchases
  • Shipment - Package delivery with two states:
    • Draft: Expected package before carrier fulfillment
    • Fulfilled: Active package with carrier tracking
  • Campaign - Marketing promotions
  • Claim - Customer service requests

Data Models (Supporting Data)

  • Event - Tracking and system events
  • Product - Item information
  • Address - Shipping locations
  • Carrier - Delivery providers

Shipment vs Tracking Terminology​

In Karla's API, Shipment and Tracking refer to the same entity, with a few differences:

  • Shipment - This model has extensive data that is used beyond a tracking page.
  • Tracking - A subset of the Shipment data. It is nested inside an Order response, with a data model specific to show statuses in a tracking page.

Both represent the same package delivery entity and can be in either draft or fulfilled state.

Shipment States Explained​

The important distinction is between draft and fulfilled states:

Draft State​

  • Created when: Order is placed
  • Purpose: Show customers expected packages (you can set this in advance via API)
  • Has tracking number: No
  • Generates events: Only pre-in-transit events
  • Customer sees: "Your order will ship in X packages"

Fulfilled State​

  • Created when: A tracking number is added
  • Purpose: Real-time package tracking
  • Has tracking number: Yes
  • Generates events: All carrier tracking events
  • Customer sees: "Your package is in transit" with tracking details

Data Flow​

Understanding how data flows through Karla helps you build better integrations:

  1. Order Creation → Order entity created with customer and product data
  2. Draft Shipment Generation → Expected shipments created for customer visibility
  3. Shipment Fulfillment → Draft becomes tracking when first carrier scan occurs
  4. Event Tracking → Events generated as tracking progresses through delivery
  5. Campaign Triggering → Campaigns activate based on tracking events and segments
  6. Analytics Collection → Performance data aggregated for insights

Common Data Patterns​

Timestamps​

All timestamps in Karla use ISO 8601 format with timezone offset:

"created_at": "2024-01-29T14:48:47+00:00"

UUIDs​

Karla uses UUID v4 for all entity identifiers:

"uuid": "abc65a96-0871-452a-a506-c644e2012123"

External References​

Many entities include external IDs to link with your platform:

"external_id": "order_12345_from_shopify"

Shipment States​

Shipment entities use a clear state pattern:

  • draft - Expected shipment before fulfillment
  • fulfilled - Active tracking with carrier updates

Event Data​

All generic events (not specific to a third-party tool) follow a consistent structure with three main sections:

Event Metadata​

{
  "source": "shipments",
  "ref": "shipments/delivered/PARCEL_DELIVERED",
  "version": 1,
  "triggered_at": "2024-01-29T14:48:47+00:00"
}

Event-Specific Data​

{
  "event_data": {
    "shipment_id": "abc65a96-0871-452a-a506-c644e2012123",
    "carrier_reference": "dhl",
    "event_name": "DEPARTURE_FROM_TRANSPORT_HUB",
    "phase": "in_transit",
    "tracking_number": "0123456789",
    "tracking_url": "https://example.com/tracking",
    "updated_at": "2024-01-29T14:48:47+00:00",
    "event_group": "shipment_in_transit"
  }
}

Contextual Information​

Every event provides context of the models involved with it.

{
  "context": {
    "order": {
      /* Full order object */
    },
    "customer": {
      /* Customer information */
    },
    "shipments": [
      /* All related shipments */
    ],
    "claims": [
      /* All related claims */
    ]
  }
}

Next Steps​