Skip to content

voucherifyio/commerce-tools-integration

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

719 Commits

voucherify-service

voucherify-service

 
 

.DS_Store

.DS_Store

 
 

.gitignore

.gitignore

 
 

LICENSE.md

LICENSE.md

 
 

README.md

README.md

 
 

connect.yaml

connect.yaml

 
 

Repository files navigation

commerce-tools-integration

Licence version code size

Voucherify's commercetools connector extends its discount capabilities with unique promo codes and advanced incentives, as well as with referral, gift card, and loyalty programs supported by Voucherify promotion engine.

Demo store https://sunrise-ct-voucherify.herokuapp.com

How does the integration between Voucherify and commercetools work?

The integration between Voucherify and commercetools allows your customers to use Voucherify-generated promotions in a store built on top of commercetools. We support all Voucherify campaigns.

We support coupons campaigns, including:

If we want to allow customers to use coupons defined in Voucherify, the integration application needs to:

  1. Watch cart updates on the commercetools’ side. If a customer adds a coupon code, use Voucherify API to validate coupons, get discount details and apply discounts back to the commercetools cart.
  2. Record fulfilled orders from commercetools on the Voucherify’s side using Voucherify redeem endpoint.

commercetools & Voucherify integration flow chart

In addition, we suggest synchronizing your customer, product, and order data between commercetools and Voucherify, so you can use that data to build more advanced promotion campaigns.

Commercetools API limits

To assure good performance for every project using commercetools Composable Commerce, the API imposes limits on certain parameters and objects.

TaxCategories:

Product Types:

Extensions:

  • A maximum of 25 Extensions can be created per project.

Warning

Voucherify's commercetools connector utilizes the commercetools API Extension mechanism, which allows the integration itself to be independent of the store front's implementation. This makes it easier to understand how the integration works, which is helpful when you build a solution for educational purposes. Unfortunately, the API Extension mechanism has limitations: each registered extension is called by commercetools synchronously. This affects the response time of the commercetools API itself and forces the promotion system to be treated as a critical system from the store's point of view. This approach is not always optimal and we recommend the following solution. Consider the implementation ofthe integration in an intermediary layer in communication between the store-front and the commercetools API. This way, you can use the patterns of asynchronicity, progressive enhancement, and the fallback pattern.

How to work with commercetools API Extensions?

Because we have organized our repository as monorepo to comply with the commercetools Connect platform, all npm commands should be executed inside the /voucherify-service folder. Our integration uses commercetools API Extensions to monitor cart and order updates. But, before commercetools can send us HTTP requests with cart and order update details, we need to register API Extension and let commercetools know under which public URL our integration is available. There are two scenarios. First, if you run the integration on a publicly available server, you can register or unregister commercetools API Extension using npm run api-extension-add, npm run api-extension-delete or npm run api-extension-update commands. Those commands use the APP_URL environment variable as the public server address where commercetools will send cart and order updates. The second scenario is when you develop or test integration locally, and your PC does not have public IP or domain. In that case, you need to use a reverse proxy (e.g., ngrok) solution to expose your local integration application. To simplify this process, we built a script npm run dev:attach that runs an ngrok reverse proxy service, uses a randomly generated ngrok public URL to register API Extension in commercetools and start our application.

graph LR;
    U((User))
    SF(Store front)
    CT(commercetools)
    V(Voucherify)
    I(Integration App)

    U-- Browse -->SF
    SF-- GraphQl -->CT
    CT-. API Extension .->I
    I-. REST API .->CT
    I-.  REST API .->V

Please note:

  1. commercetools API Extensions pointing to the server that does not respond or does not exist will block your commercetools API. Therefore, you must ensure that you have registered in commercetools only required API Extensions pointing to working servers. You can list currently registered API Extensions using npm run api-extension-list command.
  2. npm run api-extension-delete and npm run api-extension-update commands recognize their own API Extension records by the key value configured in COMMERCE_TOOLS_API_EXTENSION_KEY environment variable (default value is VOUCHERIFY_INTEGRATION

Cart updates

Handling API Extensions request from commercetools with information about cart update is the heart of the integration. Upon receiving cart update requests, the integration app will:

  • Set custom cart fields definition for newly created carts where we will keep information about applied discounts.
  • Validate discounts using Voucherify API, sending collected information about cart items and discount codes.
  • Update cart custom fields with the data which coupons were applied or not.
  • Apply the percentage or amount discount to the cart by adding a custom line item.
  • Add required promotional products to the cart (if unit type discount is used).

Please note that by putting information about applied discount codes in the cart custom fields, we bypass the commercetools Discount Codes feature. This approach lets us prevent confusing Voucherify with commercetools discounts but also requires little changes on the store frontend that uses commercetools API. Primarily, you had to change how you add and read discount codes from commercetools API and use the discount_codes cart custom field instead of the commercetools addDiscountCode action. For development purposes, we prepared Sunrise Storefront for Commercetools adjusted to work with discount coupons managed by Voucherify. The README.md file describes all required changes in detail.

How set up the development environment?

  1. Create new Voucherify and commercetools trial accounts.
  2. Load test data to commercetools using Sunrise Data project and follow instructions in the README.md file.
  3. Install the integration app locally following the Installation and configuration guide.
  4. Install Sunrise Storefront adjusted to work with Voucherify discounts, following the instruction from the "Installation" section of the README.md file.

Prerequisites

Infrastructure

Handling cart updates (validating coupons, getting promotions, releasing sessions):

graph LR;
    I((integration service))
    CT(commercetools service)
    CustomTypes(custom-types service)
    TaxCategories(tax-categories service)
    V(voucherify service)
    VC(voucherify-connector service)
    SA(store data/actions)
    APIE(api extension)

    APIE--commercetools cart-->CT
    CT--actions-->APIE
    CT--create class-->SA
    CT--integration cart, store data/actions, ?helper to get products-->I
    I--validationg coupons and promotions, releasing sessions-->V
    V-->VC
    I--geting ids/SKU/prices of products to add for unit type coupons-->CT
    CT--getting custom type schema for coupons-->CustomTypes
    CT--getting coupons taxcattegory if application applies a cart discounts by adding a custom line items-->TaxCategories

Please note that we are getting cart through API Extension, so we have max ~2000ms to send response, otherwise any cart change will be cancelled. That is why we need to be able to handle such events by asking commercetools if cart was successfully updated (see MAX_CART_UPDATE_RESPONSE_TIME_WITHOUT_CHECKING_IF_API_EXTENSION_TIMED_OUT for more information).

This app is created this way to give us option to swap in the future commercetools service (commercetools store) with any other store service if needed. Integration service in order to return data to commercetools service while handling cart updates requires 2 variables (cart (integration type) and storeData class)). Integration will set available promotions, applicable coupons,inapplicable coupons and more in StoreData class. When finished StoreData class should have all data needed to create response.

Handling order updates (redeeming order if order status is Paid):

graph LR;
    I((integration service))
    CT(commercetools service)
    V(voucherify service)
    VC(voucherify-connector service)
    APIE(api extension)

    APIE--commercetools order-->CT
    CT--integration order-->I
    I--redeeming order-->V
    V-->VC

Please note that we are using api extension, but we are not returning any actions to modify order.

Integration service just need to get order (integration type) and redeeming should happen.

Installation and configuration guide

Dependencies

  • Node.js >= 16.15.0
  • npm >= 8.5.5

Configuration

Set environment variables with credentials to Voucherify and commercetools APIs. For local development, put the configuration into .env file (see .env.example configuration template).

  • APP_URL (or CONNECT_SERVICE_URL) - a public URL where the application is hosted. commercetools will use this URL to make API Extension HTTP requests. This configuration is ignored for local development servers as ngrok provides a public URL dynamically. Please, note that CONNECT_SERVICE_URL environment variable is used by Commecetools Connect.
  • In Voucherify, go to Project Dashboard > Project Settings > General Tab > Application Keys.
    • VOUCHERIFY_APP_ID
    • VOUCHERIFY_SECRET_KEY
    • VOUCHERIFY_API_URL
  • In commercetools, credentials are available when a new API Client is created. You can create it in Settings > Developer Settings > Create new API client (top right corner) using the Admin client scope template.
    • COMMERCE_TOOLS_PROJECT_KEY
    • COMMERCE_TOOLS_AUTH_URL
    • COMMERCE_TOOLS_API_URL
    • COMMERCE_TOOLS_ID
    • COMMERCE_TOOLS_SECRET
  • Additional configuration variables
    • (optional) COMMERCE_TOOLS_COUPON_NAMES - stringifies object with possible values used as a coupon label in order summary, for example COMMERCE_TOOLS_COUPON_NAMES='{"en":"Coupon codes discount","de":"Gutscheincodes rabatt"}'
    • (optional) COMMERCE_TOOLS_API_EXTENSION_KEY - value used in API Extension key attribute used to recognize its own API Extension records, default value is: VOUCHERIFY_INTEGRATION
    • (optional) LOGGER_PRETTY_PRINT - true to get console output in the text format (JSON by default).
    • (optional) COMMERCE_TOOLS_WITH_LOGGER_MIDDLEWARE - false to disable debugger mode in commercetools connector.
    • (optional) API_EXTENSION_BASIC_AUTH_PASSWORD - (String) protects your API Extension URL from unwanted traffic.
    • (optional) CUSTOM_NGROK_BIN_PATH - a custom path to your ngrok binary file e.g /opt/homebrew/bin for Macbook M1 cpu
    • (optional) PORT - application port (default is 3000)
    • (optional) LOGGER_LEVEL - logging level for npm run test. You can set it to error or fatal.
    • (optional) DEBUG_STORE_REQUESTS_IN_JSON - true if you want to keep external requests / response in a JSON file.
    • (optional) DEBUG_STORE_REQUESTS_DIR - name of the directory where JSON files with request / responses are stored.
    • (optional) COMMERCE_TOOLS_COUPONS_LIMIT - maximum number of coupons that could be applied to cart. Default value is 5, maximum 30 related to Voucherify Api
    • (optional) DISABLE_CART_PROMOTION - allow to disable cart level promotion functionality. It will reduce number of api calls because it's remove usage of promotion validation request from all cart related operation.
    • (optional) APPLY_CART_DISCOUNT_AS_CT_DIRECT_DISCOUNT - by default, the application applies a cart discount by adding a custom line item. Set this option value as true to enforces the application to use the commercetools beta feature called direct discounts to apply discounts on the cart.
    • (optional) MAX_CART_UPDATE_RESPONSE_TIME_WITHOUT_CHECKING_IF_API_EXTENSION_TIMED_OUT - default 1000[ms]. Accepts range of numbers 0 - 1750. If set to 0 we will always be checking if application responded to API Extension within acceptable time window. If set higher, for example 1000(default) that means that we will be checking if we responded to API Extension only if building actions (validating coupons) took more than 1000ms. NOTE: This checking only happens when cart has at least 1 coupon active(added to cart).

Installation

Set up the configuration for the first run.

npm run config

For production

npm install
npm run build
npm run start
npm run api-extension-add

For local development (ngrok required)

npm install
npm run dev:attach

For development with public URL

npm install
npm run dev
npm run api-extension-add

Tests

npm run test

We have created integration tests to cover the most important scenarios connected with handling validation process and operations on cart. We mocked requests from commercetools and Voucherify to check behaviour of our application. You can examine tests here and mocks here: 1, 2, 3, 4. Currently, we cover the following scenarios:

  • creating a new cart (cart.version = 1)
  • running API extension without any applied coupons (testing integration between V% and CT)
  • running API extension when removing currently applied coupons
  • adding an amount type coupon
  • adding a percentage type coupon
  • adding the same single use coupon in a different session
  • adding coupons which don't exist
  • adding a second amount type coupons right after a percentage type coupon
  • changing the quantity of products with an applied amount and percentage type coupons

CLI

  • npm run start - start the application in production mode
  • npm run dev - start the application in development mode
  • npm run api-extension-add - add commercetools API Extension pointing to your server (server url is taken from APP_URL environment variable)
  • npm run api-extension-delete - remove commercetools API Extension by Key value configured in COMMERCE_TOOLS_API_EXTENSION_KEY environment variable. Optionaly you can provide specific API Extension Id by npm run api-extension-delete -- --id=xxx-xxx-xxx
  • npm run api-extension-update - remove old and add new API Extension pointing to your server, url is taken from APP_URL environment variable, old API Extension is recognized by API Extension key configured by COMMERCE_TOOLS_API_EXTENSION_KEY environment variable
  • npm run api-extension-list - list all commercetools API Extensions
  • npm run dev:attach - start the application in development mode including:
    • launching ngrok and collecting dynamically generated URL
    • updating commercetools API Extension to point to our development server
  • npm run config - set up the required basic configuration in commercetools:
    1. custom coupon type - needed to store coupons codes inside the Cart object
    2. coupon tax category - needed for any coupon or gift card with a fixed amount discount
  • npm run test - run Jest tests
  • npm run migrate - migrate data from commercetools to Voucherify. Arguments:
    • type - required - type of data which you want to migrate. Values: products, orders, customers
    • days - optional - set number of days to sync from the past. Value: number
    • hours - optional - set number of hours to sync from the past. Value: number
    • ms - optional - set number of milliseconds to sync from the past. Value: number
    • date - optional - set date from which the resources are to be migrated. Format: YYYY-MM-DD
    • longdate - optional - set date and time from which the resources are to be migrated. Format: YYYY-MM-DDTHH:MM:SS
      Examples:
    • npm run migrate -- --type=products
    • npm run migrate -- --type=orders --days=5
    • npm run migrate -- --type=customers --longdate=2022-03-21T21:04:37

REST API Endpoints

  • GET / - welcome application message
  • POST /api-extension - handle API extension requests (cart) from commercetools
  • POST /types/configure - trigger coupon types configuration
  • POST /tax-categories/configure - trigger coupon tax configuration (equal to npm run config)

Heroku deployment

Requirements

Configuration

  1. Create a new application on your Heroku account with a given <application_name>
  2. Go to your <application_name> -> Settings -> Reveal Config Vars
  3. Configure your commercetools application and set up environment variables see Configuration
  4. Add buildpacks (in order):
  1. Set APP_BASE environment variable to voucherify-service

Deployment

Fork

  1. Fork this repository
  2. Clone your fork
git clone <fork_name>
  1. Login to your Heroku account
heroku login
  1. Create a remote branch for Heroku deploy
heroku git:remote -a <application_name>
  1. You don't need to create any procfile. By default, Heroku recognizes package.json and run npm install and npm start.
  2. Deploy the code
git push heroku master # For master branch
git push heroku main # For main branch
git push heroku <branch_name>:main # For other branch

New repository

  1. Go to the source code folder
  2. Login to Heroku account
heroku login
  1. Init git repository
git init
git add .
git commit -m "Init"
  1. Create a remote branch for Heroku deploy
heroku git:remote -a <application_name>
  1. Deploy the code
git push heroku master # For master branch
git push heroku main # For main branch
git push heroku <branch_name>:main # For other branch

Configure commercetools

  1. Go to your <application_name> -> More -> Run console
  2. Run npm run config

This command should be run once shortly after you deploy your application, and each time when your commercetools project change the list of countries in which it operates.

Register API Extension

  1. Go to your <application_name> -> More -> Run console
  2. Run npm run api-extension-add

This command should be run once (or each time after npm run api-extension-delete).

Sync

Data migration allows us to handle more advanced features of Voucherify, so it is important to keep data updated (however it is still optional if you use only basic functionalities). Migration is done via npm run migrate commands. When you are launching the integration app the first time you should fetch all data (products, orders, customers). After that to keep Voucherify updated it will be convenient to sync data once in a while. To not process all the data each time you can pass additional arguments (e.g. days, date) to shorten the sync period and as a result decrease time of these operations. You can do it manually, but we highly recommend automating this process with some tool like Cron. The period between syncs should depend on traffic on your platform or the time when new vouchers, campaigns, etc. are created to make them as close to the newest data as possible.

Metadata

Additionally, each time migration happen metadata will be tried to sync. Metadata is a feature of Voucherify which allows you to create more specific vouchers and campaigns. These properties are mapped from names of custom fields from commercetools for customer, from attributes for products and from attributes and names of custom fields from order (please add custom_field_). You can set which metadata you want to have by setting it in Voucherify -> <your profile> -> Project Settings -> Metadata Schema. During redemption an order and a product sku included in this specific order metadata will be tried to sync too.

Important

  1. If you set some metadata in Voucherify to required, and this attribute would not be on your resource in commercetools, then whole operation will fail!
  2. Make sure that Voucherify metadata it's defined properly. If set types are not compatible with data provided by CT update may fail.
  3. Syncing customers uses CT Custom Fields.
  4. Syncing products uses Attributes. In this case be sure you provide CT Attribute identifier instead on Attribute label. You can check this under Settings -> Product types and attributes tab.
  5. Syncing orders uses CT Custom Fields when starts with custom_filed_, otherwise uses Properties of Commercetools Orders for example: shippingAddress or country. EXCEPTION: for payments add payments instead of paymentInfo.

Coupon text

All discounts are added as one CustomLineItem with a negative price. This item should be visible to the customer on the invoice to know how the price is affected. To make this readable for each customer we provide the possibility to change the name of this item depending on the language which customer uses. To make it work correctly, a developer should add COMMERCE_TOOLS_COUPON_NAMES environment variable, with stringified object, where keys are an IETF language tags and its values are coupon names translated to that languages. Later on, the text will be automatically chosen by the commercetools mechanism to match the language proper for a customer.

Example: '{"en":"Coupon codes discount","de":"Gutscheincodes rabatt"}'

Free shipping

Free shipping is one of our discount codes type. To handle this case You must define Free shipping code. You can define it on two ways:

  1. You can create predefined coupon with Free shipping type. This coupon is connected to pre created product with source id = 5h1pp1ng. In this case You can clearly define coupon type by this ID because it's given by Voucherify and cannot be changed. Make sure to change in V% dashboard product with source ID "5h1pp1ng" to 0$

    Voucherify freeshipping configuration

  2. To create new or use existing product which will represent Your shipping method. If you have chosen your product now You can create new discount with unit type of this product. Make sure to set price of this product to 0$

When you apply whichever of this discount code, the connected product id it will be set to commercetools cart custom field named shippingProductSourceIds. Next step is to properly define shipping method in Your commercetools panel and configure Predicates. Go to Settings -> Project settings -> Shipping methods. Use existed or create new shipping method which will be applied if one of codes will be used. In Shipping method -> Predicate field You can define condition when a given shipping method will be available. To allow uses to use Your new free shipping method you need to define formula.

custom.shippingProductSourceIds contains any ("5h1pp1ng") - this formula is used for default free shipping code with predefined source id = 5h1pp1ng CT shipping free method

custom.shippingProductSourceIds contains any ("<your_source_id>") - this formula should be used when you want to apply this shipping method with custom vourcherify shipping method.

To learn more about predicates You can see here.

To set new free shipping method by default after applying a code in our Sunrise fork set key field in the shipping configuration to FREE_SHIPPING_DEFAULT.

Important

  1. Make sure that you customField definition is properly set. You can run npm run config to make this configuration.
  2. If you choose free shipping code with custom product make sure that this product is properly defined in commercetools and can be applied to cart.
  3. Make sure You configure zones and shipping rates in Your shipping method in commercetools.

Loyalty program

Currently, we support a few cases related to loyalty program. Firstly we provide earning points by paying orders and using rewards with type pay with points. To handle other type rewards like getting coupon for points You can simply use our Customer cockpit

Typical use case

  1. As a customer who opens a store page in the browser (Sunrise Storefront), I add some products to the cart and on the cart page, I add one of the available coupon codes (you can check the available discounts in the Voucherify admin panel for trial accounts you should have preconfigured, e.g., BLACKFRIDAY code).
  2. As a customer who added an existing coupon code, I should see the granted discount value and be able to finish the order.
  3. As the store operator logged into the commercetools panel, I see new orders, including applied coupon codes on the Custom Fields tab and applied coupon discount value in the Order items list.
  4. As the store operator logged into the commercetools panel when I update Order Payment Status to Paid, customer, order, and redeemed objects are created in Voucherify.

Order screen in commercetools Order custom fields in commercetools Redemption screen in Voucherify

Contributing

If you found a bug or want to suggest a new feature, please file a GitHub issue.

Changelog

  • 2024-01-31 v6.0.6
    • remove fallback to coupon.order?.total_discount_amount that caused too great promotions in some cases
    • added test to test this case ^
    • increased limit of coupons that can be applied to cart from 5 to 30 (COMMERCE_TOOLS_COUPONS_LIMIT config var)
  • 2024-01-23 v6.0.5 (versions v6.0.1 - v6.0.4 were not released to the public)
    • added more tests, moved all tests to voucherify-service/test folder
    • updated dependencies
    • added npm run config to npm run ct-connect-post-deploy command
    • added channel header to V% requests.
    • added support for V% partial redeem/validation mode.
    • code refactoring (lowering cognitive complexity)
    • fixed bug in productsToAdd function related to CT price selector.
  • 2023-05-16 v6.0.0 adjust application structure to be compliant with commercetools Connect platform
  • 2023-05-11 v5.2.3
    • adjust application to work with Commercetools Connect platform:
  • 2023-05-05 v5.2.2
    • do not make unnecessary, malformed requests to CT for a products
    • update tests
    • for used cart promotions, separate promotion id from promotion banner
    • fixed console logging data while using migration CLI
  • 2023-05-04 v5.2.1
    • minor bugfix, when someone have defined unit type promotion/voucher in Voucherify dashboard not based on commercetools products, we should not be looking for this product in commercetools backend store.
  • 2022-12-07 v5.2.0
    • domain refactoring/code quality
    • optimization
    • adding new config var: MAX_CART_UPDATE_RESPONSE_TIME_WITHOUT_CHECKING_IF_API_EXTENSION_TIMED_OUT (default value 1000[ms]). For more info check configuration section.
  • 2022-10-26 v5.1.2
    • cashing coupons tax category
  • 2022-10-19 v5.1.1
    • refactoring/code quality
    • added unit tests for DirectDiscount
    • readme update, adding some descriptions
    • minor fix for corner case for unit type discount
  • 2022-10-12 v5.1.0
    • added support of DirectDiscount. If you want to use DirectDiscounts please make sure you added APPLY_CART_DISCOUNT_AS_CT_DIRECT_DISCOUNT=true to your config file.
    • metadata for order now uses Properties of Commercetools Orders for example: shippingAddress or country or Custom Fields when starts with custom_filed_. Because of that, this version is not fully compatible with the previous one.
    • improvement of displaying promotion banner
    • adding option to disable by setting environment variable cart level promotion functionality (see section Additional configuration variables for more information).
    • new orders migrated from commercetools will be set with correct status PAID or CREATED
    • sometimes application was unstable, we fixed it by catching the errors better.
    • in case of cart level promotion, information about a customer will be provided (for example for validations purposes)
    • we fixed several minor bugs with unit type coupons
  • 2022-09-15 v5.0.1
    • fixes to unit type discount
  • 2022-09-14 v5.0.0
    • this version is not fully backward compatible due to changes in a way how coupon text is configured
    • change configuration of coupon text from config in a .ts file to config via COMMERCE_TOOLS_COUPON_NAMES environment variable
    • fix logging list of available api extensions while using npm run api-extension-list command
    • added safeguard when auto-applied coupon failed to keep remaining codes in cart
    • added showing errors when validation failed and there is no safeguards
    • handling configuration for maximum coupons limit
    • adding rollback for coupon validation, session and redemption when connection with CT will time out
  • 2022-09-06 v4.2.2
    • fixed situation when redemptions fails and operations on order are blocked
    • remove additional request to voucherify with metadata
  • 2022-09-05 v4.2.1
    • fixed saving total amount on paid orders
  • 2022-08-26 v4.2.0
    • added support for fixed price promotions
    • bugfixes handling proper price from commercetools when product have only main variant
    • compatible with previews version but required to run npm run config command to proper set new lineItemCustomField
    • bugfixes empty values when applying prepaid gift cards
    • synchronizing orders, with no coupons applied, into voucherify
  • 2022-08-25 v4.1.1
    • added promotion tier handling
  • 2022-08-24 v4.1.0
    • added handling free shipping codes
    • new customField definition added
    • compatible with previews version but required to run npm run config command to proper set new customField
  • 2022-08-19 v4.0.0
    • version not compatible due to changes in a way how Custom Line Item with discount is handled
    • added possibility to set coupon text in order summary depending on the language which customer use
    • added handling proper price from commercetools including the price selector when unit type discount is applied.
  • 2022-08-10 v3.0.5
    • update readme about how handle metadata
  • 2022-08-09 v3.0.4
    • updating metadata in order and order product skus during redemption action.
  • 2022-08-08 v3.0.3
    • update rate limiter in orders sync - now there are used methods, from new voucherify sdk, to get limit information, instead of using fetch library for that
  • 2022-08-05 v3.0.2
    • many thanks again to @Irene350 for your contribution!
    • optimising the code to retrieve all the project countries for coupon tax category (npm run config)
    • refactoring
    • minor changes in readme (npm run config)
  • 2022-08-05 v3.0.1
    • fix period argument of migrate command
  • 2022-08-03 v3.0.0
    • many thanks to @Irene350 for your contribution!
    • this version is not fully backward compatible because of differences in migration commands
    • added sync of customers who made an order without account
    • enhanced CLI: removing three migrate-... commands and replace them with one migrate with several options
    • added migration of metadata: as metadata from commercetools side are considered custom fields in case of orders and customers and attributes in case of products
    • readme update
  • 2022-08-02 v2.0.0
    • version v2.x is not fully backward compatible with version v1.x, please refer to Migration from v1.x.x to v2.x.x section
    • fixing the issue with removing the commercetools API Extension pointing to other integrations
    • removed CLI commands: register and unregister
    • added CLI commands: api-extension-add, api-extension-update, api-extension-delete and api-extension-list
    • added new optional configuration (COMMERCE_TOOLS_API_EXTENSION_KEY environment variable) to recognize own commercetools API Extension from 3rd party ones when performing delete or update operations
    • remove coupon from session when coupon is deleted from a cart, it requires Sunrise Storefront v2.0.0
  • 2022-07-28 v1.0.1 Update README.md file
  • 2022-07-26 v1.0.0 Initial release

Migrations

Migration from v4.x.x to v5.x.x

  • stringify object from src/misc/coupon-text.ts file and insert it as a value for COMMERCE_TOOLS_COUPON_NAMES environment variable
  • run npm i
  • run npm run config command to proper set custom field isValidationFailed and couponsLimit

Migration from v3.x.x to v4.x.x

  • if you are using sunrise, update it to version v.3.0.0 or higher
  • if there exists carts with added coupons, now it will be impossible to remove them properly from cart - write simple script, which will list all existing carts and then delete them

Migration from v2.x.x to v3.x.x

  • run npm i, because of using new version of Voucherify SDK, which can handle metadata schemas
  • replace all migrations commands npm run migrate-products, npm run migrate-orders, npm run migrate-customers with npm run migrate -- --type=products, npm run migrate -- --type=orders, npm run migrate -- --type=customers

Migration from v1.x.x to v2.x.x

  • replace old commercetools API Extensions pointing to your integration application:
    • list all existing commercetools API Extension by npm run api-extension-list command
    • if there are existing commercetools API Extensions pointing to your integration app with empty value in Key columns, remove this API Extension by id value using npm run api-extension-delete -- --id=xxx-xxx-xx command
    • ensure that you have configured APP_URL environment variable
    • add new API Extension using npm run api-extension-add command
  • use npm run api-extension-update instead of npm run register command
  • use npm run api-extension-delete instead of npm run unregister command

Contact

If you have questions, comments, or need help with the code, we're here to help:

For more tutorials and full API reference, visit Voucherify Developer Hub.

Final words

We believe that the commercetools setup can vary between implementations and integration requirements may differ in each case. Because of that, we distributed integration between Voucherify and commercetools as an open source application so that everyone can download, host, and adjust the solution to their unique business requirements.

Licence

MIT Copyright (c) 2022 voucherify.io

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

3 stars

Watchers

2 watching

Forks

2 forks
Report repository

Releases

12 tags

Packages

No packages published

Contributors 8

Languages