Skip to main content

Orders

The Order entity represents a customer purchase in your shop system and serves as the foundation for post-purchase tracking, claims, and campaign management in Karla.

System Integration​

System Flow:

  1. Customer places an order through your shop system
  2. Order is created in Placed state with expected products
  3. Draft Shipments show customers what packages to expect
  4. Fulfillment transitions order to Fulfilled state with tracking
  5. Shipment Events enable tracking and claims functionality
  6. Events are generated and sent to you depending on your configured subscriptions

Order States​

Orders have two main states that determine their functionality in the Karla system:

Placed State​

  • Description: Order has been accepted and paid but not shipped
  • Shipments: Contains Draft Shipments (no tracking numbers)
  • Customer Experience: Shows expected packages and estimated delivery
  • Available Features:
    • Order confirmation campaigns
    • Pre-shipment notifications
    • Expected package visibility
  • Event Generation: Limited to order-level events

Fulfilled State​

  • Description: Order has been dispatched to a carrier for delivery
  • Shipments: Contains Fulfilled Shipments (with tracking numbers)
  • Customer Experience: Real-time tracking and delivery updates
  • Available Features:
    • Full tracking functionality
    • Delivery campaigns
    • Claims and resolve flows
    • Event-driven automation
  • Event Generation: Complete carrier event tracking

Partial Fulfillment​

For orders with multiple shipments, fulfillment can happen gradually:

  • Partially Fulfilled: Some shipments are fulfilled while others remain as drafts
  • Mixed State Management: Different shipments can be in different states
  • Progressive Tracking: Customers see tracking for fulfilled packages and expectations for pending ones
info

This only happens in a multi-shipment scenario where order placement specifies multiple expected shipments.

Order Lifecycle​

1. Order Creation​

Use the Upsert Order endpoint, providing an id and id_type that matches the ones given in the payload you defined for order.

For creating an order, it is mandatory to provide the order object. If the order is not fulfilled, pass [] in the trackings object.

tip

We recommend using the Upsert Order endpoint. Although orders can also be submitted using the Place Order endpoint, Upsert Order offers greater flexibility. For example, it allows for the creation of directly fulfilled orders and can simplify your code integration. We make extensive use of Upsert Order in our plugin integrations, and it represents a common implementation pattern.

For instance, to place an order using the upsert endpoint (with no tracking information available at that point):

PUT /v1/shops/{slug}/orders
{
  "id": "11334422",
  "id_type": "order_number",
  "order": {
    "order_number": "11334422", // Mandatory, it must be unique among all your orders
    "order_name": "IXF1234",
    "order_placed_at": "2023-03-17T09:51:41+00:00",
    "total_order_price": 29.99,
    "shipping_price": 4.99,
    "sub_total_price": 40,
    "discount_price": 4.99,
    "products": [
      {
        "bundled_products": [],
        "images": [
          {
            "src": "https://shop.gokarla.io/myimage.png",
            "alt": "Product A"
          }
        ],
        "price": 10,
        "quantity": 1,
        "tax_lines": [],
        "title": "Product A",
        "type": "product"
      }
    ],
    "discounts": [
      {
        "amount": "10.0",
        "code": "ULTRA_OFFER",
        "type": "percentage"
      }
    ],
    "email_id": "[email protected]",
    "address": {
      "address_line_1": "Teststr. 1",
      "address_line_2": "2nd floor",
      "city": "Berlin",
      "country": "Germany",
      "country_code": "DE",
      "name": "Jane Doe",
      "phone": "+49 123 4567890",
      "province": "Berlin",
      "province_code": "BE",
      "street": "Teststr. 1, 2nd floor",
      "zip_code": "10119",
      "company": "Example GmbH"
    },
    "currency": "EUR",
    "segments": [
      "segment1",
      "segment2"
    ],
    "weight": 1000,
    "external_customer_id": "1234067358984",
    "order_status_url": "https://shop.gokarla.io/1234067358984/orders/aabbcc/authenticate?key=secret",
    "external_id": "2205783916624",  // If provided, it must be unique among all your orders
    "preferred_delivery_date": {
      "start": "2019-08-24T14:15:22Z",
      "end": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "source": "string"
    },
    "user_agent": [
      "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36"
    ],
    "order_analytics": {},
    "expected_number_of_shipments": 1
  },
  "trackings": [] // For order placements, this field has to be provided empty
}

2. Order Fulfillment​

To fulfill an order you do not need to pass an order object to Upsert Order. Make sure that the id and id_type matches the trackings that you want to attach to that order.

For instance

PUT /v1/shops/{slug}/orders
{
  "id": "11334422",
  "id_type": "order_number",
  // "order" object is not mandatory if it has been created previously,
  // otherwise, it must be provided so order is created together with its fulfillment
  "trackings": [
    {
      "products": [
        // In multi-shipment scenarios per order,
        // the list of products from the order that
        // are included in this shipment.
        // If not provided, all shipments will have all
        // the products from the parent order
          {
            "bundled_products": [],
            "images": [
              {
                "src": "https://shop.gokarla.io/myimage.png",
                "alt": "Product A"
              }
            ],
            "price": 10,
            "quantity": 1,
            "tax_lines": [],
            "title": "Product A",
            "type": "product"
          }
      ],
      "tracking_number": "123456", // Mandatory, make sure that the number is unique among all provided shipments, it will be ignored otherwise
      "tracking_placed_at": "2025-07-23T11:47:37.470473Z", // If not provided, current time will be considered
      "tracking_company": "Carrier Name", // Unmapped carrier, significantly helps with AI matching
    }
  ]
}

3. Other operations​

4. Event Generation​

Fulfilled orders automatically generate tracking events for:

  • Carrier updates
  • Delivery status changes
  • Claim notifications

You can also add your own custom events to a specific shipment.

Key Relationships​

Shipments​

  • Draft Shipments: Expected packages before carrier pickup
  • Fulfilled Shipments: Active tracking with carrier updates

Tracking​

Order objects include a simplified trackings array for display purposes:

Order with Tracking Information
{
  "order_id": "uuid",
  "trackings": [
    {
      "tracking_number": "1Z999AA1234567890",
      "carrier_reference": "ups",
      "tracking_url": "https://www.ups.com/track",
      "phase": "in_transit",
      "estimated_arrival": {
        "start": "2024-02-01T00:00:00+00:00",
        "end": "2024-02-03T23:59:59+00:00"
      }
    }
  ]
}

Analytics & Insights​

Order Performance Metrics​

Track order success through the Merchant Portal:

  • Delivery Success Rate: Percentage of orders delivered successfully
  • Average Delivery Time: Time from fulfillment to delivery
  • Customer Satisfaction: Based on tracking page interactions
  • Claim Rate: Percentage of orders that generate claims
  • Revenue per Order: Including repeat purchases from campaigns

Best Practices​

Order Creation​

  1. External ID Mapping: Always include external IDs for platform sync
    • At least the order number MUST be unique, otherwise the new orders will be ignored
    • If no external id is provided, it will default to the order number
  2. Complete Customer Data: Provide email and external customer ID
  3. Accurate Product Info: Include SKUs, weights, and variant details, make sure that product images are working
  4. Proper Address Format: Use standardized address formatting
  5. Currency Consistency: Ensure currency matches shop configuration

Fulfillment Management​

  1. Timely Updates: Add tracking numbers as soon as available
  2. Accurate Carrier Info: Use correct carrier references and URLs
    • Providing a carrier_reference mapped to Karla makes the fulfillment process more deterministic
    • If unable to provide a carrier_reference, giving a tracking_company string will help the AI to match the tracking number to a carrier with more accuracy.
  3. Product Mapping: Ensure products map correctly to shipments
    • Specially in multi-shipment scenarios, otherwise the user won't be able to distinguish which products are in each shipment
  4. Date Precision: Use accurate shipped dates for better ETAs
  5. Status Monitoring: Track fulfillment progress through events

Integration Optimization​

  1. Batch Operations: Use bulk APIs for multiple order processing with care: we limit big requests
  2. Error Handling: Implement retry logic for failed requests
  3. Webhook Subscriptions: Subscribe to relevant order events
  4. Data Validation: Validate order data before API submission
  5. Performance Monitoring: Track API response times and errors

Troubleshooting​

Common Issues​

Order Not Found:

  • Verify order number format matches your system and that was correctly provided via id_type
  • Check that order was created in correct shop context
  • Ensure external ID mapping is consistent

Shipment State Issues:

  • Confirm tracking numbers are valid and formatted correctly
  • Verify carrier reference matches supported carriers
  • Check that product quantities match between order and shipments

Campaign Targeting Problems:

  • Validate customer segment formatting
  • Ensure segments exist in connected platforms (e.g. Klaviyo, Shopify)
  • Check campaign timing and status settings

API Reference​

  • Order - Detailed order and tracking information
  • Shipment - Detailed shipment and tracking information
  • Campaign - Marketing campaign management
  • Claim - Customer service and resolve flows