Merchant API

Merchant API Description

GENERAL INFORMATION

1. Merchant API is situated on the following address:
http://shopxml.com/API/script_name.php
where script_name.php is the name of the interface file. For example:
http://shopxml.com/API/orders.php
http://shopxml.com/API/orders_process.php

2. While using any interface there is no difference by which way you transmit data either GET or POST, if there are no additional notes. However remember about in any case it's better not to transmit very long data by GET method. That's the point where using POST method is more effective.

3. While using any interface there are two obligatory variables, which ALWAYS must be transmitted. Remember about is, because these variables will not be mentioned in description repeatedly in each concrete interface, but just specific ones for this interface. Here are these two variables:
api_id - products base ID
api_key - special key (password) for this base, installed by our administrators
Example: http://shopxml.com/API/orders.php?api_id=56&api_key=354dsg43652

4. While transmitting variables don't forget to url-code them. Of course you should copy the name of parameter as well as its value. Parameters can be arrays. In this case parameter's name includes brackets []. For example, like this: status[43]=3, or this: order[]=214. After being url-coded it will look like this status%5B43%5D=3, order%5B%5D=214.

6. Some interfaces are defined for orders handling. Orders have very important status attribute, coded with integer number. If needed you should indicate this number, so make acquaintance with table of statuses below this page.

7. While XML description following definitions are used:
- if the field name is set in brackets <field_name>, then this field in XML is presented as a nested tag.
- If the field name is set simply and without brockets, like field_name, then this field in the xml is presented as main tag's attribute.
- if the field is marked with star * so it's optional and can be absent.
There are always fields not marked with star, but some of them can be empty.

8. While parameters transmitting squares brackets after parameter's name (status[]) indicate that this parameter is array. So many of such variables can be transmitted. For example:
status[25]=3&status[35]=5&status[37]=3
Array index (in brackets) is not always necessary, so it can be transmitted like this:
order[]=21&order[]=33&order[]=34
Don't forget to url-code brackets while transmitting.

API specification

1. Orders base export (orders.php). To get orders sample you should open file:
orders.php
Request parameters (not all are necessary):
start - integer number, position, starting point of result returning (numeration starts from zero). So if 20 orders correspond to your query, and you transmitted start=10, so you will get 10 last orders.
portion - integer number, number of orders to be returned. If 20 orders correspond to your query and you transmitted portion = 10, so you will get 10 first results. And if you transmitted start = 10 and portion = 10, then 10 last.
But still when you use these parameters remember the system is live, and while you are getting information about some portion, new orders can come. So don't make logic mistakes.
Better use parameters' pair of portion and min_id (see description below). It's very easy because then results are sorted according to increasing order's ID, and in this case min_id very comfortably replaces start.
end_time - integer number. unix timestamp. End time limit of orders sampling (inclusive). If it's not indicated, then all of them are to be sampled.
start_time - integer number. unix timestamp. Start time limit of orders sampling (inclusive). If it's not indicated, then all of them are to be sampled. This value can be NEGATIVE. Then orders are sampled down from the end_time. For example if you did not indicated end_time and indicated start_time=-86400, then you'll get orders of the last 86400 seconds, that means 24 hours.
id - concrete order ID
min_id - minimal order's ID (inclusive), which can be sampled
max_id - maximum order ID (inclusive), which can be sampled
email - customer's e-mail - closest fit
name - customer's name. search by start points of shipping and billing first_name ¨ last_name (4 field in total)
zip - zip-code. Search by start points zip-codes shipping and billing (2 fields in total)
status - order status ID (any one if not indicated)
cc4 - last 4 numbers of the credit card - closest fit
testmode - 0-real orders (default), 1 - test orders, 2 - any orders
shipping_details - search by shipping mode (closest fit)

Return:
As the answer you'll get full information in XML about orders, fitting your query:
<orders> - external container
count - orders quantity in the answer
<order> - order (repeating for each order)
ID - order ID
time - time of order in UNIX_TIMESTAMP
time_str - order time in clear line
price - total order price (includes products, taxes, shipping), paid by the customer (that is taking into account the discounts)
price_prd - price only for the products in the order
price_tax - taxes
price_ship - order shipping price
discount - total discount received by the customer
discount_prd - product discount part
discount_tax - taxes discount part
discount_ship - order shipping price discount part
status - order status - number
status_str - order status - clear definition
boxes - number of boxes the order was sent in (should be a very large order that the number of boxes exceeded 1)
testmode - 1, if the order is for test
num_comments - number of admin's comments to this order

<products> - products list
quantity - quantity of products in the order
weight - total products' weight in the shopping cart
<product>* - product (for any position in the order)
ID - product ID (products with attributes if they were put several times then they will be repeated)
<name> - name
quantity - quantity for the given position in the order
weight - total weight of this position in the order (that is taking into account the quantity)
price_one_wo_attr* - price of one product in this position without taking into account the attributes (if the product has some)
price_one - price of one product in this position
price - position price (that is taking into account the quantity)
tax* - tax sum for this position (if not 0)
price_full - total position price (taking into account the taxes)
<attributes> - string with enumeration of the selected options for attributes
<model> - product's model

<email> - customer email
<comment> - user order comment
<shipping_details> - selected shipping method (clearly written string)
<payment_details> - payment details (clearly written string)
<shipping_info> - shipping information for the order (written by admins)
<site_url> - partner's site url, which the order was made from.
<site_name> - partner's site name, which the order was made from

<shipping_address> - shipping address
<first_name> - first name
<last_name> - last name
<company> - company name
<address1> - address string 1
<address2> - address string 2
<city> - city
<state> - state/province (full name)
<zip> - zip/postal code
<country> - country (full name)
<tel> - telephone
<fax> - fax

<billing_address> - customer billing address (payer))
<first_name> - first name
<last_name> - last name
<company> - company name
<address1> - address string 1
<address2> - address string 2
<city> - city
<state> - state/province (full name)
<zip> - zip/postal code
<country> - country (full name)
<tel> - telephone
<fax> - fax

2. Changing orders' status and information about shipping (orders_process.php).
To change orders status and their shipping information you need to open file:
orders_process.php
Request Parameters:
status[] - array of statuses, which are to be set for orders. Index in the array is order ID, value is the status, which are to be assigned to the order. For example: status[44]=2&status[45]=3
shipping_info[] - array of information about shipping, which is to be set for orders. Index in the array is order ID, value is the information (the string can be empty), which is to be assigned to the order
shipping_info_mail - set as 1, if shipping information (not empty) is to be sent for customers
At least one parameter either status or shipping_info must be present!

Return
As an answer, if there is no error occurred (specific errors are possible to this interface), you will get XML information about the operation:
<orders> - external container
<orders_wrong> - wrong orders ID from your query, listed through comma - from status and shipping_info array's keys (for example if there is no orders in the base)
<statuses_wrong> - wrong orders ID from your query, listed through comma for which you've indicated incorrect status
<statuses_not_changed> - wrong orders ID from your query, listed through comma for which you've indicated status identical to already existing one.
Operations with orders without errors found are successfully processed.

4. Products categories list (categories.php). To get the list of categories you need to open the file: categories.php

Request Parameters (all of them are not necessary):
id - category id. To select several of them, you can indicate several ids through comma or transmit this parameter as a array (id[])
parID - parent category id. You cannot indicate several of them.
active - 0(only inactive) or 1(active only). It is to be transmitted only if you want to filter by this parameter.
name - name. All of them will be selected, where the name includes the string transmitted in the given parameter.
exc_field[] - fields that should be excluded from the extract. The following fields could be possibly excluded:
name
title
comment
description
meta_title
meta_keywords
meta_description
image


Return
As an answer, you will get XML information about objects found (categories):
<objects> - external container
<category> - Category (repeated for the each one)
id - unique identifier. Integer.
parID - parent category identifier. Integer number. If zero then highest level category
active - activity flag. 0 or 1.
priority - priority. Integer (0-255). The smaller the number is - the higher is the priority
<name> - name
<title>* - full name (title).
<comment>* - brief category description
<description>* - full category description
<meta_title>* - text for the TITLE tag in HTML
<meta_keywords>* - keywords to be inserted into the meta-tags
<meta_description>* - description to be inserted into the meta-tags

<image>* - image
src - image url
width - image width in pixels
height - image height in pixels
size - image file size (in bytes))

5. Products list (products.php).
To get the Products list, you need to open the file:
products.php

name - name. All of them will be selected, where the name includes the string transmitted in the given parameter.

Request Parameters (all of them are not necessary):
id - product id. To select several of them, you can indicate several ids through comma or transmit this parameter as an array (id[])
catID - product category ID. To select several of them, you can indicate several ids through comma or transmit this parameter as a array (catID[])
code - product code. It returns all the products with mentioned code.
model - product model. It selects all the products with mentioned model. In the case of non-strict search you can use '%' symbol (for example 'aa%').
active - 0(only inactive) or 1(active only). It is to be transmitted only if you want to filter by this parameter.
in_stock - 0(absent only) or 1(present only). It is to be transmitted only if you want to filter by this parameter.
in_new - 0(not new only) or 1(new only). It is to be transmitted only if you want to filter by this parameter.
price_type - 0(Simple only), or 1(Special only), or 2(Featured only). It is to be transmitted only if you want to filter by this parameter.
min_price - minimal price
max_price - maximal price.
have_image - 0(only without image), or 1(only with image). It is to be transmitted only if you want to filter by this parameter. It's checking only by the first image!
have_attributes - 0(only without attributes), or 1(only with attributes). It is to be transmitted only if you want to filter by this parameter.
name - name. All of them will be selected, where the name includes the string transmitted in the given parameter.
keyword - keyword. All of them will be selected, where the name or description includes the string transmitted in the given parameter.
exc_field[] - fields that should be excluded from the extract. The following fields could be possibly excluded: name
comment
description
model
measure
dimensions
image1 - image6
document1 - document3
meta_title
meta_keywords
meta_description
attributes
add_fields - all additional fields at once

Return
As an answer, you will get XML information about objects found (products):
<objects> - external container
<product> - Product (repeated for the each one)
id - unique identifier. Integer.
active - activity flag. 0 or 1.
priority - priority. Integer (0-255). The smaller the number is - the higher is the priority
categories - categories list through comma, where the product given is placed.
<name> - name
<comment>* - brief category description
<description>* - full category description
time_available - time in unix-timestamp (that is in seconds from the beginning of 1970) when the product will be available
date_available - the date in the YYYY-MM-DD format, when the product will be available (time_available in the other format)
in_stock - availability. 0 or 1.
is_new - indicates that the product is new. 0 or 1.
price - product price (primary).

opt1 - minimal quantity for small wholesales (if it equals 0 then there are no wholesales provided).
price1 - product price for small wholesales.
opt2 - minimal quantity for large wholesales (if it equals 0 then there are no wholesales provided).
price2 - product price for large wholesales.

price_type* - special product type. 0 or absent - general product, 1 - Special (discounts), 2 - Featured (seasonal products and so on).
spec_time1* - low time bound in unix-timestamp when this product has the specified special type.
If it equals 0 - then there are no limitations from this side
spec_date1* - low time bound in the YYYY-MM-DD format, when this product has the specified special type. Analog of spec_time1.
spec_time2* - high time bound in unix-timestamp when this product has the specified special type.
If it equals 0 - then there are no limitations from this side
spec_date2* - high time bound in the YYYY-MM-DD format, when this product has the specified special type. Analog of spec_time2.
spec_price* - main price for this period. If it equals zero then it is equal to the main price.
spec_price1* - small wholesale price for this period. If it equals zero then there are no wholesales.
spec_price2* - large wholesale price for this period. If it equals zero then there are no wholesales.

quantity - quantity in stock. The number 1000000 means no limit.
num_choosed - number such of purchased products. To be used in top.
mnfID - manufacturer's ID. If it equals zero, then manufacturer is not defined.
<code>* - internal product's code
<model>* - product model
url - product official page webaddress
weight - product weight
<measure>* - units (e. g. sacks, kilogramms, ...)
<dimensions>* - sizes
<meta_title>* - text for the TITLE tag in HTML
<meta_keywords>* - keywords to be inserted into the meta-tags
<meta_description>* - description to be inserted into the meta-tags

<image>* - image
Attention: There can only be up to 6 images. Instead of number 1 there will be numbers from 1 to 6 (image1, image2,..., image6). At that they can not necessarily go succesively (that is there can be only numbers 1 and 6 present and the others may not exist at all).
1 - small image, 2 - middle, 3 - large, 4-6 - additional
src - image url
width - image width in pixels
height - image height in pixels
size - image file size (in bytes))

<document1>* - additional documents to the product (for example, instructions, schemes...).
Attention: There can be up to 3 documents. Instead of number 1 there will be numbers from 1 to 3 (document1, document2, document3). At that they can not necessarily go successively (that is there can be only number 3 present and numbers 1 and 2 may not exist at all).
name - document name
src - document url
size - document file size (in bytes)

<attributes>* - product attributes available to be chosen by the customer
<attribute> - attribute (can be a lot of them)
<code> - attribute's code, unique string
type - attribute type - integer value from 0 to 2
There are 3 attribute types:
0 - attribute obligatory selected by the customer, 1 - optional attribute - that is the one that is not obligatory, 2 - multiple choice attribute.
<name> - attribute name
<description>* - attribute description

<options>* - the present attribute options
<option> - option (there can be a lot of them)
<code> - option's unique code - unique string for this option
<name> - option name
price* - option price (can be absent then it equals 0).
Can be both positive and negative - is added to the product price
weight* - option weight (can be absent then equals 0).
Can be both positive and negative - is added to the product weight
<question>* - additional question.
Should be asked when the customer selects this option

<additional_fields>* - additional fields
<additional_field> - additional field (repeated for the each one)
id - field identifier (code) - string
type - field type. Possible values: text (text up to 65Š), checkbox (yes/no), select - one value among many, multiple - any number of values among many others
name - field name
<value>; - field value (can repeat in case of multiple)
id - value identifier - integer number. Exists only if type= select or multiple
value - value

6. Deleting manufacturer (manufacturer_delete.php).
to delete manufacturer, you need to open the file:
manufacturer_delete.php
Request Parameters:
id - manufacturer's id

Return
As an answer, if there is no error occurred, you will get operation status in XML:
<status> - 1 if operation is successful

7. Deleting category (category_delete.php).
To delete category, you need to open the file:
category_delete.php

Request Parameters:
id - category id

Return
As an answer, if there is no error occurred, you will get operation status in XML:
<status> - 1 if operation is successful

8. Deleting product (product_delete.php).
To delete product, you need to open the file:
product_delete.php

Request Parameters:
id - product id

Return
As an answer, if there is no error occurred, you will get operation status in XML:
<status> - 1 if operation is successful

9. Creating new manufacturer and editing existing one (manufacturer_edit.php).
To create new or edit existing manufacturer, you need to open the file:
manufacturer_edit.php

Request Parameters (not obligatory, if it is not indicated specially):
id - manufacturer's id - to be transmitted only in case of editing the existing one. To create a new one do not transmit or transmit 0.
name - name (necessary while creating new one), up to 255 characters
url - manufacturer's web-address, up to 100 characters
description - description, up to 65Š characters
image - image file, transferred by the POST method as the browser does (<input type=file name=image>), or string containing image's address (url) in the Internet.

Return
As an answer, if there is no error occurred, you will get in XML new/existing manufacturer's id:
<id> - manufacturer's id, integer number

10. Creating new/editing existing category (category_edit.php).
To create new category or edit existing one, you need to open the file:
category_edit.php

Request Parameters (not obligatory, if it is not indicated specially):
id - category id - to be transmitted only in case of editing the existing one. To create a new one do not transmit or transmit 0.
parID - parent category's id. Integer. If 0 (or is not setuped) - top level category
name - name (necessary while creating new one), up to 100 characters
title - full name, up to 100 characters.
active - activity flag - 0 or 1. For the new one 1 is default.
priority - priority. Integer 0-255.
comment - short description, up to 255 characters
description - description, up to 65Š characters
meta_title - title to be inserted into the meta-tags, up to 255 characters
meta_keywords - keywords to be inserted into the meta-tags, up to 65K characters
meta_description - description to be inserted into the meta-tags, up to 65K characters
image - image file, transferred by the POST method as the browser does (<input type=file name=image>), or string containing image's address (url) in the Internet.

Return
As an answer, if there is no error occurred, you will get in XML new/existing category id:
<id> - category id, integer number

11. Creating new/editing existing product (product_edit.php).
To create new product or edit existing one you need to open the file:
product_edit.php

Request Parameters (not obligatory, if it is not indicated specially):
id - product id - to be transmitted only in case of editing the existing one. To create a new one do not transmit or transmit 0.
categories - list of categories through comma (necessary while creating new one), to which the product given needs to be linked. Can be transmitted as array (categories[])
categories_delete - list of categories through comma, which the product given needs to be unlinked of. Can be transmitted as array (categories_delete[])
name - name (necessary while creating new one), up to 255 characters
active - activity flag. 0 or 1. For the new one default is 1.
priority - priority. Integer (0-255).
time_available - time in unix-timestamp (that is in seconds from the beginning of 1970) when the product will be available
date_available - the date in the YYYY-MM-DD format, when the product will be available (time_available in the other format)
in_stock - availability. 0 or 1. Default is 1
is_new - indicates that the product is new. 0 or 1. Default is 1
price - primary product price (necessary while creating new one).
opt1 - minimal quantity for small wholesales (if it equals 0 then there are no wholesales provided).
price1 - product price for small wholesales.
opt2 - minimal quantity for large wholesales (if it equals 0 then there are no wholesales provided).
price2 - product price for large wholesales.

price_type - special product type. 0 or absent - general product, 1 - Special (discounts), 2 - Featured (seasonal products and so on).
spec_time1* - low time bound in unix-timestamp when this product has the specified special type. If it equals 0 - then there are no limitations from this side
spec_date1 - low time bound in the YYYY-MM-DD format, when this product has the specified special type. (Instead of spec_time1 -the same data in the other format)
spec_time2 - high time bound in unix-timestamp when this product has the specified special type. If it equals 0 - then there are no limitations from this side
spec_date2 - high time bound in the YYYY-MM-DD format, when this product has the specified special type. (Instead of spec_time2 -the same data in the other format)
spec_price - main price for this period. If it equals zero then it is equal to the primary price.
spec_price1 - small wholesale price for this period. If it equals zero then there are no wholesales.
spec_price2 - large wholesale price for this period. If it equals zero then there are no wholesales.
quantity - quantity in stock. The number 1000000 means no limit. 1000000 is default.
num_choosed - number such of purchased products.
mnfID - manufacturer's ID. If it equals zero, then manufacturer is not defined.
code - internal product's code. Up to 16 characters.
model - product model
url - product official page webaddress. Up to 255 characters
weight - product weight
measure- units (e. g. sacks, kilogramms, ...) Up to 50 characters.
dimensions - Up to 100 characters.
comment - short description, up to 255 characters
description - full description, up to 65K characters
meta_title - title to be inserted into the meta-tags, up to 255 characters
meta_keywords - keywords to be inserted into the meta-tags, up to 65K characters
meta_description - description to be inserted into the meta-tags, up to 65K characters
imageN - image file, transferred by the POST method as the browser does (<input type=file name=image>), or string containing image's address (url) in the Internet. Here N is image number 1-6. 1,2,3 - small, middle and big images, and 4,5,6 - additional ones. And of course you can transfer several of them: image1=...&image2=...
version - resize and create new images. If you submit the value "1" in this field, the script will automatically create "image1" and "image2" from "image3" by resizing, if this field is not empty.
documentN - additional document file, transferred by the POST method as the browser does (<input type=file name=document1>), or string containing image's address (url) in the Internet. Here N is document number 1-3. And of course you can transfer several of them: document1=...&document2=...
document_name N - appropriate additional document name. Up to 50 characters. Here N - is document number 1-3. And of course you can transfer several of them: document_name1=...&document_name2=...
addition_field[code] - additional field. Here code - is given additional field code. For example addition_field[type] or addition_field[material]. As the value next data are transmitted: 0 or 1 - if it's checkbox type field, string - if it's text type field, id - integer number, appropriate option ID, if it's select type field, and the list of options ids (integer numbers) through comma, if it's multiple type field.
What's more each product has a set of its unique attributes which customer has to select/indicate while ordering this product. Each attribute has its own set of options (values), which buyer is choosing from. You can see above attributes structure in products sampling interface. Basically you have multilevel structure. The number of transmitted data levels is cut as much as possible using suffixes for providing easy work. Thus, for example, instead of attr[1][name], you will transmit attr_name[1], etc. Meanwhile these arrays will be matched by index indicated in brackets, so for example attr_name[1] will be matched to attr_code[1], as well as to attr_type[1] etc.
There are few simple rules:
1. If you don't want to change the set of attributes of existing product, or new product created does not have attributes, so data set below do not need to be transmitted at all.
2. However if you transmit these data then product's attributes set will be completely redefined according to these data. As you see each time when you change at least one attribute or attribute's option you must transmit full set of given product's attributes.
3. If you want to delete existing product's attributes without creating new ones, you don't need to transmit parameters set below, but transmit just one parameter drop_attrs=1.
The set of parameters, necessary for attributes processing:
attr_name[] - attribute name (example: Color or Siz¥). Necessary. String up to 50 characters.
attr_type[] - attributes type - integer number 0 to 2. Necessary. There are 3 attribute types:
0 - attribute obligatory selected by the customer, 1 - optional attribute - that is the one that is not obligatory, 2 - multiple choice attribute.
attr_code[] - unique (within product's limit) attribute's code (example:color). String up to 50 characters. This field is not necessary. If it is not transmitted or it is not unique then system will select unique code itself automatically.
attr_description[] - attribute description. String up to 255 characters.
Furthermore the set of options should be transmitted for each attribute (the set of its possible values). This set is transmitted with several (yes, unfortunately) 2D arrays where the first array index (in the first brackets) is attribute index and the second array index (in second brackets) is option index. For example attr_option_name[color][red] or attr_option_name[1][1], etc. As you can see values will be matched by correspondence of the two indexes.
attr_option_name[][] - option name. Necessary. String up to 50 characters. Example: Red Metallic
attr_option_code[][] - unique (within attribute) option code (example: red-metal). String up to 50 characters. This field is not necessary. If it is not transmitted or it is not unique then system will select unique code itself automatically.
attr_option_price[][] - option price (can be absent then it's 0). Can be positive or negative and is added to product price while selecting by buyer.
attr_option_weight[][] - option weight (can be absent then it's 0). Can be positive or negative and is added to product weight while selecting by buyer.
attr_option_question[][] - additional question which is asked of buyer while selecting this option.
Remember that all parameters are not obligatory except those where it's specially indicated.

Return
As an answer, if there is no error occurred, you will get in XML new/existing product id:
<id> - product id, integer number

Errors code table (skipped numbers are reserved for the future)

Orders status table