Over time the APIs evolve, new methods are added, others removed, and requests and responses are modified. Applications that use Open2b APIs are guaranteed compatibility with previous versions thanks to versioning.
The following are the Open2b versions with the supported API versions:
| Open2b | API |
|---|---|
| 2012 | v1 |
| 2013 | v1 and v2 |
| 2015 | v1 and v2 |
| 2016 | v2 and v3 |
| 2018 | v2, v3 and v4 |
| 2018 GDPR | v2, v3, v4 and v5 |
| 2018 Electronic Invoicing | v2, v3, v4, v5 and v6 |
| 2019 | v2, v3, v4, v5 and v6 |
| 7.0 and 7.1 | v3, v4, v5, v6 and v7 |
| 7.2 | v3, v4, v5, v6, v7, v8 |
| 7.3 | v3, v4, v5, v6, v7, v8 |
| 7.4 | v3, v4, v5, v6, v7, v8, v9 |
| 7.5 | v3, v4, v5, v6, v7, v8, v9, v10 |
| 7.6 | v3, v4, v5, v6, v7, v8, v9, v10, v11 |
| 7.7 | v3, v4, v5, v6, v7, v8, v9, v10, v11, v12 |
| 7.8 and 7.9 | v3, v4, v5, v6, v7, v8, v9, v10, v11, v12, v13 |
If you are building a new application, first consider which Open2b version you need to target, then choose the most recent supported API version.
If the Open2b version is not the latest, consider, or propose to your customer, an upgrade to the most recent version so you can immediately use the latest API version.
The compatibility guarantee lets you build applications for your store or your customers with the confidence that they will continue to work after platform updates, provided that the new Open2b version supports the API version you used, and taking into account any considerations noted at the time of release.
With the compatibility guarantee we commit to not modifying methods, request and response formats, field names, removing or adding fields, changing their types or ordering, or changing the types of error messages returned.
While guaranteeing the above, sometimes functional changes in new Open2b versions may be such that the API cannot guarantee identical behavior in all circumstances. In this case, the documentation will detail which differences you should expect so you can better assess timing and conditions for updating the store and application.
Version 13 was introduced with Open2b 7.8 in September 2025. If you have built applications that use version 12, you can continue to use it or move to the new version by replacing v12 with v13 in the call URL.
Open2b 7.8 introduces support for 4-byte characters (UTF8mb4); API calls (any version) that return text can therefore return 4-byte characters.
storefront.products method, note that the departments field may be empty.storefront.cart method, note that the departments field on items may be empty.commerce.promotions.get and commerce.promotions.find methods, note that the new fields method and isOneTimePerCustomer are returned.It is now possible to set a shipping or payment method to trigger a promotion using the method field.
It is also possible to specify that a promotion can only be used once by each customer using the isOneTimePerCustomer field. Promotion usages in this case can be managed using the new API promotions-usages.
If your app uses the commerce.promotions.find method to retrieve promotions, new condition fields hasCoupon, isOneTimePerCustomer, endTimeFrom, endTimeTo allow more effective searching
Version 12 was introduced with Open2b 7.7 in March 2025. If you have built applications that use version 11, you can continue using it or move to the new version by replacing v11 with v12 in the call URL.
commerce.products.get and commerce.products.find methods, note that the new field showRequestsFor is returned.commerce.returns.get and commerce.returns.find methods, note that the status field of returns and the approval field of return rows can take the new value "Completed".commerce.payment-methods.get and commerce.payment-methods.find methods, note that the new field minAmountPayable is returned.You can now specify when the field for entering requests on individual products should be shown in the cart via the new showRequestsFor field.
You can now indicate that a product return has been completed by setting the return row approval field to "Completed".
You can now specify the minimum payable amount for payment methods via the new minAmountPayable field.
Version 11 was introduced with Open2b 7.6 in October 2024. If you have built applications that use version 10, you can continue to use it or move to the new version by replacing v10 with v11 in the call URL.
The length of all city fields has been increased from 25 to 35 characters.
Version 10 was introduced with Open2b 7.5 in January 2024. If you have built applications that use version 9, you can continue to use it or move to the new version by replacing v9 with v10 in the call URL.
commerce.promotions.get and commerce.promotions.find methods, note that the new fields minQuantity and discountedQuantity are returned
You can now specify the quantity of items in the cart that triggers a promotion and on which items that quantity is calculated via the new minQuantity field.
You can also specify, via the discountedQuantity field, the quantity of items to which the discount will be applied and whether the minimum quantity should be discounted or only the additional quantities after the minimum.
Version 9 was introduced with Open2b 7.4 in May 2023. If you have built applications that use version 8, you can continue to use it or move to the new version by replacing v8 with v9 in the call URL.
site.blog-post.get and site.blog-post.find methods, note that the new field tags is returned.commerce.promotions.create and commerce.promotions.update methods, note that the startTime and endTime fields have changed type from date to datetime.
commerce.promotions.get and commerce.promotions.find methods, note that:
startTime and endTime fields have changed type from date to datetime.hourLimits field is returnedTags can be assigned to blog posts to categorize them and make them easier to browse.
Version 9 of the API adds the following methods to Site for working with tags:
and the following method to Storefront
In addition, the blog APIs also return the tags associated with blog posts.
You can now specify a start or end time for promotions. It is also possible, via the new hourLimits field, to specify a daily time window for activation of the promotion.
Version 8 was introduced with Open2b 7.2 in March 2022. If you have built applications that use version 7, you can continue to use it or move to the new version by replacing v7 with v8 in the call URL.
If you prefer to continue using an older version from 3 to 7, consider the following:
site.pages.get, site.pages.find, url-rewrites.find and site.urls.resolve methods and in particular read the resources field that is returned, note that the sub-field type could have the value "Collection", which previously was never returned.url-redirects.find method and in particular read the target field that is returned, note that the sub-field type could have the value "Collection", which previously was never returned.commerce.items.get and commerce.items.find methods, note that the new fields width, height, and depth are returned.commerce.attribute-values.get method, note that the new field products is returned.commerce.tax-areas.get and commerce.tax-areas.find methods, note that the new field code is returned.commerce.shipping-methods.get and commerce.shipping-methods.find methods, note that the new field code is returned.commerce.customer-groups.get and commerce.customer-groups.find methods, note that the new field collection is returned.commerce.customers.get and commerce.customers.find methods, note that the new fields collection and collections are returned.commerce.customers.get and commerce.customers.find methods, note that the new fields collection and collections are returned.site.pages.get, site.pages.find, url-rewrites.find and site.urls.resolve methods and in particular read the resources field that is returned, note that the sub-field type could have the value "Collection", which previously was never returned.url-redirects.find method and in particular read the target field that is returned, note that the sub-field type could have the value "Collection", which previously was never returned.Version 8 adds the new Batch API. The Batch API makes it easier to build procedures and applications that access the product catalog in read-only mode. It enables faster catalog exports, integrations with resellers, and publishing products on comparison sites and marketplaces.
Items have the new fields width, height, and depth which represent respectively the width, height, and depth of an item.
Collections allow you to limit which products are visible on the site to specific customers or customer groups.
Version 8 adds the following methods to Commerce for working with collections:
commerce.collections.findcommerce.collections.getcommerce.collections.countcommerce.collections.createcommerce.collections.updatecommerce.collections.deleteand the following method to Storefront:
Collections are enabled only for the Advanced B2B edition; for other editions the commerce.collections.create and commerce.collections.update methods return a specific error.
Customer groups and customers have been given the collection field which indicates the associated catalog collection. Customers also have the collections field, which indicates the additional collections the customer can access.
To read products that are part of one or more collections, you can use the collections field as a condition in the commerce.products.find method and the collection field as a condition in the storefront.products method.
With version 8 you can read all products that have a specific attribute value via the products field returned by the commerce.attribute-values.get method.
It also allows assigning an attribute value to all and only specific products via the products field of the commerce.attribute-values.update method.
When creating an order with the commerce.orders.create method, you can use the movements parameter to create inventory movements together with the order. For order rows without a code, or for which no item exists with that code, movements will not be created.
Tax areas and shipping methods have the new code field.
The new Storefront method storefront.login-with allows customers to log in via Facebook.
Version 7 was introduced with Open2b 7.0. If you built applications that use API version 2 you must update your applications, as version 2 is no longer supported. You can do so by first moving to version 3 (as indicated in moving from version 2 to version 3). If you built applications that use version 6 you can continue to use it or move to the new version by replacing v6 with v7 in the call URL.
X-Key to X-Secret-Key.commerce.products.create method you must handle the error in case a variant or option does not exist.commerce.products.create, commerce.items.create and commerce.items.update methods, since they now verify that for options the product has the corresponding variant and the option belongs to the variant, you must handle the possible returned error.get and find methods of documents, note that the items field now includes a new id field.commerce.orders.delete method, note that it returns an error if an order has shipments.seoKeywords field you can no longer use it as it has been removed.Open2b 7.0 introduces the new Storefront API which reproduces the store shopping experience.
The HTTP header X-Key, used to authenticate requests, has been renamed to X-Secret-Key. The previous name X-Key can still be used, but not for calls to the new Storefront API, and it will be removed in a future version.
The product code field, the sku and supplierSKU fields of items, and the sku field of documents have been extended from 32 to 40 characters.
The commerce.products.create method now returns an error if a variant or option does not exist.
The commerce.products.create, commerce.items.create and commerce.items.update methods now verify for options that the product has the corresponding variant and that the option belongs to the variant. Otherwise they return an error.
Categories have been removed starting from version 7, therefore category methods are no longer available.
Version 7 enables management of multiples for orders and quotes. For each item you can specify whether the customer can order only multiples of the quantity of the first price tier for orders only, quotes only, or both orders and quotes.
The following methods include the new quantityStepsOn field that indicates whether orders, quotes, or both are allowed only in multiples:
commerce.products.createcommerce.items.createcommerce.items.updatecommerce.items.findcommerce.items.getThe token field has been added to documents (orders, quotes, invoices, receipts and packing slips). The token is 32 ASCII characters long and uniquely identifies a document. The token is assigned automatically when the document is created and never changes.
Document rows (orders, quotes, invoices, receipts and packing slips) now have a new id field that uniquely identifies them. The id field is returned by the get and find methods of documents.
The new id field is primarily used to manage shipments and returns of an order:
items field lists all products that are part of the shipment and within it the orderItem field refers to the id field of an order rowitems field lists all products that are part of the return and within it the orderItem field refers to the id field of an order rowFor the commerce.orders.update method, if you modify items, it becomes important to specify in items the id field of the order item being modified because it is not allowed to remove order rows for which shipments or returns exist.
With the new API version it is possible to manage order shipments. For each order you can create one or more shipments by indicating the order rows that are part of the shipment with the shipped quantity. It is also possible to manage tracking for each shipment. The following methods have been added for this purpose:
commerce.shipments.findcommerce.shipments.getcommerce.shipments.countcommerce.shipments.createcommerce.shipments.updatecommerce.shipments.deleteSince an order cannot be deleted if it has shipments, the commerce.orders.delete method in this case returns an error.
The new API introduces several methods to manage returns. You can create a return for one or more orders and for all or only some of the rows of an order. The following methods have been added for this purpose:
commerce.returns.findcommerce.returns.getcommerce.returns.countcommerce.returns.createcommerce.returns.updatecommerce.returns.deleteReturns are closely tied to shipments because only products that have actually been shipped and delivered can be returned.
Return reasons indicate the reason for each returned product. The following methods have been added for this purpose:
commerce.return-reasons.findcommerce.return-reasons.getcommerce.return-reasons.countcommerce.return-reasons.createcommerce.return-reasons.updatecommerce.return-reasons.deleteReturn rules specify the conditions under which a customer can request a return. The following methods have been added for this purpose:
commerce.return-rules.findcommerce.return-rules.getcommerce.return-rules.countcommerce.return-rules.createcommerce.return-rules.updatecommerce.return-rules.deleteThe commerce.returns.create method does not verify return rules. It is the responsibility of the application that creates a return to verify, for example if the return is made directly by the customer, that the rules allow it.
To check whether return rules allow returns for one or more order rows, the following method has been added:
The locale field has been added.
The order field has been added, indicating the order created from the quote.
The seoKeywords field has been removed.
Version 6 was introduced with Open2b 2018 Electronic Invoicing. If you built applications that use version 5, you can continue to use it or move to the new version by replacing v5 with v6 in the call URL.
With the introduction of electronic invoicing in January 2019, changes were made to customers and documents to allow registration of the recipient code and PEC email address for electronic invoices.
The following have the new field invoiceRecipient, which can contain either the recipient code or the PEC email address to send the electronic invoice to:
Version 5 was introduced with Open2b 2018 GDPR. If you built applications that use version 4, you can continue to use it or move to the new version by replacing v4 with v5 in the call URL.
As part of compliance with the new privacy regulation (GDPR), version 5 of the APIs introduces new methods to manage processing and consents for customers' personal data.
You can define the processing carried out on customers' personal data so the related information notice can be shown on the site and, if needed, request consent for processing. The following methods have been added to the APIs:
commerce.privacy-processings.findcommerce.privacy-processings.getcommerce.privacy-processings.countcommerce.privacy-processings.updatecommerce.privacy-processings.deleteFor each processing and for each customer, order, and quote, you can collect consents given and withdrawn. The following methods have been added for their management:
commerce.privacy-consents.findcommerce.privacy-consents.givecommerce.privacy-consents.withdrawcommerce.privacy-consents.deleteWith the new version of Open2b you can choose, for each department, whether it is visible on the site, visible only if it contains products, or not visible at all, for example because it is still being set up.
For this purpose the new field visibility has been added to the department methods.
For B2B editions it is now possible to choose for each customer group which payment and shipping methods the customer can select in the cart and during checkout.
For this purpose the new fields paymentMethods and shippingMethods have been added to customer groups, which can contain a list of payment and shipping methods that the customer is restricted to.
Version 4 was introduced with Open2b 2018. If you built applications that use API version 1 you must update your applications to use version 2, 3 or 4 because version 1 is no longer supported. In particular, you must first follow the instructions for moving from version 2 to version 3. If you built applications that use version 3, you can:
commerce.price-lists.update method, note that it is no longer possible to read the base price list and the change (discount or markup) of a derived list; the method returns an internal error if the baseList or change argument is provided.commerce.price-lists.get method, note that it is no longer possible to read the base price list of a derived list; the method returns an internal error if the fields field is null or contains baseList.commerce.price-lists.find method, note that it is no longer possible to read the base price list of a derived list; the method returns an internal error if the fields field is null or contains baseList.commerce.price-lists.find method, note that it is no longer possible to sort the returned price lists by the base price list; the method returns an internal error if the order field contains baseList.site.banners methods, note that banners are no longer available. Calls to the site.banners methods return an internal error.site.menus methods, note that menus are no longer available. Calls to the site.menus methods return an internal error.canonicalURL field of the various resources with the get and find methods of version 4.v3 with v4 in the call URL.find methods and do not pass the limit field, or the limit field is null, note that these methods in version 4 may return more results than you expected previously. You have two options:
limit field with the maximum value expected by the version 3 method called, generally 100.limit field or pass it as null and leverage the fact that version 4 methods return more results than before.commerce.price-lists methods, note that what used to be price list properties are now split between price lists and customer groups, so you may need to make additional calls to commerce.customer-groups.commerce.customers methods to read or modify the priceList field, note that this field is now called group.commerce.customers.create and commerce.customers.update methods to set customer passwords and use the cryptedBy field with value "CommerceReady", you must replace it with "Open2b".commerce.products.find method with an order field that includes "position", then add "id" after "position" to have products ordered the same way as before.commerce.products.get, commerce.products.find, commerce.items.get and commerce.items.find methods and read the departments field, note that this field no longer contains the department levels from the top department to the final one but contains the final departments where the product is located. This is because a product can now be in multiple departments. To get all departments from the highest level to the lowest, you can call the commerce.departments.get method and read the ancestors field.commerce.products.create method, you must rename the department field to departments and pass the value in an array. For example if department was 56 then departments should be [ 56 ].commerce.products.update method and pass the department field, note that it has been renamed to departments and now contains all product departments, up to five. If you are sure the product is in a single department, follow the instructions in the previous point. If the product may be in multiple departments, you must modify your program to pass all departments to the method.0.000 as the price, it now returns null.0.000 you must now use null to indicate it has no price.commerce.products.get and commerce.products.find methods to read the listPrice field, note that it now also includes taxes if the related customer group includes taxes.commerce.products.get and commerce.products.find methods to read the sellingPrice field, note that this field is no longer present.commerce.products.get and commerce.products.find methods to read the price field, note that it has been renamed to salePrice and now includes taxes if the related customer group includes taxes.commerce.items.get and commerce.items.find methods to read the listPrice field, note that it now returns both prices for price lists and for customer groups, and prices for customer groups include taxes if the related customer group includes taxes.commerce.products.get and commerce.products.find methods to read the sellingPrice field, note that this field is no longer present.commerce.items.get and commerce.items.find methods to read the price field, note that it now returns both prices for price lists and for customer groups, and prices for customer groups include taxes if the related customer group includes taxes.commerce.items.get and commerce.items.find methods to read the costPrice field, note that this field is no longer present. At the time of upgrading to the new 2018 version, if at least one product had a cost price greater than zero, a new price list was created for the cost price. Therefore, to read the old cost price you must read the price field for the price list used for cost price. The cost price list is the one called "Costo" (unless it has been renamed or deleted after the upgrade).commerce.items.update-prices method to update item prices, with version 4 you must use instead the commerce.item-prices.update method with the necessary differences.commerce.tax-areas.get and commerce.tax-areas.find methods to read the isDefault field, note that this field is no longer present. The default tax area is now the tax area of the default customer group. Therefore you must call the commerce.customer-groups.find method with the isDefault condition set to true and indicate taxArea in the fields field.commerce.promotions.create or commerce.promotions.update methods, ensure that the coupon field does not contain leading or trailing spaces, that the elements field does not contain duplicate elements, and that the date in the startTime field is later than the date in the endTime field.commerce.categories methods, note that categories may have been converted into attribute values (this happens automatically on upgrade if no categories are present, or at a later time). If they have been converted, you must use the commerce.attribute-values methods instead, using as the value for the attribute field the identifier of the attribute used for categories (recognizable because the conversion assigns it the code "CATEGORY").commerce.departments.get and commerce.departments.find methods and read the parent field, note that where you expected 0 it now returns null.commerce.departments.get and commerce.departments.find methods and read the parents field, you must change your code because this field now contains only department identifiers. To also get names you must make a subsequent call to commerce.departments.find passing the identifiers in the ids field of conditions.id field because its type changed from bigint to int. If you have old identifiers to convert to new ones, perform a 32-bit right shift operation (id >> 32) on the old identifiers to obtain the new ones. The reverse is not possible. Note that the operation must be performed on a 64-bit integer and therefore, depending on the programming language used, it may be necessary to use a special library.find methods for documents with the address field in conditions, note that you will also get documents whose billing email address matches the one specified in address.find and get methods for documents, note that the taxClass field in items, shippingMethod and paymentMethod is no longer present; instead you can read the taxCode field and then determine the corresponding taxClass by calling the commerce.tax-classes.find method.commerce.discounts.find and commerce.discounts.get methods, note that the priority field has been added to discounts and that the priority of discounts previously did not exist. This field can have values between 0 and 100 and indicates the priority used to choose which discount to apply when multiple discounts can be applied; previously this choice was made at the system's discretion.commerce.discount-rules methods, note that they now return an error because discount rules are no longer supported.commerce.discount-rules.create method, note that it is no longer available. It has been replaced by commerce.promotions.create.commerce.discount-rules.find method, note that it is no longer available. It has been replaced by commerce.promotions.find.commerce.discount-rules.get method, note that it is no longer available. It has been replaced by commerce.promotions.get.commerce.discount-rules.update method, note that it is no longer available. It has been replaced by commerce.promotions.update.commerce.discount-rules.delete method, note that it is no longer available. It has been replaced by commerce.promotions.delete.commerce.discount-rules.create method, you no longer receive the notifications commerce.discount-rules.create and commerce.discount-rules.update and commerce.discount-rules.delete and commerce.discount-rules.get because these notifications have been removed.site.banners.create, site.banners.update or site.menus.update notifications, you will no longer receive them.Almost all find methods allow you to specify, with the limit parameter, the maximum number of results to return.
If limit is present and between 1 and 100, at most limit results are returned. If fewer than limit are returned, it means no others are present. This behavior is the same for all API versions.
If limit is not present or is null, then in previous versions 2 and 3 the find returns all or at most 100, while in version 4 it returns all or at most a multiple of 100.
With the new API version it is possible to assign labels, optionally visible in the back office, to products, customers and documents (orders, quotes, invoices, receipts and packing slips). The following methods have been added for this purpose:
If a label should be displayed in the back office, it is possible to call the Admin.Labels.set method via Admin SDK to set its name and color.
With the new version it is possible to manage site URLs via the following methods:
The canonicalURL field has been added to products, departments, producers, promotions, attribute values (ex options), pages and blog posts. The new field provides, for each site language, the canonical URL of the corresponding site page. The canonical URL is initially assigned by Open2b based on the name (of the product, department, etc.) and to change it you must either modify the name or create a rewrite using the site.url-rewrites.set method.
With the new 2018 version it is possible to add a product to multiple departments, up to five.
For this purpose the department field of products is now called departments and is the list of all product departments. The order of departments is preserved. In addition, the meaning of departments changed: whereas before it was the path from the top department to the final department where the product is located, in version 4 it is the list of all departments the product is in.
Customer groups replace old price lists with the difference that a customer group does not define any new prices for products and items. Prices are still managed via price lists while customer groups indicate which lists to use for customers in the group. Where you previously assigned a price list to a customer, you now assign a customer group. A customer therefore will have prices from the lists of the group they are assigned to.
For each customer group, via the taxArea field, you can specify the tax area to use for prices shown to customers.
The following methods have been added to manage customer groups:
commerce.customer-groups.findcommerce.customer-groups.getcommerce.customer-groups.countcommerce.customer-groups.createcommerce.customer-groups.updatecommerce.customer-groups.deleteThe sum of the number of price lists and the number of customer groups cannot exceed 255.
Some functions of price lists have now been transferred to the new customer groups. Adding a new price list now means having the ability to manage a new freely modifiable price with optional price tiers for each item. It is no longer possible to associate a price list to customers; this is now done with customer groups.
The price fields for products and items have changed. For items, the listPrice, sellingPrice and costPrice fields have been merged into a single price field.
The new price field for items reports prices for free lists, derived lists and for customer groups. Prices for free and derived lists are always tax excluded, while prices for customer groups are tax excluded or included based on the includeTaxes field of the customer group.
For products, the price field has been renamed to salePrice and the sellingPrice field has been removed. Therefore the product price fields are now listPrice and salePrice, which report list and sale prices for customer groups. Prices are tax excluded or included based on the includeTaxes field of the customer group.
The "position" value of the order field of the commerce.products.find method used to sort products by position and, for the same position, by product id. In version 4, "position" sorts products only by position.
The priceList field has been changed to group and now indicates the customer group instead of the price list.
For tax areas the isDefault field has been removed, because the default tax area for unregistered customers is now the one indicated in the default customer group.
In the previous version, an item price could be zero ("0.000") for a price list and in that case the item and its product were not visible to customers of that list. In the new version an item can have no price (null) for a list and in that case the item will not be visible to customers of that list. The product, unlike the previous version, will not be visible only if no items are visible.
The new version allows managing quantity discounts, i.e., defining multiple price tiers for each item and list based on the quantity ordered by the customer.
The following methods have been added to read item prices:
The find method returns only the prices of the first tier, i.e., the one with the lowest quantity, while the find-tiers method returns prices for all tiers including the minimum quantity of each tier.
The find method is more convenient when you do not manage quantity discounts or you need only the first tier price.
The following methods have been added to update item prices:
The update method updates only the price of the first tier, i.e., the one with the lowest quantity, while the update-tiers method updates the prices for all tiers including the minimum quantity of each tier.
Note that if a price is set to null, in order to remove an item from a list, then prices for all tiers will be removed. This happens whether you use the update method or the update-tiers method.
With the introduction of these new methods, the commerce.items.update-prices method has been removed. The commerce.item-prices.update method can be used instead, with the necessary differences.
Promotions can now be applied to all customers or only to customers in specific groups. As a result, a product can have multiple promotions applied, one for each customer group. The promotion field has been removed from the product and the promotions field has been added, which reports the promotion, or null if not present, for each customer group.
A new promotion type has been added: Shippings. Promotions of type Shippings are applied to shipments and can be a percentage discount, a fixed discount or a fixed price on the specified shipments.
The priority field has been added to promotions to indicate a priority that can range from 0 to 100. If multiple promotions are applicable, the choice is now based on which promotion has the highest priority, whereas in the previous version it was at the system's discretion.
For promotions on products, departments and producers it is now possible to specify, via the new discountList field, whether the fixed discount should be applied to the list price instead of the sale price. In previous Open2b versions it could only be applied to the list price.
In the new version, whether the customer group has a tax area or not determines some behaviors of promotions applied to it:
minSubtotal and maxSubtotal) for which a promotion is applied are to be considered tax included if the customer group has a tax area and tax excluded if it does not.discountAmount) is to be considered tax included if the customer group has a tax area and tax excluded if it does not. The same applies to shipping promotions.The commerce.promotions.find method now allows reading only promotions with the identifiers indicated in the ids field of conditions.
Version 4 of the commerce.promotions.create and commerce.promotions.update methods return an error if:
/\s+/), ifelements field contains duplicated elements and ifstartTime field is later than the date in the endTime field.Each product can now be associated with attributes, with their respective values, to be shown on the product detail page and used for filters.
What used to be variants are now attributes; the term variant now indicates an attribute used in a product as a variant. What used to be options are now attribute values and, as with variants, the term option is used for an attribute value when it is used as an option for an item.
The methods for variants and options have therefore been renamed to:
commerce.attributes.findcommerce.attributes.getcommerce.attributes.countcommerce.attributes.createcommerce.attributes.updatecommerce.attributes.deletecommerce.attribute-values.findcommerce.attribute-values.getcommerce.attribute-values.countcommerce.attribute-values.createcommerce.attribute-values.updatecommerce.attribute-values.deleteCompared to variants, attributes have the new position field to indicate the attribute's position in URLs.
If the keywords field of conditions in the commerce.products.find method contains one or more barcodes, products that have at least one item with one of the indicated barcodes will also be returned. If the search is by relevance, these products will be first in the search results.
The parent and parents fields returned by the commerce.departments.get and commerce.departments.find methods have changed. For top-level departments, i.e. those without a parent, parent is null instead of 0. parents no longer includes the names of parent departments but only their identifiers.
The commerce.departments.find method now allows reading only departments with the identifiers indicated in the ids field of the new conditions parameter. The parent parameter is now a field of conditions.
The commerce.producers.find method now allows reading only producers with the identifiers indicated in the ids field of the new conditions parameter.
The identifier for documents (orders, quotes, invoices, receipts and packing slips) changed type from bigint to int and document identifiers changed accordingly. API v2 and v3 accept and return the old identifiers while API v4 accepts and returns the new identifiers.
The old identifiers can be converted to new identifiers by a 32-bit right shift operation: id >> 32. The reverse is not possible. Note that the operation must be performed on a 64-bit integer and therefore, depending on the programming language used, a special library may be required.
Documents can now be searched by billing email address via the address field of the conditions parameter.
The ip field has been added to orders to indicate the IP address of the device from which the order was completed.
The goods transport documents (packing slips) now include the fields goodsAppearance, trackingNumber and transportReason.
When deleting a language via the site.languages.delete method, all texts that were previously entered for the deleted language are now removed.
The site.pages.find method now allows reading only pages with the identifiers indicated in the ids field of the new conditions parameter.
The ids field has been added to the conditions parameter of the site.blog-posts.find method to read posts with the indicated identifiers.
Banners and menus were removed in version 4. All related methods are no longer available.
A path can now contain more dot "." characters but never consecutively.
The following notifications have been added:
commerce.customer-groups.createcommerce.customer-groups.deletecommerce.customer-groups.updatesite.url-redirects.deletesite.url-redirects.setsite.url-rewrites.deletesite.url-rewrites.setThe following notifications have been removed:
site.banners.createsite.banners.deletesite.banners.updatesite.menus.updateVersion 3 was introduced with Open2b in February 2016. If you have built applications that use API version 1 you must update your applications to use API version 2 or 3 because version 1 is no longer supported. If instead you built applications that use version 2, you can:
stock field for items, note that internally it has changed type from int to decimal with 2 decimal digits. API version 2 methods, for compatibility, do not return decimal digits; for example instead of 23.67 they return 23. Also, if you assign to stock a value greater than 999999999, it will still be set to 999999999.commerce.movements.create method may return an InvalidValue error if adjustment is less than -999999999 or greater than 999999999.commerce.movements.get and commerce.movements.find methods return adjustment without decimal digits.minOrder, maxOrder and minQuote fields for products, note that internally they have changed type from int to decimal with 2 decimal digits. API version 2 methods, for compatibility, do not return decimal digits; for example instead of 23.67 they return 23.commerce.promotions.create and commerce.promotions.update methods with the discountAmount and discountPercent fields, verify that they are respectively of type decimal[8,2](0..) and int(0..99).v2 with v3 in the call URL.commerce.products.find and commerce.products.count methods and in these you use the conditions.keywords field, then put its value inside an array: [ "shirt" ] instead of "shirt" as also indicated later.code field or the sku and supplierSKU fields of items or the sku field of documents, note that in one of the next versions of Open2b the length will increase from 32 to 40 characters. For your application to be compatible with this change when introduced, it must already handle a maximum length of 40 characters for these fields even though at the moment it is effectively 32.stock field for items, note that it has changed type from int to decimal with 2 decimal digits and the range of possible values has changed from the previous 0 → 2147483647 to the new 0.00 → 999999999.99.minOrder, maxOrder and minQuote fields for products, note that they have changed type from int to decimal with 2 decimal digits and the range of possible values has changed from the previous 1 → 2147483647 to the new 0.01 → 999999.99.commerce.items.update-stock method, note that the itemsStock parameter is now called stock and the quantity has changed type from int to decimal with 2 decimal digits and the range of possible values has changed from the previous 0 → 2147483647 to the new 0.00 → 999999999.99.productsLayout field, note that it no longer has columnsOnFirstRow, rows, imageSizeOnFirstRow and showDescriptionOnFirstRow while products has been added. Allowed values for imageSize now include Optimal and Large. columns can no longer take the value 5 but only 1, 2, 3, 4 and 6.adjustment field has changed type from integer to decimal and the range of possible values has changed from the previous -2147483648 → 2147483647 to the new -999999999.99 → 999999999.99.commerce.product-images.find method then:
resized field instead of sizes.commerce.product-images.get method to read the original image of a product, you must now use the commerce.product-images.find method instead, identify the image among those returned, and then retrieve the original image by performing an HTTP GET directly to its URL in the original field.commerce.product-files.find or commerce.product-files.get methods to read the content of a product file, you must now retrieve the file by performing an HTTP GET directly to its URL in the address field.commerce.product-files.count method to read the number of files for a product, you must change the request from {"product":281} to {"conditions":{"product":281}}.commerce.departments.update method, note that the largeImage field now accepts images only up to 2500 pixels instead of 32767 pixels. In addition, GIF format is no longer supported.commerce.promotions.get and commerce.promotions.find methods, the discountAmount field now has 3 decimal digits instead of 2 and the discountPercent field changed type from int to decimal with 3 decimal digits.commerce.promotions.get and commerce.promotions.find methods, the smallImage field can return an image with width and height up to 255 pixels instead of the previous 200 pixels, and the largeImage field can return an image with width and height up to 2500 pixels instead of the previous 500 pixels.commerce.tax-areas.create and commerce.tax-areas.update methods, make sure you do not set the isActive field to false for the default tax area or they will return an error.commerce.shipping-methods methods, rename the percentCost field of shippingRates to unitCost.site.menus.get [ Removed in version 4 ] and site.menus.find [ Removed in version 4 ] methods, rename the openAsPopup field to openAsModal.create or update methods of documents (orders, quotes, invoices, receipts and packing slips), you must remove the taxArea field because it has been removed. In previous versions even if the field was present it was not used.Methods for template management have been added. In particular, the following methods were added:
site.templates.findsite.templates.find-filessite.templates.read-text-filesite.templates.write-text-filesite.templates.delete-filesTo enable keyword search on products with results ordered by relevance, in the commerce.products.find and commerce.products.count methods the type of the conditions.keywords field has changed from string to an array of string and relevance has been added as a possible value for order.
The fields promotion (to return only products with a specific promotion applied), codes (to return only those with specified product codes) and hasZeroPrice (to return products that have or do not have a zero price for the specified price list) have been added to the conditions field of the commerce.products.find and commerce.products.count methods.
The commerce.products.count method has added the priceList field to be used in combination with the hasZeroPrice field of conditions to indicate the price list.
To better support responsive templates, the productsLayout field used by various methods has been updated: products has been added and the fields columnsOnFirstRow, rows, imageSizeOnFirstRow and showDescriptionOnFirstRow were removed.
The allowed values for the imageSize field of productsLayout now include Optimal and Large.
The allowed values for the columns field of productsLayout no longer include 5; therefore the allowed values are now 1, 2, 3, 4 and 6.
If you need to read or update the old productsLayout fields that are no longer present in version 3, you can call the same methods but with API version 2.
The commerce.items.update-prices method [ Removed in version 4 ] has been added to update list and sale prices for multiple items at once. You can update prices, for a single price list, for 100 items with a single call.
For the product code field, the sku and supplierSKU fields of items, and the sku field of documents, the maximum length that methods can return for these fields changes from 32 to 40 characters. The maximum length that methods accept in requests remains 32.
For example, as a consequence, your application must expect a method to return an item with a 40-character sku and must handle the fact that it cannot modify it because currently request methods only allow sku up to 32 characters.
This particular API behavior is required for compatibility with version 2. When version 2 is no longer supported, a new API version will be introduced that removes these limitations.
For the commerce.products.find, commerce.products.get, commerce.items.find and commerce.items.get methods, the fields thumbnailImage, smallImage, mediumImage and largeImage now include the url2x field with the URL of the image for high-resolution displays.
The commerce.product-images.find method has been modified accordingly. It now returns the new fields original and resized. The fields baseURL and sizes have been removed. The new method version also adds the limit and first fields that limit the number of images returned to 1000. Previous versions returned all images that matched the conditions.
Product images can now have a maximum size of 2 MB. In previous versions the limit was 1 MB.
The commerce.product-images.resize method has been added to resize product images to the default dimensions set in the back office.
The commerce.product-images.get method is no longer present.
The stock field of items has changed type from int to decimal, enabling stock management with two decimal places. The range of possible values has changed from the previous 0 → 2147483647 to the new 0.00 → 999999999.99. In addition to the commerce.items methods, the commerce.products.create method is also affected by this change.
As a consequence, the types of the product fields minOrder, maxOrder and minQuote have changed from int to decimal with 2 decimal digits. The range of possible values changed from the previous 1 → 2147483647 to the new 0.01 → 999999.99.
The commerce.movements.get and commerce.movements.find methods return adjustment with two decimal digits and the commerce.movements.create method also accepts adjustment with two decimal digits.
Also for the commerce.items.update-stock method the itemsStock parameter is now called stock and the quantity has changed type from int to decimal with 2 decimal digits and the range of possible values has changed from the previous 0 → 2147483647 to the new 0.00 → 999999999.99.
For products the new unitOfMeasure field is available to indicate the unit of measure. The unit of measure allows both showing the unit on which a price is based (e.g., "23.99/kg", "12.15 per pack") and ordering quantities with one or more decimals (e.g., "3.19 kg", "55.9 m²"). To manage units of measure, the following methods were added:
commerce.units-of-measure.findcommerce.units-of-measure.getcommerce.units-of-measure.countcommerce.units-of-measure.createcommerce.units-of-measure.updatecommerce.units-of-measure.deleteThe commerce.items.find method now accepts barcode and -barcode in order to sort items by barcode.
The description parameter of the commerce.product-files.update method is no longer required.
The file field of the commerce.product-files.find and commerce.product-files.get methods has been removed and you must now retrieve the file by performing an HTTP GET directly to its URL in the address field.
The conditions parameter of the commerce.product-files.find method is no longer required and it is now possible to use the commerce.product-files.count method to get the total number of files and not just those for a specific product.
For the commerce.departments.update method, the smallImage field can now accept an image up to 2500 pixels instead of the previous 255 pixels. If the image is larger than 255 pixels it will be scaled while preserving proportions. The largeImage field can now accept an image only up to 2500 pixels instead of the previous 32767 pixels.
GIF images are no longer supported; JPEG and PNG images are supported.
For cart promotions you can ensure they are applied only if the total cart cost is greater than or equal to a minimum amount or less than or equal to a maximum amount. For this purpose the minSubtotal and maxSubtotal fields have been added to promotions.
In promotions the discountAmount field now has 3 decimal digits instead of 2 and the discountPercent field changed type from int to decimal with 3 decimal digits.
It is now possible to modify the small and large images of promotions. The new fields smallImage and largeImage were added to the commerce.promotions.update method. The maximum size of the uploaded image is 2500 pixels. For the small image, if the uploaded image size exceeds 255 pixels, the image is scaled preserving its proportions.
For the commerce.promotions.get and commerce.promotions.find methods, the smallImage field can return an image with width and height up to 255 pixels instead of the previous 200 pixels, and the largeImage field can return an image with width and height up to 2500 pixels instead of the previous 500 pixels.
The name parameter of the commerce.promotions.create method is no longer required.
The language parameter was added to the commerce.producers.get and commerce.producers.find methods to return SEO fields for a single language.
Also, the producer name field can now have zero length.
The showName field was added to variants to indicate whether the variant name should be displayed together with option names.
The canLogin field was added to the conditions of the commerce.customers.find method to return only customers who can log in to the site.
An error is now returned if you try to set the default tax area to inactive.
The taxArea field passed as a parameter to the create and update methods of documents (orders, quotes, invoices, receipts and packing slips) has been removed. In previous versions even if the field was present it was not used.
In the commerce.shipping-methods methods the percentCost field of shippingRates was renamed to unitCost and the value range was extended from the previous 0.00 → 99.99 to the new 0.000 → 9999999.999.
Two new fields were added to site.pages methods: image and isAlwaysVisible.
The site.pages.find and site.pages.get methods now return ProductLayout also for the wish-list.html template page. In previous versions they returned null.
The new isDefault field was added to the site.languages.find method to indicate whether the language is the site's default.
For each store manager it is now possible to indicate the back office language. For this purpose the locale field was added to site.accounts.
The site.menus.update method [ Removed in version 4 ] was added to update a menu. The fields description and showTo were added to menu items and the openAsPopup field was renamed to openAsModal.
Banners can now have a maximum size of 500 KB instead of 200 KB. Also the link field, in addition to URLs starting with http:// and https://, now also allows URLs starting with /.
The following notifications have been added:
commerce.contacts.deletecommerce.currencies.deletecommerce.customers.deletecommerce.departments.deletecommerce.invoices.deletecommerce.items.deletecommerce.movements.deletecommerce.notes.deletecommerce.options.deletecommerce.orders.deletecommerce.packing-slips.deletecommerce.payment-methods.deletecommerce.price-lists.deletecommerce.producers.deletecommerce.products.deletecommerce.product-files.deletecommerce.product-images.deletecommerce.product-reviews.deletecommerce.promotions.deletecommerce.quotes.deletecommerce.receipts.deletecommerce.shipping-methods.deletecommerce.suppliers.deletecommerce.tax-areas.deletecommerce.tax-classes.deletecommerce.units-of-measure.createcommerce.units-of-measure.deletecommerce.units-of-measure.updatecommerce.variants.deletesite.accounts.deletesite.banners.deletesite.languages.deletesite.menus.updatesite.newsletter-lists.deletesite.newsletter-members.deletesite.pages.deleteUnlike versions 1 and 2, an UnknownField error is returned if the object passed in the request includes a field that is not present in the method documentation.
API version 2 introduces new methods and some minor changes. If you built applications that use API version 1, you can:
v1 with v2 in the call URL.commerce.items.count and commerce.items.find methods and in these you use the conditions.product field, replace it with the conditions.products field as indicated below.Version 2 was introduced with Open2b in September 2013. The following are the differences compared to the first version.
In the commerce.items.count and commerce.items.find methods, the conditions.product field became conditions.products and now accepts multiple product identifiers instead of only one.
The new sortOrder field has been added to manage product ordering on department, producer, promotion, home and new arrivals pages.
The new position field has been added to manage department ordering.
Methods for contact management were added. In particular the following methods were added:
commerce.contacts.findcommerce.contacts.getcommerce.contacts.countcommerce.contacts.createcommerce.contacts.updatecommerce.contacts.deleteFields for SEO management were added to promotions:
seoTitleseoKeywordsseoDescriptionThe new isDefault field was added to payment methods and shipping methods to indicate the default method selected in the cart.
Product reviews have been added. In particular the following methods were added:
commerce.product-reviews.findcommerce.product-reviews.countcommerce.product-reviews.createcommerce.product-reviews.deleteIn addition, the rating field was added for products and the related method to update the rating of multiple products with a single call:
Unlike version 1, an error (HTTP 400) is returned if non-UTF-8 characters are present in the call body.