18 July 2017
We are unveiling a new version of the Administration Panel API documentation. Have a look at what has changed recently.
The Administration Panel API documentation has undergone extensive visual changes, and now enables switching between API versions and comparing changes between versions globally, for the entire API, and granularly for each endpoint / method. New endpoints were introduced - DiscountGroups, which allows for discount group management, GiftCards and Vouchers, for managing gift cards and vouchers. Existing endpoints received new methods, as well as functionality updates to existing ones - Products, GetProducts, SetProducts, RMA, Orders, GetOrders and Payments. Some of the new functionality includes the ability to process cash back refunds to customers with external payment systems that support cash backs.
Updated look & feel and the ability to switch between API versions
The Administration Panel API documentation has undergone extensive visual changes, and now enables switching between API versions and comparing changes between versions globally, for the entire API, and granularly for each endpoint / method. The new documentation displays the latest version by default. This is a great utility for developers who want to stay up to date with all changes we regularly introduce to the Administration Panel API
Below you can find the list of API changes introduced within the last few months:
You can now retrieve the configuration of the Include free products on VAT invoices and receipts option available in the administration panel, as well as the list of available printers.
The API-GetShopsData method received a few new parameters:
- product_free_invoices - returns the value of the Include free products on VAT invoices and receipts configuration option, which is available in the administration panel under ADMINISTRATION / Print configuration / Sales documents print settings.
- fiscal_printers - returns the list of fiscal receipt printers configured in the administration panel under ADMINISTRATION / Print configuration / Fiscal printer settings
- printers - returns a list of document printers configured in the administration panel under ADMINISTRATION / Print configuration / Document printer settings (IAI Printer)
- vouchers - returns information whether the shop has active gift vouchers configured
- giftCards - returns information whether the shop has active gift cards configured
All previously optional request parameters are now required
All request parameters in the API-CheckServerLoad endpoint are now required
The API customer search logic changed from OR to AND
Before, when searching for a customer, e.g. John Smith, the results would include all customer whose names and surnames match John and Smith. After the change, when the search phrase contains two or more words, the results will contain only those customers, whose both names and surnames match the phrase (i.e. John AND Smith).
New endpoint which enables discount group management
Discount groups can be seen as a kind of a price template which can be used to efficiently manage prices for specific products. A discount group can be assigned to a customer, which means you do not have to set individual promotional product prices for each customer separately and, in turn, reduce the number of required API calls. Discount groups are especially useful for online B2B stores, as they allow you to set price thresholds. This lets you segment your client base in such a way that each segment sees only the product prices from a preconfigured threshold. Methods available in the new API-DiscountGroups endpoint:
- getDiscountGroups - retrieving information about discount groups configured in the administration panel
- addDiscountGroup - adding new discount groups. New discount groups are added with the Discount for products option set to yes, but different for indicated groups by default.
- setProductsToDiscountGroup - adding products to discount groups and setting their prices. This method overwrites the currently configured products.
- editDiscountGroups - changing the discount group name.
- deleteDiscountGroups - deleting discount groups. In order to delete an existing discount group, it must not be currently assigned to any existing customer.
- getClientsAssignedToDiscountGroup - retrieving the list of customers currently assigned to a discount group. In order to assign a customer to a discount group use the setClients method available in the API-Clients endpoint.
New endpoint which enables gift card management
API-GiftCards is a new endpoint that lets you create, edit and manage gift cards in your administration panel. More information about the IdoSell Shop gift card functionality can be found here.
New endpoint which enables gift voucher management
API-Vouchers is a new endpoint that lets you create, edit and manage gift vouchers in your administration panel. More information about the IdoSell Shop gift card functionality can be found on here.
New methods and parameter names were introduced
The API-Products endpoint received the following new methods:
- checkDeliveryTime - retrieving the time required for preparing a product for shipment
- delete - deleting a product from the administration panel
- get - getting information about products available in the administration panel
- getDescriptions - getting textual information about products, e.g. name, long and short descriptions, metadata
- getIds - getting product ids and related size ids, based on provided external system codes
- insert - adding new products to the administration panel
- insertAttachments - adding and editing products attachments
- insertImages - adding and editing pictures for existing products
- update - editing existing products
- updateDescriptions - updating textual data in an existing product, e.g. name, long and short descriptions, metadata
Added the ability to retrieve product strikethrough price information
The API-GetProducts method received two new parameters:
Added the ability to set product strikethrough prices
The API-SetProducts method received four new parameters:
New endpoint which enables strikethrough price and marketing section management for products
API-ProductsMarketing is a new endpoint which lets you freely manage product strikethrough prices as well as marketing sections products will be displayed in.
New endpoint which allows creating products bundles and managing their contents
API-Bundles is a new endpoint that lets you create and manage (add / remove products) product bundles in the administration panel.
More information about product bundles / sets can be found on the Product sets (configurators) page.
New endpoint which allows creating products collections and managing their contents
API-Collections is a new endpoint that lets you create and manage (add / remove products) product collections in the administration panel.
More information about product collections can be found on the Product collections (inspirations, stylebooks) page.
New parameters were added that allow getting information about the customer placing a complaint
The API-Rma endpoint's get method received two new parameters - client_login and product_name, which return the login and name of the customer who placed the complaint. The client_id parameter was removed.
New methods and parameter names were introduced
The API-Order endpoint received the following new methods:
- changeCourier - changing the delivery method for an existing order
- changeDeliveryAddress - changing the delivery address for an existing order
- changeShippingCosts - changing the shipping cost information for an existing order
- get - retrieving information about orders present in the administration panel
- insert - adding new retail or wholesale orders to the administration panel
- setSerialNumbers - configuring serial numbers for products included in an order
- update - editing orders available in the administration panel (e.g. changing the included products, changing the order status)
Added the ability to retrieve information about gift vouchers and gift cards used in an order
The method received two new parameters, voucherNumber and giftCardNumber, which return information about any gift cards and vouchers used in an order.
Added the ability to mark products as free when adding an order
The API-AddOrders method received a new parameter under the products node - product_fee, which lets you indicate whether the product being added to the order should be marked as free of charge.
Added a new method for processing cash back refunds - doCashBack
The API-Payments endpoint received a new method, doCashBack, which lets you process a cash back refund to a customer via the external payment system they used to initially pay for an order (as long as it supports the cash back functionality).
Records for payments and refunds for orders can be managed using the same methods
Methods for managing payment and refund records in the API-Payments endpoint:
In order for this to be possible, you must include the payment source, e.g. order or return, in the source_type parameter and provide the payment number which the request relates to. The payment number consists of the order / return ID and the payment's ordinal number, e.g. 1234-1.
The get method was extended to allow retrieving information about payments and refunds
The get method in the existing API-EppDocuments endpoint, which can be used to download sales documents in the universal EDI++ format, was extended allow retrieving information about payments and refunds.
Removed all deprecated parameters
Removed the type and doc_copy_type parameters from all available methods in the API-OrdersDocuments endpoint, which were previously marked as DEPRECATED.