PrestaShop Webservice API

PrestaShop enables merchants to give third-party tools access to their shop’s database through a CRUD API, otherwise called a web service.

About CRUD & REST

The PrestaShop web service uses the REST architecture in order to be available on as many platforms as possible since the HTTP protocol and XML files are understood by most platforms if not all.

HTTP has several methods that can perform processing on data as defined in the REST architecture, among which are 5 main methods:

Enabling & Creating access to the webservice

Reach the dedicated page.

Accessing the webservice

Now that your access key is generated you can test your store’s webservice, its endpoint is located in the /api/ folder at the root of your installation of Prestashop. The quickest way to test your API is to use your browser:

• If PrestaShop is installed at the root of your server, you can access the API here: http://example.com/api/
• If PrestaShop is installed in a subfolder of your server, you can access the API here: http://example.com/prestashop/api/

The shop should prompt you for a username and a password to enter. The username is the authentication key you created and there is no password to enter.

The second and more appropriate way to access the API is to include your access key in the url, this will prevent you from entering any user name. This is also the recommended way to call the API from a javascript client, or any application. Here is an example, assuming your access API key is UCCLLQ9N2ARSHWCXLT74KUKSSK34BFKX:

• At the root of the server: https://UCCLLQ9N2ARSHWCXLT74KUKSSK34BFKX@example.com/api/
• In a subfolder of the server: https://UCCLLQ9N2ARSHWCXLT74KUKSSK34BFKX@example.com/prestashop/api/

Using your webservice API

Describe a resource

When you call the root /api URL you will get a summary of the available APIs you can call with your access token. In this example, we see that we have all rights on the /api/addresses API:

<?xml version="1.0" encoding="UTF-8"?>
<prestashop xmlns:xlink="http://www.w3.org/1999/xlink">
    <api shopName="Prestashop">
        <addresses xlink:href="http://example.com/api/addresses" get="true" put="true" post="true" patch="true" delete="true" head="true">
            <description xlink:href="http://example.com/api/addresses" get="true" put="true" post="true" patch="true" delete="true" head="true">
            The Customer, Brand and Customer addresses</description>
            <schema xlink:href="http://example.com/api/addresses?schema=blank" type="blank"/>
            <schema xlink:href="http://example.com/api/addresses?schema=synopsis" type="synopsis"/>
        </addresses>
    </api>
</prestashop>

Each API comes with two schema APIs:

• /api/RESOURCE?schema=synopsis returns basic info on the API format, the name of fields, and their type
• /api/RESOURCE?schema=blank will return a default blank data which you could use as a base for your write actions

Both calls are very much alike, only the synopsis contains more information about the data format and types:

<?xml version="1.0" encoding="UTF-8"?>
<prestashop xmlns:xlink="http://www.w3.org/1999/xlink">
    <address>
        <id_customer format="isNullOrUnsignedId"></id_customer>
        <id_manufacturer format="isNullOrUnsignedId"></id_manufacturer>
        <id_supplier format="isNullOrUnsignedId"></id_supplier>
        <id_warehouse format="isNullOrUnsignedId"></id_warehouse>
        <id_country required="true" format="isUnsignedId"></id_country>
        <id_state format="isNullOrUnsignedId"></id_state>
        <alias required="true" maxSize="32" format="isGenericName"></alias>
        <company maxSize="255" format="isGenericName"></company>
        <lastname required="true" maxSize="255" format="isName"></lastname>
        <firstname required="true" maxSize="255" format="isName"></firstname>
        <vat_number format="isGenericName"></vat_number>
        <address1 required="true" maxSize="128" format="isAddress"></address1>
        <address2 maxSize="128" format="isAddress"></address2>
        <postcode maxSize="12" format="isPostCode"></postcode>
        <city required="true" maxSize="64" format="isCityName"></city>
        <other maxSize="300" format="isMessage"></other>
        <phone maxSize="32" format="isPhoneNumber"></phone>
        <phone_mobile maxSize="32" format="isPhoneNumber"></phone_mobile>
        <dni maxSize="16" format="isDniLite"></dni>
        <deleted format="isBool"></deleted>
        <date_add format="isDate"></date_add>
        <date_upd format="isDate"></date_upd>
    </address>
</prestashop>

Read a resource

Each resource comes with an XLink argument. Using XLink, you will be able to access your various resources. XLink associates an XML file with another XML file via a link. From our root API example, we can see that we have access to http://example.com/api/addresses which will return the list of Addresses:

<?xml version="1.0" encoding="UTF-8"?>
<prestashop xmlns:xlink="http://www.w3.org/1999/xlink">
    <addresses>
        <address id="2" xlink:href="http://example.com/api/addresses/2"/>
        <address id="3" xlink:href="http://example.com/api/addresses/3"/>
        <address id="1" xlink:href="http://example.com/api/addresses/1"/>
        <address id="4" xlink:href="http://example.com/api/addresses/4"/>
    </addresses>
</prestashop>

Here is what a resource API call could look like (in this case http://example.com/api/addresses/1):

<?xml version="1.0" encoding="UTF-8"?>
<prestashop xmlns:xlink="http://www.w3.org/1999/xlink">
    <address>
        <id><![CDATA[1]]></id>
        <id_customer xlink:href="http://example.com/api/customers/1"><![CDATA[1]]></id_customer>
        <id_manufacturer><![CDATA[0]]></id_manufacturer>
        <id_supplier><![CDATA[0]]></id_supplier>
        <id_warehouse><![CDATA[0]]></id_warehouse>
        <id_country xlink:href="http://example.com/api/countries/8"><![CDATA[8]]></id_country>
        <id_state><![CDATA[0]]></id_state>
        <alias><![CDATA[Mon adresse]]></alias>
        <company><![CDATA[My Company]]></company>
        <lastname><![CDATA[DOE]]></lastname>
        <firstname><![CDATA[John]]></firstname>
        <vat_number></vat_number>
        <address1><![CDATA[16, Main street]]></address1>
        <address2><![CDATA[2nd floor]]></address2>
        <postcode><![CDATA[75002]]></postcode>
        <city><![CDATA[Paris ]]></city>
        <other></other>
        <phone><![CDATA[0102030405]]></phone>
        <phone_mobile></phone_mobile>
        <dni></dni>
        <deleted><![CDATA[0]]></deleted>
        <date_add><![CDATA[2019-01-15 22:46:55]]></date_add>
        <date_upd><![CDATA[2019-01-15 22:46:55]]></date_upd>
    </address>
</prestashop>

Available Parameters

You can add these GET parameters to your request to modify the READ response:

• display to control which fields are returned
• filter to control which items are returned
• language to control which language values are returned

Control returned fields with “display”

The display the parameter can be used to return all fields when used with the full value: http://example.com/api/addresses/?display=full.

You can also ask for certain fields if you use a list of fields names in brackets: http://example.com/api/addresses/?display=[id,lastname,firstname,phone_mobile]

Control returned items with “filter”

The EQUAL operator is used when you need to get specific items. For example, if you want the addresses for customer #1, you can filter your GET request with the filter parameter: http://example.com/api/addresses?filter[id_customer]=1

The LIKE operator is used when you need to search for items. For example, if you want the addresses with cities starting with “SAINT”: http://example.com/api/addresses?filter[city]=[saint]%

The OR operator is used when you need to get items matching several criteria: http://example.com/api/addresses?filter[city]=[paris|lyon]

Other operators can be used, such as:

• NOT EQUAL (single value): http://example.com/api/customers?filter[firstname]=![hubert] (apologies to all Huberts)
• NOT EQUAL (multiple values): http://example.com/api/customers?filter[firstname]=![hubert|leon|gaspard] (apologies again…)
• GREATER THAN: http://example.com/api/customers?filter[birthday]=>[2000-00-00%2000:00:00] (Millenials only 🙂)
• LOWER THAN: http://example.com/api/customers?filter[birthday]=<[2000-00-00%2000:00:00] (previous century only 😄)

This can be used in combination with the display parameter! Let’s say you want to get the mobile phone numbers of customers #1, #7, and #42: http://example.com/api/addresses?filter[id_customer]=[1|7|42]&display=[phone_mobile]

You can also filter by dates! A typical example would be a routine in an ERP fetching the orders since the last call: http://example.com/api/orders?display=full&date=1&filter[date_add]=[2019-11-14%2013:00:00,2019-11-14%2014:00:00]. In this example, we request the orders created on 2019-11-14 between 1 pm and 2 pm.

Special parameters

The date=1 a parameter must be used to allow data filtering (see the example above).

The limit=0,100 the parameter can be used to limit the number of returned items (similar to MySQL’s LIMIT clause).

The sort=[field1_ASC,field2_DESC] the parameter can be used to sort the results (similar to MySQL’s ORDER BY clause, with an underscore to separate the field name and the order way).

The language=1 or language=[1|2] the parameter can be used to return only these languages for translatable fields (eg: product description, category name, etc.).

The sendemail=1 the parameter can be used if you need to change the state of the order AND you want the emails to be sent to the customer: you will have to do a POST on http://example.com/api/order_histories?sendemail=1

The sendemail=1 the parameter can be used on the order_carriers endpoint to send the in-transit email with the tracking number. Example: http://example.com/api/order_carriers/12345?sendemail=1 12345 is the order carrier id.

Create a resource

To create a resource, you simply need to GET the XML blank data for the resource (example /api/addresses?schema=blank), fill it with your changes, and send a POST HTTP request with the whole XML as body content to the /api/addresses/ URL.

PrestaShop will take care of adding everything in the database, and will return an XML file indicating that the operation has been successful, along with the ID of the newly created customer.

Update a resource

To edit an existing resource: GET the full XML file for the resource you want to change (example /api/addresses/1), edit its content as needed, then send a PUT HTTP request with the whole XML file as body content to the same URL again.

Partially update a resource

To partially edit an existing resource: GET a part of the XML file for the resource you want to change (example /api/addresses/1), edit its content as needed, then send a PATCH HTTP request with the partial XML file as the body content to the same URL again.

Using JSON instead of XML

The Web services can also output JSON instead of XML. To enable JSON output you have two choices:

Query parameter

Add one of the following parameters to your query string:

• output_format=JSON
• io_format=JSON

Example:

https://UCCLLQ9N2ARSHWCXLT74KUKSSK34BFKX@example.com/api/?output_format=JSON

HTTP header

Add one of the following headers to your HTTP request:

• Io-Format: JSON
• Output-Format: JSON

Example:

GET /api/ HTTP/1.1
Host: example.com
Output-Format: JSON
Authorization: Basic VUNDTExROU4yQVJTSFdDWExUNzRLVUtTU0szNEJGS1g6