# PrestaShop

PrestaShop integration with Ritevo: the webservice key, connecting the store, mapping statuses and payment modules, orders and customer service messages.

The PrestaShop integration brings orders and customer service messages from your store into Ritevo. You connect it with a webservice key generated in the PrestaShop panel. You translate the store's statuses and payment modules to Ritevo statuses in the mapping on the integration page.

> **Required integration:** You need a working PrestaShop store and access to its admin panel to generate the API keys.

The same PrestaShop store can be connected only once. When you add it again, Ritevo refreshes the existing integration and turns it back on, even if it was deleted.

Uniqueness: the integration is unique within the company by `externalId` and the type `PRESTASHOP`; `externalId` is the store url without a trailing `/` (a url ending in `/` is saved without it). Creating it again with the same url refreshes the existing integration instead of adding a new one: it replaces the credentials, sets `authError=false` and `active=true` and returns that integration. You can also send new credentials with `PATCH /integrations/shops/prestashop/{integrationId}/credentials` - in any state of the integration, also when `authError=false` and `active=true`; it sets `authError=false` and `active=true`.

## How to generate the API key

You create the key in the PrestaShop admin panel. Copy it in full - you will paste it into Ritevo when adding the integration.

1. Sign in to the PrestaShop panel and in the left menu choose **Advanced Parameters**, then **Webservice**.
2. In the **Configuration** section set **Enable PrestaShop's webservice** to **Yes** and save.
3. Click **Add new webservice key**. Click **Generate**, and in the **Key description** field enter any name, for example "Ritevo".
4. In the **Permissions** table tick **everything**: every resource and every action (View, Add, Modify, Delete). Set **Status** to **Yes** and save. Copy the key from the **Key** field.

> **Good to know:** Grant full permissions even though Ritevo uses only some of them today - a key with missing access yields incomplete orders or no messages, and new Ritevo features will then work without touching the key.

## Connecting the account

Start in Ritevo:

1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner.
2. In the **Online stores** section pick the **PrestaShop** tile.
3. In the **Account name** field enter your own name for the integration, for example the store's name.
4. In the **Store address** field enter the store's full address with `https://`, without a trailing slash and without `/api` - for example `https://mystore.com`.
5. In the **Webservice key** field paste the key from the PrestaShop panel.
6. Click **Add integration**. Ritevo connects to the store right away and checks the details: if they are valid, the integration is added and its settings open. If not - you will see the error returned by the store and nothing is saved.

![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp)

![The Add integration screen with the PrestaShop tile framed in the Online stores section](https://ritevo.com/docs/integrations/prestashop/en-catalogue.webp)

![The PrestaShop add-integration screen with the Account name, Store address and Webservice key fields](https://ritevo.com/docs/integrations/prestashop/en-add.webp)

## Integration settings

After connecting, the integration is **Active**, but order fetching is **off** - you turn it on yourself. On the integration page you will find:

- **Account name** - your own name for this integration, for example the store's name. You can change it at any time.
- **Store address** - the address given when adding. It cannot be changed here; a new address or new keys go through **Update credentials**.
- **Fetch orders** - once on, Ritevo checks for new and changed orders about every 10 minutes. The rules shared by all channels: [Fetching orders](https://ritevo.com/en/docs/orders/fetching-orders).
- **Fetch messages** - once on, Ritevo fetches customer service threads about every 10 minutes, reaching 7 days back on the first fetch. Shared rules: [Fetching messages](https://ritevo.com/en/docs/messages/fetching-messages).
- **Order status mapping** and **Payment method mapping** - described below.

![PrestaShop integration details: the pickup point notice, account name, store address and the Fetch orders and Fetch messages switches](https://ritevo.com/docs/integrations/prestashop/en-details.webp)

> **Good to know:** You can replace the key at any time with the same **Update credentials** button, not only after an error.

## Mapping statuses and payments

Every store names its order statuses and payment methods its own way, so with online stores you decide yourself how they translate to Ritevo statuses and methods. You set the mapping once, on the integration page, and it applies to every order fetched from then on.

> **Good to know:** You can change the mapping freely at any time to suit your needs - including the assignments filled in up front, which are only a starting point.

### Order status mapping

Ritevo reads the status list from your store, so you see them under the same names as in the PrestaShop panel. **Up front** the statuses PrestaShop is installed with are assigned. **You assign yourself** statuses added by payment modules or by hand. The starting assignment:

- **Confirmed** (API: "Confirmed" = `CONFIRMED`; value in `orderStatusMappings[].status`) - Payment accepted, Processing in progress, Shipped, Delivered, Refunded, Remote payment accepted, Payment received. A refunded order was a real sale, so it stays confirmed.
- **Cancelled** (API: "Cancelled" = `CANCELLED`; value in `orderStatusMappings[].status`) - Canceled.
- **Awaiting payment** (API: "Awaiting payment" = `WAITING_FOR_PAYMENT`; value in `orderStatusMappings[].status`) - Awaiting check payment, Payment error, Awaiting bank wire payment, Awaiting remote payment, Awaiting Cash On Delivery validation.
- **Awaiting confirmation** (API: "Awaiting confirmation" = `WAITING_FOR_CONFIRMATION`; value in `orderStatusMappings[].status`) - nothing up front; orders with an unassigned status land here too.

One Ritevo status can have several store statuses assigned, but one store status only one Ritevo status. An order with a status you have not assigned anywhere arrives as **Awaiting confirmation** - you will see it and decide what to do.

![The Order status mapping card of the PrestaShop integration with the store's statuses assigned by default](https://ritevo.com/docs/integrations/prestashop/en-statuses.webp)

### Payment method mapping

PrestaShop does not expose a list of payment modules, so here you type the **module names** by hand - the ones you see in the PrestaShop panel in an order's details or under **Modules → Payment** (for example `ps_wirepayment`, `payu`). **Up front** the most common modules are filled in. **You add yourself** other modules and remove the ones you do not need. The starting assignment:

- **Bank transfer** (API: "Bank transfer" = `BANK_TRANSFER`; value in `paymentMethodMappings[].paymentMethod`) - ps_wirepayment, ps_checkpayment.
- **Cash on delivery** (API: "Cash on delivery" = `CASH_ON_DELIVERY`; value in `paymentMethodMappings[].paymentMethod`) - ps_cashondelivery.
- **Card** (API: "Card" = `CARD`; value in `paymentMethodMappings[].paymentMethod`) - stripe_official.
- **PayU** (API: "PayU" = `PAYU`; value in `paymentMethodMappings[].paymentMethod`) - payu.
- **PayPal** (API: "PayPal" = `PAYPAL`; value in `paymentMethodMappings[].paymentMethod`) - ps_checkout, paypal.
- **P24** (API: "P24" = `P24`; value in `paymentMethodMappings[].paymentMethod`) - przelewy24.

A payment made with a method you have not assigned anywhere arrives as **Other**.

![The Payment method mapping card of the PrestaShop integration with payment module names filled in by default](https://ritevo.com/docs/integrations/prestashop/en-payments.webp)

> **Good to know:** You save mapping changes with the **Update integration** button at the bottom of the page. They apply from the next fetch - orders fetched earlier do not change their status retroactively.

You save the mappings with `PATCH /integrations/shops/prestashop/{integrationId}` together with `accountName`: `orderStatusMappings` (`{ status, externalIds }`), `paymentMethodMappings` (`{ paymentMethod, externalIds }`) and `fieldMappings` as an empty list - this store has no fields to map. Each list must carry every value of its enum - send an unassigned value with an empty list. `externalIds` are PrestaShop status ids and payment module names. The current shape is in Swagger.

## What this integration gives you

- **Orders** - new and changed PrestaShop orders land in the orders table, with the buyer's details, invoice details, delivery and line items with product images.
- **Messages** - PrestaShop customer service threads land in the inbox; you reply to them from Ritevo.

## Orders from PrestaShop

Ritevo fetches the whole PrestaShop order: the customer account with the invoice address, the delivery address and carrier, payments, line items with gross prices and product images. An order changed in the store (for example a new status) is fetched again.

- **Statuses and payments** - translated according to your mapping, described above. The paid amount is the sum of payments registered in PrestaShop.
- **Buyer's note** - the comment typed at checkout goes into the order as the buyer's message.
- **Additional services** - supported. When the buyer chooses gift wrapping or recycled packaging, you see them in the order as separate line items for the whole order, also when they are free. The gift message is supported too - the text the buyer wants added to the parcel. You see it together with the buyer's message, in a **Gift message** box. More about [additional services](https://ritevo.com/en/docs/orders/fetching-orders#additional-services).
- **Discounts** - cart rules (discount codes) appear as separate line items with a negative amount, so the items add up to the order total.
- **Guest checkout** - a guest order is fetched normally.
- **Invoice** - if PrestaShop provides the buyer's tax id or its equivalent, the order gets the **Customer asks for an invoice** flag with the company details and the number filled in.

The card text is in `messageFromBuyer`, wrapped in `[GIFT_MESSAGE]` and `[/GIFT_MESSAGE]` markers, before the buyer's comment. Everything outside the markers is the buyer's message.

> **Good to know:** An order with the **Confirmed** status is taken over by Ritevo - later changes on the sales channel's side are skipped. More in [Fetching orders](https://ritevo.com/en/docs/orders/fetching-orders#who-manages).

## Messages from PrestaShop

Ritevo fetches threads from PrestaShop's **Customer Service** - both those from the contact form and those attached to an order. Each thread is a conversation in Ritevo:

- **Reply** - you reply from Ritevo; in PrestaShop the reply is stored as a message from a store employee. There are no disputes or claims - PrestaShop has none.
- **Link to the order** - a thread about an order is attached to that order in Ritevo.
- **Private messages** - employee notes marked private in PrestaShop are not fetched.
- **Attachments** - PrestaShop provides only the name of the attached file, not the file itself. In Ritevo you see the name; open the file in the PrestaShop panel. You cannot send attachments either.

## Reconnection required

This state appears when the store stopped accepting the credentials - the key was deleted in the store's panel, lost its permissions, or the store address changed. Until you provide new details, Ritevo neither fetches nor sends any data from that store.

1. Generate new keys in the store's panel - the same way as when connecting for the first time.
2. On the integration page in Ritevo click **Update credentials**, enter the store address and the new keys and confirm. Ritevo checks them with the store just like when adding - wrong details return an error, valid ones refresh the connection. The mappings, fetching settings and history stay unchanged.

> **Good to know:** Reconnecting clears the **Reconnection required** state straight away and turns the integration on - also when it was deleted earlier. You do not need to restore it separately.

In the API, reconnecting sets `authError=false` and `active=true` on the integration, also when it was deleted (`active=false`). Which endpoint does it for a given integration is described in the uniqueness note at the top of the page.

## Deleting the integration

**Delete integration** turns the integration off in Ritevo: it stops fetching and sending data, but what it fetched earlier stays. **Restore integration** turns it back on.

## What the integration does not do

- It does not manage listings: it does not list, change prices or stock in PrestaShop.
- It does not support pickup points (for example parcel lockers). PrestaShop has no standard field for them - each carrier module stores the chosen point on its own, out of the webservice's reach. An order with such a delivery is fetched normally, but without the point; you see a warning about this at the top of the integration page.
- It sends nothing back to PrestaShop: when you change an order's status, create a shipment or issue an invoice in Ritevo, the order in PrestaShop stays unchanged.

## The integration through the API

This integration's endpoints are under `/integrations/shops/prestashop`, and the ones shared by the whole type (list, get one, fetching switches, delete, restore) under `/integrations/shops`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs.


---

All help in one file: https://ritevo.com/llms-full.txt. Help map with links to every page: https://ritevo.com/llms.txt.