# Karla Documentation

> **Last Updated**: 2025-11-06
> **API Version**: v1 (stable)
> **Documentation Source**: https://docs.gokarla.io

## What is Karla?

Karla is an API-first post-purchase experience platform that helps e-commerce businesses enhance their delivery tracking, customer communication, and post-purchase marketing. This documentation covers our complete API, integrations, and features.

## Getting Started

- [Get Started](https://docs.gokarla.io/docs/get-started): Quick introduction to Karla platform and step-by-step onboarding guide. Most merchants are operational within 30 minutes.

## Core Platform & API

- [Platform Overview](https://docs.gokarla.io/platform/): Developer resources hub with API references, data models, SDKs, and integration guides.
- [API Reference](https://docs.gokarla.io/api/v1): Complete interactive API documentation with live examples for all endpoints.

### Platform Features

- [Orders](https://docs.gokarla.io/platform/features/orders): Complete order management including placement, fulfillment, analytics, and attribution tracking.
- [Shipments](https://docs.gokarla.io/platform/features/shipments): Package tracking with draft and fulfilled states, carrier integration, and real-time updates across 1000+ carriers.
- [Events](https://docs.gokarla.io/platform/features/events): Comprehensive event system with 100+ event types for webhooks, triggers, and automation workflows.
- [Webhooks](https://docs.gokarla.io/platform/features/webhooks): Real-time HTTP notifications with security, filtering, and retry logic.
- [Campaigns](https://docs.gokarla.io/platform/features/campaigns): Post-purchase marketing campaign management with targeting, scheduling, and A/B testing.

## Customer Experience Products

### Tracking Pages

- [Tracking Page Overview](https://docs.gokarla.io/docs/tracking-page/overview): Branded tracking experience features and customization options.
- [Tracking Page Demo](https://docs.gokarla.io/docs/tracking-page/demo): Interactive demo of tracking page functionality.
- [Integrate Tracking Pages](https://docs.gokarla.io/docs/tracking-page/integrate-in-your-shop): Technical integration methods including embeds, redirects, and API.

### Campaigns

- [Campaigns Overview](https://docs.gokarla.io/docs/campaigns/overview): Post-purchase marketing strategies and campaign types.
- [Segmented Campaigns](https://docs.gokarla.io/docs/campaigns/segmented-campaigns): Advanced customer targeting with Klaviyo, Shopify, and custom segments.

### Resolve (Customer Self-Service)

- [Resolve Overview](https://docs.gokarla.io/docs/resolve/overview): Self-service customer support for delivery issues and claims management.
- [Resolve Demo](https://docs.gokarla.io/docs/resolve/demo): Interactive demo of resolution features.
- [Shop Connection](https://docs.gokarla.io/docs/resolve/shop-connection): Service desk integration and workflow automation.
- [Data Processing](https://docs.gokarla.io/docs/resolve/data-processing): How customer data is processed in resolve flows.
- [Embedding Options](https://docs.gokarla.io/docs/resolve/embedding-options): Technical integration guide for resolve flows.

### Notify

- [Disable Carrier Emails](https://docs.gokarla.io/docs/notify/how-to-switch-off-carrier-emails): Guide to preventing duplicate notifications from carriers.

## Shop Integrations

- [Shops Overview](https://docs.gokarla.io/docs/shop-integrations/overview): Introduction to e-commerce platform integrations.
- [Shopify Integration](https://docs.gokarla.io/docs/shop-integrations/shopify): Complete Shopify app setup, configuration, and custom property mapping.
- [Shopware Integration](https://docs.gokarla.io/docs/shop-integrations/shopware): Shopware plugin installation and configuration guide.
- [Headless Integration](https://docs.gokarla.io/docs/shop-integrations/headless): API-based integration patterns for custom and headless commerce platforms.
- [Customize Your Experience](https://docs.gokarla.io/docs/shop-integrations/customize-your-experience): Advanced customization options for integrations.

## Notification Integrations

Karla integrates with major email service providers and notification platforms:

- [Klaviyo Integration](https://docs.gokarla.io/docs/notify-integrations/klaviyo): Email and SMS automation with delivery events and customer segmentation.
- [Shopify Email](https://docs.gokarla.io/docs/notify-integrations/shopify): Native Shopify email notifications and Flow integration.
- [Shopware Email](https://docs.gokarla.io/docs/notify-integrations/shopware): Shopware native email integration.
- [WhatsApp](https://docs.gokarla.io/docs/notify-integrations/whatsapp): WhatsApp notification setup.
- [Inxmail](https://docs.gokarla.io/docs/notify-integrations/inxmail): Inxmail integration for email campaigns.
- [Emarsys](https://docs.gokarla.io/docs/notify-integrations/emarsys): Emarsys marketing automation integration.
- [Braze](https://docs.gokarla.io/docs/notify-integrations/braze): Braze customer engagement platform integration.
- [Brevo](https://docs.gokarla.io/docs/notify-integrations/brevo): Brevo (formerly Sendinblue) integration.
- [HubSpot](https://docs.gokarla.io/docs/notify-integrations/hubspot): HubSpot CRM and marketing automation integration.

## Carrier Integrations

- [DHL Integration](https://docs.gokarla.io/docs/carrier-integrations/dhl): DHL carrier-specific integration and features.

## AI Features

Karla provides AI-powered capabilities to enhance customer experience:

- [KarlaNXT Agent](https://docs.gokarla.io/platform/ai/karlanxt-agent): Intelligent AI chatbot that integrates with product catalogs, knowledge bases, and provides real-time order assistance.
- [Agent Toolkit](https://docs.gokarla.io/platform/ai/agent-toolkit): Tools and APIs for building custom AI agent integrations.
- [Model Context Protocol (MCP)](https://docs.gokarla.io/platform/ai/mcp): Standardized protocol for AI model integration and context sharing.

## Web SDK & Browser Integration

- [Browser SDK](https://docs.gokarla.io/platform/web/browser-sdk): JavaScript SDK for embedding Karla features into your website.

## Core Concepts & Data Models

### Order Lifecycle

Orders in Karla have two main states:
- **Placed**: Order accepted and paid but not shipped. Contains draft shipments showing expected packages.
- **Fulfilled**: Order dispatched to carrier with tracking numbers. Generates full carrier event tracking.

### Shipment States

- **Draft Shipment**: Created when order is placed. Shows customers expected packages without tracking numbers. Only generates pre-transit events.
- **Fulfilled Shipment**: Created when tracking number is added. Provides real-time package tracking with all carrier events.

### Shipment Phases

Shipments progress through these phases during delivery:
- **order_created**: Order placement and initial processing
- **order_processed**: Package preparation and carrier pickup
- **in_transit**: Package movement through carrier network
- **in_delivery**: Out for delivery and delivery attempts
- **collect**: Customer pickup from pickup points
- **delivered**: Successful delivery confirmations
- **delivery_failed**: Failed delivery attempts
- **returned**: Return to sender events
- **return_failed**: Failed return attempts

### Event System

Karla generates 100+ event types organized by:
- **Source**: shipments or claims
- **Ref Pattern**: `{source}/{phase}/{event_name}` for webhooks filtering
- **Event Groups**: Business-friendly names for marketing automation (Klaviyo-compatible)

Common event groups include:
- shipment_delivered, shipment_in_transit, shipment_out_for_delivery
- shipment_carrier_delay, shipment_damaged, shipment_delivery_failed
- claim_created, claim_updated

### Campaign Types

Three campaign types for post-purchase marketing:
- **Basic Campaign**: Simple promotional content with CTA
- **Product Campaign**: Multi-product recommendations with rich metadata
- **Banner Campaign**: High-impact promotional banners for sales events

Campaigns support:
- Customer segmentation (Klaviyo, Shopify, custom)
- Multi-language localization
- Scheduling and timing controls
- A/B testing and analytics

## API Integration Patterns

### Authentication

- **Basic Authentication**: Username and private API key in HTTP headers
- **Organization-level Keys**: Multi-shop access with single credential
- **User Permissions**: Admin (read/write) vs Viewer (read-only) access

### Webhook Security

All webhooks include security features:
- `Karla-Signature` headers for HMAC-SHA256 verification
- Timestamp verification for replay attack prevention
- Automatic retry with exponential backoff (up to 15 attempts)
- 10-second timeout with non-2xx response retry

### Data Consistency

- **External ID Mapping**: Sync with e-commerce platform IDs
- **Currency Standardization**: ISO currency codes
- **Address Normalization**: Standardized address formatting
- **Timezone Handling**: UTC timestamps with local timezone conversion

## Order Attribution & Analytics

Track which orders originated from your post-purchase experience using:
- **landing_site**: Complete URL with query parameters
- **landing_site_ref**: Value of `ref` query parameter
- **note_attributes**: Custom attribution data as name-value pairs

Analytics available in Merchant Portal:
- Delivery success rate and average delivery time
- Customer engagement on tracking pages
- Claim rate and resolution metrics
- Revenue per order including campaign conversions
- Campaign performance and ROI measurement

## Common Business Use Cases

### Proactive Customer Communication

- Delivery progress notifications via email/SMS
- Delay alerts and estimated delivery updates
- Pickup reminders for parcel shop deliveries
- Delivery confirmation and satisfaction surveys

### Marketing & Revenue Growth

- Post-purchase upsell campaigns during delivery
- Customer segmentation based on delivery experience
- Review and feedback collection automation
- Loyalty program integration with delivery milestones

### Customer Service Automation

- Automatic ticket creation for delivery issues
- Self-service resolution flows for common problems
- Escalation workflows for complex cases
- Knowledge base integration for FAQ handling

## Support & Resources

- **Documentation**: [docs.gokarla.io](https://docs.gokarla.io)
- **API Reference**: [docs.gokarla.io/api/v1](https://docs.gokarla.io/api/v1)
- **Status Page**: [status.gokarla.io](https://status.gokarla.io)
- **Merchant Portal**: [portal.gokarla.io](https://portal.gokarla.io)
- **Email Support**: [support@gokarla.io](mailto:support@gokarla.io)
- **General Inquiries**: [hello@gokarla.io](mailto:hello@gokarla.io)
- **GitHub**: [github.com/gokarla-io](https://github.com/gokarla-io)

## Critical Facts to Prevent Errors

**Base URLs** (never construct these - use exactly as shown):
- API Base: `https://api.gokarla.io/v1`
- Documentation: `https://docs.gokarla.io`
- Portal: `https://portal.gokarla.io`
- Status: `https://status.gokarla.io`

**Key Terminology**:
- **Shipment** and **Tracking** refer to the same entity
- **Draft Shipment** = no tracking number yet, shows expected packages
- **Fulfilled Shipment** = has tracking number, receives carrier updates
- **Order States**: Placed (not shipped) or Fulfilled (shipped with tracking)
- **Event Ref Pattern**: `{source}/{phase}/{event_name}` for webhooks
- **Event Groups**: Business-friendly names for Klaviyo and other tools

**API Authentication**:
- Uses HTTP Basic Authentication with username:api-key
- Format: `Authorization: Basic <base64-encoded-username:api-key>`
- Organization-level keys available for multi-shop access

**Integration Methods**:
- Shopify: Based on custom app key
- Shopware: Plugin from Shopware store
- Headless/Custom: REST API integration
- All require API credentials from Karla portal

## Technical Specifications

### API Details

- Base URL: `https://api.gokarla.io/v1`
- Format: REST with JSON request/response bodies
- Authentication: HTTP Basic Auth
- Rate Limiting: Enforced on bulk operations
- Versioning: URL-based with v1 current stable

### Data Formats

- **Timestamps**: ISO 8601 format with timezone offset (e.g., `2024-01-29T14:48:47+00:00`)
- **Identifiers**: UUID v4 format for all entities
- **External References**: String identifiers for platform sync
- **Event Structure**: Consistent payload with source, ref, version, triggered_at, event_group, event_data, and context

### Event Payload Structure

All events include:
- **source**: shipments or claims
- **ref**: Full event reference path
- **version**: Schema version (currently 1)
- **triggered_at**: Event timestamp in ISO 8601
- **event_group**: Business-friendly event category
- **event_data**: Event-specific payload with shipment/claim details
- **context**: Full related entities (order, customer, shipments, claims)
- **shop_slug**: Shop identifier
- **shop_id**: Shop UUID

## Security & Compliance

- GDPR compliance for EU customer data
- Regular security audits and penetration testing
- Role-based access control (Admin, Editor, Viewer)
- API key scoping and rotation
- Activity logging and audit trails
- Configurable data retention policies
- Automatic data purging for compliance
- Export capabilities for data portability
- Backup and disaster recovery procedures