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:

API-GetShopsData

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

API-CheckServerLoad

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).

API-DiscountGroups

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.

API-GiftCards

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.

API-Vouchers

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.

API-Products

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

API-GetProducts

Added the ability to retrieve product strikethrough price information

The API-GetProducts method received two new parameters:

  • strikethrough_retail_price
  • strikethrough_wholesale_price

API-SetProducts

Added the ability to set product strikethrough prices

The API-SetProducts method received four new parameters:

  • strikethrough_retail_price
  • strikethrough_retail_price_net
  • strikethrough_wholesale_price
  • strikethrough_wholesale_price_net

API-ProductsMarketing

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.

API-Bundles

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.

API-Collections

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.

API-RMA

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.

API-Orders

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)

API-GetOrders

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.

API-AddOrders

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.

API-Payments

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:

  • set
  • get
  • confirm
  • cancel

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.

API-EppDocuments

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.

API-OrdersDocuments

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.