This release introduces a new webhook envelope format shared across all events, making it easier to implement idempotency, consume multiple event types from a single endpoint, and clearly separate event metadata from resource data.

It also adds the first Order webhooks, allowing external systems to react in real time to key order lifecycle changes.

A unified webhook envelope for all events​

All OpenTiendas webhooks now use a common payload structure.

{
  "event_id": "evt_123",
  "type": "order.created",
  "created_at": "2026-03-16T10:12:33Z",
  "data": {
    ...
  }
}

This new format introduces:

• event_id: a unique event identifier, useful for implementing idempotency
• type: the event type, allowing consumers to process multiple webhook types from the same destination URL
• created_at: the timestamp indicating when the event was generated, useful for logging, debugging, and event tracing.
• data: the resource payload associated with the event

This change applies to all webhooks, including already existing ones such as:

• review.created
• review.published

Why this change matters​

The new envelope structure makes webhook integrations more reliable and easier to scale.

It allows integrators to:

• Detect and ignore duplicate deliveries using the event_id
• Route logic based on type without requiring separate endpoints
• Keep event metadata separated from the actual business resource
• Standardize webhook handling across all current and future event types

New order webhooks​

With the Orders resource now available, OpenTiendas also introduces new webhook events related to the order lifecycle.

These events allow external systems such as ERPs, fulfillment tools, or automation workflows to react in real time to key order state changes.

The following events are now available:

• order.created
• order.paid
• order.fulfilled
• order.canceled

You can find the full list of available Order events, payload examples, and event-specific notes in the webhook reference:

👉 Webhook Events Reference

Documentation updates​

The developer documentation has been updated accordingly.

👉 Webhooks

What's next​

With the webhook system now standardized and Order events available, upcoming improvements will focus on:

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

👉 API Overview

This release introduces Orders endpoints, enabling integrations of order data with external systems, extends the catalog API with new bulk operations, improved filtering, and better integration tools for PIMs and ERPs, and makes the API available in OpenAPI format for use with AI tools and standard API tooling.

Orders API: retrieve and synchronize orders​

OpenTiendas now provides endpoints to retrieve orders from external systems, enabling integrations with ERPs, logistics platforms, and other management tools.

Get Order​

GET /api/v1/orders/{id}

Retrieve a specific order with detailed information, including:

• Customer data
• Billing and shipping addresses
• Product lines
• Amounts and totals
• Payment status
• Fulfillment status

This endpoint is designed for systems that need to consult individual orders in real time.

List Orders​

GET /api/v1/orders

Retrieve a paginated list of orders with support for filtering and sorting.

Supported filters include:

• Creation date
• Payment date
• Fulfillment date
• Payment status
• Payment method
• Delivery method

This enables order synchronization workflows with external systems.

Bulk updates at variant level​

To improve catalog synchronization, a new endpoint allows bulk updates directly on product variants.

POST /api/v1/variants/bulk-update

Key characteristics:

• Operates directly at variant level
• Designed for updating price, stock, and variant-specific attributes
• Supports multiple matching strategies:
  • id
  • internal_id
  • ean
  • sku + supplier

Unlike the product bulk upsert, this endpoint allows updating specific variant data (such as price or stock) without modifying the overall product structure.

As with other bulk operations, processing is asynchronous, generating a background Job.

Link products with external systems​

A new endpoint allows linking existing OpenTiendas catalog products/variants with external systems.

POST /api/v1/catalog/link-ids

This endpoint enables updating the internal_id of products and variants using matching strategies such as:

• ean
• sku + supplier

It is especially useful for:

• Initial ERP or PIM integrations
• Migrating existing catalogs without recreating products
• Establishing a persistent mapping between systems

Once linked, external systems can rely on internal_id for future updates.

Improvements in product filtering​

The List Products endpoint now includes enhanced filtering capabilities.

Filter by slug​

Products can now be retrieved using their public identifier:

• Filter by a single slug
• Filter by multiple slugs in a single request

This improvement also applies to other resources that support slug filtering, such as categories and brands.

This makes it easier to integrate with systems that rely on public URLs as identifiers.

OpenAPI documentation for AI tools​

The OpenTiendas API documentation can now be downloaded in OpenAPI format, making it easier to use with AI-assisted development tools and standard API tooling.

👉 API Reference

This enables:

• Using the API specification as context in tools like ChatGPT or Claude to generate code, queries, or integrations
• Importing the API into tools such as Postman or Insomnia to explore and test endpoints
• Automatically generating client code

This improvement is designed to accelerate integration development, allowing AI tools and developers to understand the API precisely and generate valid requests based on its specification.

Slug management via API​

It is now possible to modify the base slug (slug_base) via API for:

• Products
• Categories
• Brands

Keep in mind:

Updating the slug will modify the public URL and may impact SEO (existing links and indexed pages).

Background Jobs​

All bulk operations continue to rely on the background Jobs system, ensuring safe processing of large updates without affecting store performance.

Jobs provide:

• Asynchronous execution
• Status tracking
• Logs and result inspection

You can monitor Jobs in the backoffice:

Settings → Advanced Options → Jobs

What's next​

With Orders now available and catalog operations becoming more flexible, upcoming improvements will focus on:

• Expanding order management capabilities
• Improving real-time synchronization flows
• Enhancing bulk operations performance and coverage
• Continuing to evolve the API as a robust integration platform

👉 API Overview

This release introduces several foundational capabilities that significantly expand what can be built on top of the API: product listing with filtering and sorting and bulk catalog updates prepared for ERP and PIM integrations.

Alongside these endpoints, we’re also introducing a new background Jobs system, allowing the platform to safely process large asynchronous tasks such as mass catalog updates.

Together, these changes represent an important milestone in making the OpenTiendas API scalable, predictable, and ready for large external system integrations.

List Products with filtering and sorting​

A new endpoint allows retrieving products from the catalog with pagination, filtering, and sorting.

GET /api/v1/products

It supports filtering by common catalog attributes such as brand, category, supplier or product structure.

For the complete list of supported filters, sorting options, and query parameters, see the List Products API reference.

Bulk product upsert​

Large catalogs are often managed in external systems such as PIMs or ERPs.

To support these workflows, we've introduced the bulk product upsert endpoint:

POST /api/v1/products_bulk_upsert

This endpoint allows clients to create or update products and variants in bulk.

Important characteristics:

• Asynchronous processing
• Supports both product and variant updates
• Suitable for full or partial catalog synchronization from external systems

Instead of processing the entire request synchronously, the API creates a background job that performs the operation.

For the complete request structure and supported fields, see the Bulk Product Upsert operation in the API reference.

Background Jobs system​

Bulk operations through the API require a safe way to process large tasks without affecting store performance.

OpenTiendas now includes a background Jobs system designed to support API-triggered asynchronous operations.

When an asynchronous operation is triggered (such as products_bulk_upsert), the API creates a Job responsible for executing the task.

Jobs provide:

• Background execution of heavy operations
• Status monitoring
• Execution logs
• Result inspection

A new Jobs section is available in the backoffice under: Settings → Advanced Options → Jobs

From this interface, administrators can inspect running tasks, review logs, and check the outcome of these async API operations.

What's next​

With product retrieval and bulk catalog updates in place, the next steps focus on:

• Direct access to list product variants.
• Improving catalog synchronization workflows.
• Bulk updates at the variant level to support additional integration scenarios.
• Expanding the API with Orders.

👉 API Overview

Alongside it, we’ve formalized and documented the core rules around localization, markets, field selection, and response shape that apply consistently across the API.

First catalog endpoint: Get Product​

We’ve released the first Products API endpoint:

GET /api/v1/products/{id}

This endpoint supports both simple products and products with variants.

Key characteristics:

• One endpoint for simple and multi-variant products
• Explicit and unambiguous schema
• Deterministic localization and pricing behavior
• Safe defaults for performance (variants preview capped at 50)

This endpoint establishes the baseline design for all future catalog endpoints.

No more Accept-Language​

The Accept-Language header has been removed.

Localization is now controlled exclusively via the locales query parameter:

GET /api/v1/products/123?locales=es-ES,fr-FR

• Multiple locales can be requested in a single call
• All translatable fields are returned only under translations
• This behavior is consistent across Products, Categories, Brands, and Reviews

Locale → Market → Prices​

In OpenTiendas, a locale represents more than language.

• Each locale deterministically resolves to one pricing market
• Prices are returned under prices, keyed by market identifiers (market_es, market_fr, …)
• Multiple locales may resolve to the same market

This relationship is now explicitly documented and enforced.

👉 Localization & Markets

Fixed fields, default fields, explicit expansion​

All API resources now follow the same field model:

• Fixed fields are always returned (e.g. id)
• Default fields form the minimal canonical representation
• When fields is specified, only:
  • fixed fields, and
  • explicitly requested fields
    are returned

Each resource documents its fixed fields, default fields, and navigable relationships.

One rule for missing, empty, and null​

The API enforces a single data presence contract everywhere:

• Missing field → not applicable
• Empty value ("", [], {}) → applicable but empty
• null → explicitly unset or unknown

This removes ambiguity and simplifies client-side logic.

What’s next​

• Product list endpoints
• Expanded variants access
• Continued alignment across resources for filtering

These changes lay the foundation for a predictable, scalable catalog API.

👉 API Overview
👉 Localization & Markets

Reviews: Filtering & sorting on list endpoint​

The List Reviews endpoint now supports filtering and sorting through explicit query parameters.

This makes it easier to:

• Build moderation and backoffice tooling
• Sync subsets of reviews reliably
• Query large datasets without extra client-side processing

Filtering remains fully compatible with pagination and ordering.

Example:

GET /api/v1/reviews?type=product&product_id=2532&status=published&sort=rating_desc

If you’re implementing filters, refer to our conventions and supported parameters in:

👉 Filtering & Sorting

Categories: Google Merchant Category field​

The Categories endpoint now exposes the Google Merchant Category field.

This improves catalog management for:

• Merchant Center feeds
• Ads campaigns
• External integrations that require taxonomy mapping

By providing this field directly from the API, you can reduce external dependencies and avoid duplicating category mapping logic outside OpenTiendas.

What’s next?​

• More list endpoints adopting the same filtering conventions.
• First version of the products endpoint.

Check out the updated API documentation and start using these improvements in your integrations.

This release enhances the API with access to suppliers, brands, and categories — setting the foundation for deeper catalog management and greater automation capabilities.

New endpoints​

You can now manage suppliers, brands, and categories directly through the OpenTiendas API.

Suppliers​

New endpoints for managing your suppliers:

• GET /api/v1/suppliers/: List all suppliers (paginated).
• GET /api/v1/suppliers/{id}: Get a specific supplier.
• POST /api/v1/suppliers/: Create a new supplier.
• PATCH /api/v1/suppliers/{id}: Update supplier info.
• DELETE /api/v1/suppliers/{id}: Permanently delete a supplier.

Each supplier has fields like name, internal_id, and description. The internal_id is unique per supplier and should be used for internal references.

Brands​

Manage brand data with full i18n support:

• GET /api/v1/brands/
• GET /api/v1/brands/{id}
• POST /api/v1/brands/
• PATCH /api/v1/brands/{id}
• DELETE /api/v1/brands/{id}

Brands include media, SEO metadata, and size guide files.
All translatable fields (e.g., name, description, body_html) must be provided inside the translations block — even for the store’s main language.

Categories​

Categories are now fully accessible via API:

• GET /api/v1/category/
• GET /api/v1/category/{id}
• POST /api/v1/category/
• PATCH /api/v1/category/{id}
• DELETE /api/v1/category/{id}

As with brands, category endpoints support multilingual data through the translations block.
Each category includes status (published/unpublished), image_url, and parent_id.

New global permissions​

We’ve introduced a new permission system for API keys.

When creating or editing an API key, you’ll now see a Permissions section with two global scopes:

• ✅ Read access
• ✅ Write access

These apply across all current and future endpoints.
More granular domain-specific permissions (e.g., suppliers, brands, categories) will follow soon.

Consistent pagination​

All list endpoints (GET requests returning multiple items) now include a unified pagination block:

{
  "data": [...],
  "pagination": {
    "current_page": 2,
    "per_page": 50,
    "total": 250,
    "total_pages": 5,
    "next_page_url": "/api/v1/suppliers?page=3",
    "previous_page_url": "/api/v1/suppliers?page=1"
  }
}

This makes it easier to build consistent UIs or sync large datasets across pages.

👉 See the pagination section in our API docs for implementation details and best practices.

i18n contents​

We’ve now published our first i18n-ready content. All translatable fields must be sent inside the translations block when creating or updating content through the API

{
  "translations": [
    {
      "locale": "en",
      "name": "New category",
      "description": "Short text"
    }
  ]
}

Any translatable field (name, description, body_html, etc.) sent at the root level will be ignored or rejected.
This applies to both create and update operations.

👉 Learn more in our i18n handling documentation

What’s next?​

• More endpoints for advanced catalog and order management.
• Fine-grained permission scopes per domain.

Check out the updated API documentation and start integrating these new features today. 🚀

This marks the beginning of a journey towards a more connected and automated e-commerce platform. While the initial endpoints are limited, the underlying infrastructure sets the stage for rapid future expansion.

What this means​

The OpenTiendas API provides the foundation for developers to build integrations and automate workflows with their stores.
With a RESTful design, standard HTTP methods, and JSON responses, it’s designed for simplicity and flexibility.

This initial release is focused on laying the groundwork. Expect more comprehensive endpoints, actions, and features in upcoming releases.

Key highlights​

• Robust infrastructure: Built to support scalable and secure integrations.
• API key authentication: Secure access to store data with role-based controls.
• Shop-specific endpoints: Use {SHOP_ID} in the URL to target your store’s data.
• RESTful design: Predictable URLs and standard HTTP methods.

What’s next?​

This is just the beginning. Over the coming weeks, we plan to:

• Expand the available endpoints and actions (including POST, PATCH, DELETE).
• Introduce fine-grained permissions and scopes for more control.
• Improve performance and increase rate limits.

How to get started​

1️⃣ Generate your API key in the OpenTiendas admin panel.
2️⃣ Replace {SHOP_ID} with your store’s unique identifier.
3️⃣ Start making requests to https://{SHOP_ID}.opentiendas.app/api/v1.
4️⃣ Handle responses and errors according to best practices.

Check out our API documentation to get started.

Stay tuned for updates as we expand the OpenTiendas API. 🚀

This means developers can now subscribe to real-time notifications of key events happening in their stores, paving the way for dynamic integrations and seamless workflows.

What are Webhooks?​

Webhooks allow OpenTiendas to notify your applications automatically when certain events occur.
You can now receive instant updates via HTTP POST requests whenever relevant events happen.

This opens up a world of possibilities: syncing data, triggering workflows, sending alerts, and more.

First Webhooks: A test launch​

To kick things off, we’re launching with two initial webhook events for testing:

• review.create: triggered when a new review is created.
• review.publish: triggered when a review is published.

These events allow you to build features like:

• Notifying teams about new reviews.
• Automatically updating your analytics or moderation systems.
• Building integrations with other platforms based on review activity.

Why this is important​

This initial launch isn’t just about the two events—it’s about the infrastructure.
We now have a robust webhook system in place, and we’re planning to rapidly expand the list of available events in the near future.

Expect support for orders, products, customers, inventory, and more, all with the same real-time capabilities.

Getting Started​

1️⃣ Set up your webhook endpoint (a URL in your system to receive events).
2️⃣ Register the webhook via the OpenTiendas dashboard.
3️⃣ Listen for the review.create and review.publish events.
4️⃣ Validate webhook signatures to ensure security.

For detailed setup instructions, visit our Webhooks Guide.

Stay tuned for more updates from the OpenTiendas team. Happy coding! 🎉

Welcome to the OpenTiendas Developer Portal! 🚀

We're excited to launch this platform to provide comprehensive documentation, developer resources, and updates for the OpenTiendas ecosystem.

Whether you're a merchant looking to integrate with OpenTiendas, a developer exploring the APIs, or a partner building custom solutions, this portal will be your go-to hub.

What is OpenTiendas?​

OpenTiendas is a hosted no-code All-in-One eCommerce platform that empowers businesses to create, manage, and grow successful online stores—without plugins, technical complexity or worrying about infrastructure.

As a SaaS (Software-as-a-Service) solution, OpenTiendas offers:

• 🚀 Advanced eCommerce features ready to use
• 🔗 Native integrations with leading applications (Klaviyo, Stripe, PayPal, and more)
• 🌐 Robust APIs and webhooks for seamless integrations and expansion
• 🤝 A Partner-friendly ecosystem designed for agencies and developers

About This Portal​

This portal provides:

• 🔗 Versioned API documentation and developer guides
• 📝 Dynamic blog posts with product announcements, API updates, and tips
• 📢 News and updates from the OpenTiendas engineering team
• 💡 Best practices and tutorials to help you succeed with OpenTiendas

Getting Involved​

Want to contribute or suggest content?
Feel free to open a pull request or contact us via our support channels.

We’re building this platform for you, so your feedback is always welcome!

Tags and More​

This blog post is tagged with:

• api
• webhooks
• updates
• css
• tips

Stay tuned for more updates and happy coding! 🎉