# Karla Documentation

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.

## Core Platform

- [Get Started](https://docs.gokarla.io/docs/get-started): Quick introduction to Karla platform and capabilities.
- [API Overview](https://docs.gokarla.io/docs/api/overview): Complete API reference and integration guide.
- [Authentication](https://docs.gokarla.io/docs/api/authentication): API authentication methods and credentials setup.
- [API Reference](https://docs.gokarla.io/api/v1): Interactive API documentation with live examples.
- [Data Models Overview](https://docs.gokarla.io/docs/data-models/overview): Core entities, relationships, and data structures.
- [Events System](https://docs.gokarla.io/docs/data-models/events): Complete event reference for webhooks and triggers.
- [API Errors](https://docs.gokarla.io/docs/api/errors): Error handling and troubleshooting guide.
- [API Versioning](https://docs.gokarla.io/docs/api/versioning): API version management and upgrade procedures.
- [Localization](https://docs.gokarla.io/docs/api/localization): Multi-language support and internationalization.
- [API Clients](https://docs.gokarla.io/docs/api/clients): SDK clients for various programming languages.

## API Entities

### Core Business Objects
- [Organization](https://docs.gokarla.io/docs/api/entities/organization): Multi-tenant account management for multiple shops.
- [Shop](https://docs.gokarla.io/docs/api/entities/shop): Individual store configuration and settings.
- [Order](https://docs.gokarla.io/docs/api/entities/order): Customer purchase data and order management.
- [Shipment](https://docs.gokarla.io/docs/api/entities/shipment): Package tracking, delivery status, and carrier integration.
- [Campaign](https://docs.gokarla.io/docs/api/entities/campaign): Post-purchase marketing campaigns and promotions.
- [Claim](https://docs.gokarla.io/docs/api/entities/claim): Customer service requests and issue resolution.

### Supporting Entities
- [Announcement](https://docs.gokarla.io/docs/api/entities/announcement): Shop-wide notifications and messaging.
- [Discount](https://docs.gokarla.io/docs/api/entities/discount): Promotional discounts for campaign integration.
- [Shop Setting](https://docs.gokarla.io/docs/api/entities/shop-setting): Shop-specific configuration options.
- [Webhook](https://docs.gokarla.io/docs/api/entities/webhook): Event subscription and notification configuration.

## Tracking & Customer Experience

- [Tracking Page Overview](https://docs.gokarla.io/docs/tracking-page/overview): Branded tracking experience for customers.
- [Tracking Page Demo](https://docs.gokarla.io/docs/tracking-page/demo): Interactive demo of tracking page features.
- [Integrate in Your Shop](https://docs.gokarla.io/docs/tracking-page/integrate-in-your-shop): Integration methods for tracking pages.

## Triggers & Notifications

- [Triggers Overview](https://docs.gokarla.io/docs/triggers/overview): Automated notification systems and event-driven workflows.
- [Klaviyo Integration](https://docs.gokarla.io/docs/triggers/klaviyo): Email and SMS automation with delivery events.
- [Shopify Integration](https://docs.gokarla.io/docs/triggers/shopify): Native Shopify order status updates and Flow integration.
- [Webhooks](https://docs.gokarla.io/docs/triggers/webhooks): Real-time HTTP notifications with security and retry logic.

## Marketing Campaigns

- [Campaigns Overview](https://docs.gokarla.io/docs/campaigns/overview): Post-purchase marketing and customer engagement.
- [Creating Campaigns](https://docs.gokarla.io/docs/campaigns/creating-campaigns): Step-by-step campaign creation guide.
- [Campaign Types](https://docs.gokarla.io/docs/campaigns/campaign-types): Basic, product, and banner campaign specifications.
- [Segmentation](https://docs.gokarla.io/docs/campaigns/segmentation): Customer targeting with Klaviyo, Shopify, and custom segments.

## Customer Service & Resolution

- [Resolve Overview](https://docs.gokarla.io/docs/resolve/overview): Self-service customer support for delivery issues.
- [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.

## Shop Integrations

- [Shopify Integration](https://docs.gokarla.io/docs/shop-integrations/shopify): Complete Shopify setup and configuration.
- [Shopware Integration](https://docs.gokarla.io/docs/shop-integrations/shopware): Shopware plugin installation and setup.
- [Headless Integration](https://docs.gokarla.io/docs/shop-integrations/headless): Headless commerce integration patterns.
- [Customize Your Experience](https://docs.gokarla.io/docs/shop-integrations/customize-your-experience): Customization options for integrations.

## Advanced Features

- [Karla NXT](https://docs.gokarla.io/docs/karla-nxt/integrate-agent-to-website): Advanced analytics and AI agent integration.

## Event Types & Data Models

Karla's event system provides comprehensive tracking throughout the delivery journey with consistent patterns. All events follow standard structure with metadata, payload, and context sections.

### Shipment Events
Karla generates events throughout the delivery journey with consistent patterns:

- **Order Created** (`shipments/order_created/*`): Order placement and initial processing
- **Order Processed** (`shipments/order_processed/*`): Package preparation and carrier pickup
- **In Transit** (`shipments/in_transit/*`): Package movement through carrier network
- **In Delivery** (`shipments/in_delivery/*`): Out for delivery and delivery attempts
- **Delivered** (`shipments/delivered/*`): Successful delivery confirmations
- **Pickup** (`shipments/pickup/*`): Customer pickup from pickup points
- **Delivery Failed** (`shipments/delivery_failed/*`): Failed delivery attempts
- **Return Transit** (`shipments/return_transit/*`): Return shipment processing
- **Return Failed** (`shipments/return_failed/*`): Failed return attempts

### Claim Events
Customer service and resolution workflows:

- **Claim Created** (`claims/created`): New customer service requests
- **Claim Updated** (`claims/updated`): Status changes and resolution updates

### Data Model Structure

Karla's API is built around several core entities:

**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 draft and fulfilled states
- **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

## Integration Patterns

### Authentication Methods
- **Basic Authentication**: Username and private API key
- **API Key Headers**: Custom header-based authentication
- **Organization-level Keys**: Multi-shop access with single credential
- **User Permissions**: Admin (read/write) vs Viewer (read-only) access

### Webhook Security
All webhooks include `Karla-Signature` headers for verification:
- HMAC-SHA256 signature validation
- 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 across all transactions
- **Address Normalization**: Standardized address formatting
- **Timezone Handling**: UTC timestamps with local timezone conversion

## 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

### Analytics & Optimization
- Delivery performance tracking across carriers
- Customer satisfaction correlation with delivery experience
- Campaign conversion and ROI measurement
- Cross-shop performance comparison and optimization

## Common Integration Scenarios

### E-commerce Platform Setup
1. Install platform-specific plugin or extension
2. Configure API credentials and webhook endpoints
3. Map product catalogs and customer segments
4. Set up order and fulfillment synchronization
5. Test with sandbox/development orders

### Marketing Automation Integration
1. Connect email/SMS platform (Klaviyo, Mailchimp, etc.)
2. Configure event group subscriptions
3. Create delivery-based customer segments
4. Design automated campaign flows
5. Set up conversion tracking and attribution

### Customer Service Integration
1. Connect service desk platform (Zendesk, Intercom, etc.)
2. Configure claim event webhooks
3. Set up automatic ticket creation rules
4. Design resolution workflow automation
5. Train support team on Karla-generated tickets

### Multi-brand Management
1. Create organization with multiple shops
2. Configure shop-specific settings and branding
3. Set up cross-shop user permissions
4. Implement unified reporting and analytics
5. Manage centralized billing and invoicing

## Security & Compliance

### Data Protection
- GDPR compliance for EU customer data
- Regular security audits and penetration testing

### Access Control
- Role-based permissions (Admin, Viewer)
- API key scoping and rotation
- IP whitelisting for webhook endpoints
- Activity logging and audit trails

### Data Retention
- Configurable data retention policies
- Automatic data purging for compliance
- Export capabilities for data portability
- Backup and disaster recovery procedures

## Support & Resources

- **Documentation**: [docs.gokarla.io](https://docs.gokarla.io)
- **API Reference**: [doc.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)
- **Contact**: [hello@gokarla.io](mailto:hello@gokarla.io)
- **GitHub**: [github.com/gokarla-io](https://github.com/gokarla-io)