This repository provides a production-ready commercetools Connect connector that integrates commercetools Composable Commerce with Stripe Tax for automated sales tax calculation and transaction reporting.
The connector enables real-time tax calculation during checkout and synchronizes completed orders to Stripe for tax compliance and reporting. It uses Cart and Order data models from commercetools, API Extensions for real-time tax calculation, and asynchronous Subscriptions for order synchronization.
Users are expected to create API client responsible for API extension creation as well as fetching cart and order details from composable commerce project, API client should have enough scope to be able to do so. These API client details are taken as input as an environment variable/ configuration for connect. Details of composable commerce project can be provided as environment variables (configuration for connect) CTP_PROJECT_KEY , CTP_CLIENT_ID, CTP_CLIENT_SECRET, CTP_SCOPE, CTP_REGION. For details, please read Deployment Configuration.
Users are expected to have a Stripe account with Stripe Tax enabled. The Stripe API token is required for tax calculations and order synchronization. API token can be provided as environment variable (configuration for connect) STRIPE_API_TOKEN. For details, please read Deployment Configuration.
Stripe Tax Setup Requirements:
The connector contains two separate modules:
Provides a REST API to calculate tax amounts through Stripe Tax by processing cart details. It is triggered automatically by commercetools API Extension when a cart (in frozen state with tax mode as ExternalAmount) is created or updated.
Key Capabilities:
For detailed documentation, see Tax Calculator README
Receives messages from commercetools project when orders are created. The order and cart details are synchronized to Stripe Tax as transactions for accounting, compliance, and tax reporting purposes.
Key Capabilities:
For detailed documentation, see Order Syncer README
┌─────────────────────────────────────────────────────────────────┐
│ commercetools Platform │
├─────────────────────────────────────────────────────────────────┤
│ Cart Creation/Update │ Order Created │
│ (ExternalAmount mode) │ (OrderCreated event) │
└──────────┬─────────────┴──────────────────┬─────────────────────┘
│ │
│ (1) API Extension Trigger │ (4) Pub/Sub Message
│ │
▼ ▼
┌─────────────────────┐ ┌─────────────────────┐
│ Tax Calculator │ │ Order Syncer │
│ (Service) │ │ (Event Handler) │
│ │ │ │
│ - Tax Calculation │ │ - Order Sync │
│ - Address Validation│ │ - Transaction Create│
│ - Tax Code Resolve │ │ │
└──────────┬──────────┘ └──────────┬──────────┘
│ │
│ (2) Stripe Tax API │ (5) Stripe Tax API
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ Stripe Tax Platform │
│ - Tax Calculations │ - Tax Transactions │
│ - Address Validation│ - Tax Reporting │
└─────────────────────────────────────────────────────────────────┘
Follow guidelines here to register the connector for public/private use in commercetools Connect.
In order to deploy your customized connector application on commercetools Connect, it needs to be published. For details, please refer to documentation about commercetools Connect
In addition, in order to support connect, the tax integration connector template has a folder structure as listed below
├── tax-calculator
│ ├── src
│ ├── test
│ └── package.json
├── order-syncer
│ ├── src
│ ├── test
│ └── package.json
└── connect.yaml
Connect deployment configuration is specified in connect.yaml which is required information needed for publishing of the application. Following is the deployment configuration used by tax calculator and order syncer modules
deployAs:
- name: tax-calculator
applicationType: service
endpoint: /taxCalculator
scripts:
postDeploy: npm install && npm run connector:post-deploy
preUndeploy: npm install && npm run connector:pre-undeploy
configuration:
standardConfiguration:
- key: CTP_REGION
description: region of commercetools composable commerce project
securedConfiguration:
- key: CTP_PROJECT_KEY
description: commercetools composable commerce project key
- key: CTP_CLIENT_ID
description: commercetools composable commerce client ID
- key: CTP_CLIENT_SECRET
description: commercetools composable commerce client secret
- key: CTP_SCOPE
description: commercetools composable commerce client scope
- key: STRIPE_API_TOKEN
description: API Token for communication between the connector and tax provider
- name: order-syncer
applicationType: event
endpoint: /orderSyncer
scripts:
postDeploy: npm install && npm run connector:post-deploy
preUndeploy: npm install && npm run connector:pre-undeploy
configuration:
standardConfiguration:
- key: CTP_REGION
description: region of commercetools composable commerce project
securedConfiguration:
- key: CTP_PROJECT_KEY
description: commercetools project key
- key: CTP_CLIENT_ID
description: commercetools client ID
- key: CTP_CLIENT_SECRET
description: commercetools client secreet
- key: CTP_SCOPE
description: commercetools client scope
- key: STRIPE_API_TOKEN
description: API Token for communication between the connector and tax provider
us-central1, europe-west1)inclusive or exclusive)'{"US":"exclusive","DE":"inclusive"}')true or false, default: false)usd)For detailed configuration documentation, see:
We have provided comprehensive unit and integration test cases with Jest and supertest. The implementation is under test folder in both tax-calculator and order-syncer modules. It is recommended to implement additional test cases based on your specific needs.
For issues, questions, or contributions, please refer to the project repository or contact the development team.