The PrestaShop Webservices

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.

CRUD is an acronym that stands for “Create, Read, Update, and Delete”. These are the four basic operations for managing data in an application.

REST defines roughly a style of software architecture, which promotes the use of HTTP methods when building web application, instead of custom methods or protocols such as SOAP or WSDL. It defines several rules, including one that is similar to CRUD, which is described below.

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

HTTP/REST CRUD SQL
POST Create INSERT
GET Read SELECT
PUT Update UPDATE
DELETE Delete DELETE

Enabling & Creating an 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:

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:

To test/call your APIs we recommend you use an API client such as Insomnia or Postman, it is easier to call the APIs than with a browser, especially for write actions.
As you noticed no password nor authentication process is required to access the APIs which is why you need to be extra careful with you access key rights and how (and whose) you distribute them.

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" delete="true" head="true">
            <description xlink:href="http://example.com/api/addresses" get="true" put="true" post="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 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 to 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>
You can notice that a resource API url always follow the same pattern:

  • http://example.com/api/RESOURCE_NAME list a type of resource
  • http://example.com/api/RESOURCE_NAME/ID_RESOURCE will return the information of the specified resource

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>

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 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 a 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 the 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 UCCLLQ9N2ARSHWCXLT74KUKSSK34BFKX