Skip to main content

API improvements for order integrations

· 3 min read
Albert Tiñena
Albert Tiñena
Chief Technology Officer (CTO)
David Sancho
David Sancho
Principal Engineer & Technical Architect

This release introduces improvements focused on order integrations, adding new metadata to better represent commercial bundles and order attribution sources.

Bundle metadata in orders​

Orders now include additional metadata to represent commercial bundles, enabling external systems to reconstruct how products were grouped when purchased.

Previously, the API returned all products as independent line_items, without any way to identify which items belonged to the same bundle.

This created limitations for integrations (such as ERPs) that need to:

  • Identify which products belong to the same pack
  • Reconstruct the original commercial bundle
  • Optionally represent the bundle as a single line

bundle_group_id in line items​

A new optional field bundle_group_id is now available in line_items.

  • Present only when the item belongs to a bundle
  • Same value for all items within the same bundle
  • Corresponds to the internal identifier of the bundle line

Example:

{
  "line_items": [
    {
      "id": 253419,
      "display_name": "Product A",
      "bundle_group_id": 81741
    },
    {
      "id": 253420,
      "display_name": "Product B",
      "bundle_group_id": 81741
    }
  ]
}

bundles field at order level​

A new optional field bundles is available at the root of the order.

  • Contains one entry per bundle group
  • Provides a structured view of the commercial packs

Example:

{
  "bundles": [
    {
      "bundle_group_id": 81741,
      "bundle_id": 1243,
      "display_name": "Bundle Name",
      "quantity": 2,
      "line_item_ids": [253419, 253420, 253421]
    }
  ]
}

How it works​

  • line_items remains the source of truth for:

    • Quantities
    • Prices
    • Totals

  • bundles is metadata only:

    • Does not introduce new lines
    • Does not affect calculations

  • bundle_group_id links both structures

If bundles.quantity = N, it means:

  • The customer purchased N complete bundles
  • All corresponding units are already reflected in line_items
  • No additional multiplication or recalculation is required

Order source attribution​

Orders now include attribution data to indicate the origin of the customer journey.

source field​

A new optional field source is available in the order resource:

{
  "source": ["organic"]
}

This field represents the list of attributed sources associated with the order, ordered chronologically.

Supported values​

The source field uses predefined values:

  • not_defined — Source is not available
  • organic — Unpaid search traffic
  • sem — Paid search campaigns
  • promotion — Merchant-created promotional campaigns
  • social — Supported social media sources
  • backoffice — Manually created orders
  • seestocks — Traffic from SeeStocks CSS
  • automarketing — Automated marketing flows (e.g. abandoned cart)

Availability​

All fields are available in:

  • GET /api/v1/orders/
  • GET /api/v1/orders/{id}/

Summary​

This release improves order-related integrations by:

  • Enabling reconstruction of commercial bundles through lightweight metadata
  • Providing clear attribution of order origin

These changes are designed to support real-world integration scenarios while preserving the existing data model.

What's next​

Upcoming improvements will continue to focus on:

  • Expanding API coverage to support broader ERP and integration use cases
  • Continuing to evolve the API as a robust integration platform
  • Customer endpoint.

👉 API Overview