.png)
commercetools Integration Guide
Integrate commercetools Composable Commerce with enterprise systems through HTTP APIs, GraphQL queries, OAuth 2.0, asynchronous imports, and selected subscription events.
commercetools integration options at a glance
commercetools is primarily integrated through project-scoped HTTP APIs secured with OAuth 2.0 client credentials. Its GraphQL API supports read-oriented queries and tailored responses, while the HTTP API remains the main surface for mutations and update actions. Subscriptions publish selected resource-change messages to configured destinations such as Amazon SNS or SQS, Google Cloud Pub/Sub, Azure Service Bus, and EventBridge; coverage is not universal for every operation. The Import API supports asynchronous, large-scale loading for supported resources. Martini can orchestrate these APIs and events, map commerce objects, monitor asynchronous jobs, and run scheduled reconciliation workflows.
| Integration point | Supported by commercetools? | Common use cases | How Martini supports it |
|---|---|---|---|
| HTTP REST APIs | Yes | Primary interface for Products, Product Projections, Categories, Carts, Orders, Customers, InventoryEntries, prices, discounts, stores, channels, and update actions. Supports queries, pagination, filtering, expansion, and resource mutations. | Martini can consume the commercetools HTTP API from workflows, configure regional endpoints and OAuth authentication, transform responses, invoke update actions, and route errors. |
| GraphQL APIs | Yes | Read-oriented product, Product Projection, customer, cart, and related commerce queries where consumers need a tailored response shape or reduced over-fetching. | Martini can consume commercetools GraphQL queries, map nested responses, and combine GraphQL reads with HTTP API mutations in one workflow. |
| Subscriptions and event notifications | Limited | Publishes selected resource-change messages for supported Products, inventory, Customers, Carts, Orders, and other message types to configured destinations such as SNS, SQS, Pub/Sub, Azure Service Bus, or EventBridge. | Martini can consume resulting event messages through supported endpoints or messaging infrastructure, validate message types, retrieve current resources, and trigger downstream workflows. |
| Import API and asynchronous operations | Yes | Supports large-scale or asynchronous imports for Products, prices, inventory, Customers, and other supported resource types using import containers and asynchronous processing. | Martini can transform source data, submit import jobs, persist operation identifiers, monitor status, and route rejected or partially failed items for replay. |
| File and asset handling | Limited | Product assets and media references are supported, but commercetools is not a general-purpose file-transfer platform; binary content may reside in separate object storage or media services. | Martini can map asset metadata and coordinate separate media transfers, but should use a dedicated storage endpoint for binary content when required. |
| Authentication | Yes | OAuth 2.0 client credentials, bearer access tokens, project scopes, permissions, regional API hosts, and finite token lifetimes secure machine-to-machine API access. | Martini can store client credentials and endpoints as secrets or environment configuration, acquire and renew tokens, and apply least-privilege access. |
| SDKs | Yes | commercetools provides client libraries for several programming languages when custom application code is needed. | Martini can consume the documented HTTP and GraphQL APIs directly and use custom JVM-compatible logic when an implementation requires additional processing. |
| Database access | Not confirmed | No direct customer-facing SQL or database connection should be assumed for commercetools projects. | Martini should integrate through documented APIs and event mechanisms rather than direct database access. |
How commercetools exposes data and business events
commercetools REST APIs
The commercetools HTTP API is the primary integration surface for project resources, queries, mutations, and action-based updates. It supports commerce operations involving Products, Carts, Orders, Customers, InventoryEntries, prices, stores, channels, and related resources.
Martini implementation pattern
Martini uses a workflow to acquire an OAuth 2.0 bearer token, call the regional commercetools API, follow pagination, map the response into a canonical model, and invoke downstream APIs or commercetools update actions. Version-aware updates and bounded retry logic protect against concurrency and transient failures.
Implementation sequence
commercetools GraphQL API
The commercetools GraphQL API provides read-oriented access to commerce data and is useful when a storefront or downstream service needs a tailored response across related resources. The HTTP API remains the primary mechanism for mutations.
Martini implementation pattern
Martini can issue parameterized GraphQL queries, validate and transform nested responses, and combine those reads with HTTP API actions. This pattern reduces unnecessary fields while preserving commercetools-specific mutation semantics through the HTTP API.
Implementation sequence
commercetools Subscriptions
Subscriptions publish selected resource-change messages to configured destinations such as Amazon SNS or SQS, Google Cloud Pub/Sub, Azure Service Bus, and EventBridge. They are not universal webhooks for every commercetools operation.
Martini implementation pattern
Martini receives or consumes the configured event through a supported endpoint or messaging arrangement, validates the resource and message type, retrieves the current resource when necessary, and executes an idempotent downstream workflow. Scheduled reconciliation covers missed or unsupported changes.
Implementation sequence
commercetools Import API
The Import API supports asynchronous, large-scale loading of supported commerce data such as Products, prices, inventory, and Customers. Processing occurs through import containers and can return successful, rejected, or partially failed items.
Martini implementation pattern
Martini prepares and validates source data, submits an import, stores the operation identifier, monitors asynchronous processing, and routes item-level validation or business errors for correction and replay. This avoids issuing every mutation individually for large loads.
Implementation sequence
Common commercetools integration patterns
Pattern 1: Synchronize products and catalog data
When to use this pattern
Use this pattern when commercetools is the commerce product source or when a downstream search, content, or commerce platform needs Products, Product Projections, Categories, prices, and related catalog data. It accounts for variants, localized fields, currencies, channels, staged and current representations, and product assets.
Integration direction
Example Mapping
| commercetools Field | Canonical Field | Target Field |
|---|---|---|
| Product.id | productId | objectID |
| Product.masterData.current.name | localizedName | name |
| Product.masterData.current.masterVariant.sku | primarySku | sku |
| Product.masterData.current.masterVariant.prices | priceByCurrencyAndChannel | price |
Martini implementation pattern
A Martini workflow consumes subscription messages where available and uses paginated HTTP or GraphQL reads for initial loads and reconciliation. It builds a canonical catalog model, applies publication and localization rules, sends index or catalog updates, and retries transient failures without duplicating documents.
Martini capabilities used
- workflows
- API consumption
- GraphQL consumption
- data mapping
- business rules
- scheduled reconciliation
- error handling
Pattern 2: Orchestrate orders and fulfillment
When to use this pattern
Use this pattern when Orders must flow from commercetools to an ERP, warehouse, shipping, finance, or service application and fulfillment status must return to commercetools. The workflow should preserve resource versions and use appropriate Order update actions.
Integration direction
Example Mapping
| commercetools Field | Canonical Field | Target Field |
|---|---|---|
| Order.id | commerceOrderId | externalId |
| Order.lineItems | orderLines | itemList |
| Order.shippingAddress | shipToAddress | shippingAddress |
| Order.orderState | commerceOrderStatus | orderStatus |
Martini implementation pattern
Martini receives an event or scheduled request, retrieves the current Order, validates payment and fulfillment conditions, maps it to the target application, and stores correlation identifiers. Inbound fulfillment updates are translated into commercetools Order actions; concurrent modification and transient errors use safe, bounded retries.
Martini capabilities used
- API consumption
- API exposure
- workflows
- data mapping
- business rules
- idempotency
- error handling
Pattern 3: Synchronize inventory by channel
When to use this pattern
Use this pattern when warehouse or ERP quantities must update commercetools InventoryEntries, or when commercetools inventory changes must reach availability and fulfillment systems. Supply channels, variants, reservations, restockable quantities, and expected quantities require explicit mapping.
Integration direction
Example Mapping
| commercetools Field | Canonical Field | Target Field |
|---|---|---|
| InventoryEntry.sku | variantSku | sku |
| InventoryEntry.supplyChannel | fulfillmentChannel | supplyChannel |
| InventoryEntry.quantityOnStock | onHandQuantity | quantityOnStock |
| InventoryEntry.availableQuantity | availableQuantity | availableQuantity |
Martini implementation pattern
Martini consumes warehouse messages or scheduled extracts, maps quantities by SKU and supply channel, validates that the target entry is current, and invokes the appropriate commercetools update action or import process. It records source timestamps and identifiers to prevent stale or duplicate updates.
Martini capabilities used
- workflows
- messaging or event processing
- scheduled synchronization
- data mapping
- validation
- error handling
Pattern 4: Load and reconcile a large catalog
When to use this pattern
Use this pattern for initial migrations or high-volume loads where individual HTTP mutations would be inefficient. The Import API is used for supported resource types, while scheduled queries verify completeness and identify rejected or missed items.
Integration direction
Example Mapping
| commercetools Field | Canonical Field | Target Field |
|---|---|---|
| SourceProduct.externalId | productExternalId | key |
| SourceProduct.localizedName | localizedName | name |
| SourceProduct.variants | productVariants | variants |
| SourcePrice.value | moneyValue | prices |
Martini implementation pattern
A Martini workflow extracts source pages, validates and transforms records, submits asynchronous import containers, stores operation identifiers, and polls status. It separates accepted and rejected items, sends actionable errors to an operational queue or report, and runs a later reconciliation workflow against commercetools.
Martini capabilities used
- workflows
- API consumption
- asynchronous orchestration
- data mapping
- JSON handling
- validation
- scheduled reconciliation
Applications commonly integrated with commercetools
commercetools can be integrated with adjacent enterprise applications when organizations need to coordinate commerce data, fulfillment, customer operations, search, or payments. The exact source of truth and synchronization direction should be defined for each implementation.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Salesforce | Synchronize Customers, Orders, and commerce activity with CRM and customer service processes. | commercetools → Martini → Salesforce | Martini consumes commercetools HTTP APIs or subscription messages, maps Customers and Orders to Salesforce objects, applies field and privacy rules, and routes failures for retry or reconciliation. |
| SAP S/4HANA | Exchange Products, prices, inventory, Orders, customers, invoices, and fulfillment information with an ERP. | SAP S/4HANA → Martini → commercetools | Martini orchestrates scheduled or event-driven workflows, transforms ERP product and inventory structures into commercetools resources, and uses update actions or the Import API where appropriate. |
| NetSuite | Send Orders and customer data to ERP processes and receive inventory, item, fulfillment, and financial status. | commercetools → Martini → NetSuite | Martini retrieves Orders and Customers from commercetools, maps them to NetSuite records, and sends fulfillment or inventory updates back through version-aware commercetools actions. |
| Shopify | Coordinate catalog, order, or inventory data when multiple commerce channels operate together. | commercetools → Martini → Shopify | Martini applies an explicit source-of-truth policy, transforms Products, prices, inventory, and Orders between APIs, and uses identifiers and reconciliation checkpoints to prevent duplicate exchanges. |
| Salesforce Commerce Cloud | Synchronize catalog, customer, order, or inventory data during migration or across parallel commerce channels. | commercetools → Martini → Salesforce Commerce Cloud | Martini coordinates staged migration or bidirectional workflows, normalizes variants, localized fields, prices, and inventory, and records item-level errors for replay. |
| ServiceNow | Create operational or service cases from order, customer, delivery, or payment exceptions. | commercetools → Martini → ServiceNow | Martini detects relevant Order or Payment conditions, enriches the payload with commerce context, creates or updates ServiceNow cases, and sends status changes back when required. |
| Algolia | Publish Product and Product Projection data to support product search and discovery. | commercetools → Martini → Algolia | Martini consumes product changes or scheduled pages, produces an Algolia-compatible index document, handles localized and variant fields, and retries transient indexing failures. |
| Adyen | Coordinate payment-related references and status associated with Carts, Payments, and Orders. | commercetools → Martini → Adyen | Martini exposes or consumes controlled payment endpoints, maps payment references and status, correlates callbacks with commercetools resources, and applies idempotency and retry rules. |
How to build a commercetools integration in Martini
Objective
Configure regional API and OAuth endpoints, project keys, client credentials, scopes, and permissions without embedding sensitive values in workflows.
Instructions in Martini
- Store client ID, client secret, project key, regional endpoints, and scopes in Martini secrets or environment configuration.
- Use OAuth 2.0 client credentials and bearer tokens for commercetools API access.
- Grant only the project and store permissions required by the integration.
Objective
Select an event-driven, API-led, import-driven, or scheduled trigger based on the resource coverage and reliability requirements.
Instructions in Martini
- Use a supported subscription destination when the required resource message type is available.
- Expose a Martini API for controlled requests from storefronts or operational applications.
- Use scheduled workflows for initial loads, reconciliation, and unsupported or missed changes.
Objective
Obtain the current commercetools resource or import status rather than relying on incomplete event payloads.
Instructions in Martini
- Call the HTTP API or GraphQL API according to the read requirement.
- Follow pagination and preserve resource identifiers and versions.
- Poll asynchronous Import API operations and capture item-level outcomes.
Objective
Coordinate calls, transformations, business rules, downstream writes, and recovery as a maintainable Martini workflow.
Instructions in Martini
- Separate extraction, canonical mapping, validation, target delivery, and status recording.
- Correlate commercetools identifiers with downstream identifiers.
- Use reusable services or workflow components for common authentication and error handling.
Objective
Convert commercetools objects into target schemas while preserving commerce-specific semantics.
Instructions in Martini
- Map variants, localized fields, currencies, channels, categories, prices, addresses, and statuses explicitly.
- Use action-based update mappings for Carts, Orders, Customers, and Products.
- Keep personal data mappings restricted and mask sensitive values in diagnostics.
Objective
Validate data, select the correct target operation, and prevent stale, duplicate, or unauthorized updates.
Instructions in Martini
- Validate required fields, project context, source timestamps, and permissions.
- Apply idempotency using stable keys and persisted processing state.
- Retry only safe transient failures and avoid retrying validation or permission errors.
Common commercetools data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Product | Product master data, variants, attributes, localized information, prices, images, and product lifecycle management. | SAP S/4HANA, NetSuite, Salesforce Commerce Cloud, Algolia, media platforms | Martini retrieves or receives Product changes, normalizes variants and localized fields, applies source-of-truth rules, and writes through HTTP actions or the Import API. |
| Product Projection | Read-optimized product data for storefronts, search, discovery, and experience-layer applications. | Algolia, Salesforce Commerce Cloud, storefront services, content platforms | Martini consumes paginated or GraphQL-read data, maps search-ready fields, and performs scheduled reconciliation when event coverage is incomplete. |
| Cart | Shopper basket containing line items, prices, discounts, shipping information, and payment-related data. | Storefronts, payment platforms, customer service applications | Martini exposes controlled APIs or consumes requests, retrieves current Carts, applies business rules, and uses commercetools update actions without replacing unrelated data. |
| Order | Confirmed or imported purchase with line items, addresses, payments, shipment information, and order state. | SAP S/4HANA, NetSuite, warehouses, shipping systems, ServiceNow | Martini retrieves the current version, maps order and fulfillment data, invokes appropriate actions, and handles concurrent modification, duplicate, and retry scenarios. |
| Customer | Shopper profile, credentials, addresses, customer groups, and custom fields. | Salesforce, NetSuite, identity and loyalty platforms, customer service applications | Martini applies restricted field mappings and scopes, protects personal data, synchronizes identifiers, and routes validation or duplicate conflicts for review. |
| InventoryEntry | Product-variant inventory quantity and availability associated with a supply channel. | SAP S/4HANA, NetSuite, warehouse systems, fulfillment and search platforms | Martini maps quantities, channels, and availability semantics, processes events or scheduled pages, and applies idempotent updates with reconciliation. |
Authentication and security considerations
OAuth 2.0 and project access
commercetools uses OAuth 2.0 client credentials, bearer access tokens, project-scoped API clients, scopes, and permissions. Tokens have finite lifetimes and must be renewed by the integration.
Martini security model
Store client IDs, client secrets, project keys, regional endpoints, and related configuration in Martini secrets or environment-specific properties. Use least-privilege permissions for each workflow and avoid logging credentials, tokens, or unnecessary personal data.
- Restrict access to required projects, stores, resources, and operations.
- Mask customer addresses, email data, credentials, and payment-related values in diagnostics.
- Separate development, test, and production credentials and endpoints.
Operational considerations for commercetools integrations
Pagination and rate limits
Collection APIs are paginated, and large synchronizations should handle page limits, throttling, timeouts, and transient service failures with bounded backoff.
Versions and idempotency
Many updates require the current resource version and the correct update action. Retrieve the latest resource when safe, prevent duplicate downstream transactions with stable identifiers, and retry concurrent modifications only when the operation is safe.
Events and imports
Subscriptions cover selected message types rather than every operation. Combine event processing with scheduled reconciliation. Import API operations are asynchronous, so persist operation identifiers and process successful, rejected, and partially failed items.
Testing and change management
Test regional configuration, scopes, localized data, variants, channels, currencies, action semantics, schema changes, and failure paths against the target project. Monitor deprecation notices and tolerate additive fields where practical.
Why use Martini instead of scripts or point-to-point integrations?
Orchestration instead of isolated scripts
Martini provides a maintainable workflow layer for OAuth authentication, API calls, event handling, pagination, mapping, business rules, asynchronous imports, and downstream delivery. This keeps commercetools-specific behavior separate from target-system logic.
Reusable integration assets
Teams can expose controlled Martini APIs, reuse authentication and transformation logic, and combine HTTP, GraphQL, messaging, and scheduled processing in one governed integration design.
- Centralize retries, validation, idempotency, and reconciliation.
- Adapt Products, Orders, Customers, Carts, and InventoryEntries to multiple target schemas.
- Monitor workflow outcomes and route rejected or failed items for operational recovery.
Frequently asked questions
commercetools is integrated primarily through its project-scoped HTTP APIs secured with OAuth 2.0. GraphQL supports read-oriented queries, the Import API supports asynchronous bulk loading for supported resources, and Subscriptions publish selected resource-change messages to configured event destinations. Scheduled API queries can provide reconciliation.
Yes. Martini can consume commercetools HTTP and GraphQL APIs, process supported Subscription messages, orchestrate asynchronous Import API operations, map commerce objects, expose controlled APIs, and coordinate downstream workflows. No native Martini commercetools connector is documented in the supplied sources.
No dedicated commercetools connector is required. Martini can integrate using commercetools HTTP APIs, GraphQL queries, OAuth 2.0 authentication, supported subscription or messaging destinations, asynchronous imports, and scheduled workflows.
Lonti does not charge an additional per-connector or per-vendor fee to integrate commercetools. Integrations are subject to the provisioned capacity of the Martini environment. Separate costs may apply from commercetools, infrastructure, messaging providers, or other third-party systems depending on subscriptions, usage, and deployment model.
Use the HTTP API for resource mutations, update actions, project operations, and API behavior that depends on commercetools versions and action semantics. Use GraphQL for read-oriented queries where a tailored response is useful. Both can be used in the same Martini workflow.
commercetools provides Subscriptions that publish selected resource-change messages to configured destinations, including supported cloud messaging and event services. Coverage depends on the resource and message type, so they should not be treated as universal webhooks for every operation. Martini can process the resulting events where the deployment supports the destination.
Use subscription messages for supported incremental changes, paginated HTTP or GraphQL queries for reads and reconciliation, and the Import API for supported high-volume asynchronous loads. Martini can store checkpoints and import identifiers, reconcile missed events, and route rejected items for correction and replay.
Martini maps Products, Product Projections, Carts, Orders, Customers, and InventoryEntries into canonical and target models, applies validation and business rules, and uses bounded retries for transient failures. Workflows should preserve commercetools resource versions, use update actions, apply idempotency, and distinguish validation, permission, concurrency, and throttling errors.
Related Martini documentation
API Integration
Connect commercetools with Martini
Use Martini to build governed commercetools integrations across APIs, subscription events, asynchronous imports, and enterprise workflows.