# Shoper

Shoper integration with Ritevo: Client ID and API token, connecting the store, mapping your own statuses and payments, fetching orders, messages by email.

The Shoper integration brings orders from your store into Ritevo. You connect it with API access details generated in the Shoper panel. Because every Shoper store sets up its own statuses and payment methods, after connecting you assign them to Ritevo statuses in the mapping. Shoper delivers buyer messages by email - you handle them in Ritevo through an email integration.

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

The same Shoper 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 `SHOPER`; `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/shoper/{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 access details in the Shoper admin panel. Copy them right away - you will paste them into Ritevo when adding the integration.

1. Sign in to the Shoper panel and choose **Aplikacje i integracje** (apps and integrations), then **Zewnętrzne aplikacje** (external apps).
2. Click **Dodaj integrację** (add integration) and enter any name, for example "Ritevo".
3. Tick **all** access areas with full permissions - even though Ritevo uses only some of them today, new features will then work without changes in the Shoper panel.
4. Save and copy the **Client ID** and the **API token**.

> **Good to know:** Shoper shows the token only once, right after creating it. If you close the window without copying it, create the integration in the Shoper panel again.

## 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 **Shoper** 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 - for example `https://mystore.shoparena.pl`.
5. In the **Client ID** and **API token** fields paste the details from the Shoper 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 Shoper tile framed in the Online stores section](https://ritevo.com/docs/integrations/shoper/en-catalogue.webp)

![The Shoper add-integration screen with the Account name, Store address, Client ID and API token fields](https://ritevo.com/docs/integrations/shoper/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**.
- **Client ID** - the identifier from the Shoper panel, given when adding. You change it together with the token through **Update credentials**.
- **Fetch orders** - once on, Ritevo checks for new orders and status changes about every 10 minutes. The rules shared by all channels: [Fetching orders](https://ritevo.com/en/docs/orders/fetching-orders).
- **Fetch messages** - instead of a switch there is a note that Shoper messages are handled through an email integration, and an **Add integration** button that leads to adding one.
- **Order status mapping** and **Payment method mapping** - described below.

![Shoper integration details: the account name, store address, Client ID, the Fetch orders switch and the messages card pointing to the email integration](https://ritevo.com/docs/integrations/shoper/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.

> **Good to know:** In Shoper you create statuses and payment methods yourself in the store's panel, so **nothing is assigned up front**. Set the mapping right after connecting, before you turn on order fetching - otherwise every order arrives as **Awaiting confirmation** with the **Other** payment.

### Order status mapping

Ritevo reads the status list from your store, so you see them under the names you gave them in the Shoper panel. **Up front** nothing is assigned. **You assign yourself** every status, because every store creates its own. An example assignment for Shoper's standard statuses:

- **Confirmed** (API: "Confirmed" = `CONFIRMED`; value in `orderStatusMappings[].status`) - accepted for processing, awaiting delivery, being packed, ready to ship, shipped.
- **Cancelled** (API: "Cancelled" = `CANCELLED`; value in `orderStatusMappings[].status`) - cancelled.
- **Awaiting payment** (API: "Awaiting payment" = `WAITING_FOR_PAYMENT`; value in `orderStatusMappings[].status`) - placed, awaiting payment, rejected.
- **Awaiting confirmation** (API: "Awaiting confirmation" = `WAITING_FOR_CONFIRMATION`; value in `orderStatusMappings[].status`) - returned, claim - orders you want to look at before doing anything with them.

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 Shoper integration with an example assignment of the store's statuses](https://ritevo.com/docs/integrations/shoper/en-statuses.webp)

### Payment method mapping

Ritevo reads the method list from the payments set up in your store, under their names from the Shoper panel. **Up front** nothing is assigned. **You assign yourself** every method, because every store has its own. An example assignment:

- **Bank transfer** (API: "Bank transfer" = `BANK_TRANSFER`; value in `paymentMethodMappings[].paymentMethod`) - mBank mRaty, Przelewy24.pl, Klarna, InPost Pay, Stripe - online payment operators you want to settle like a transfer.
- **Cash** (API: "Cash" = `CASH`; value in `paymentMethodMappings[].paymentMethod`) - Cash.
- **Cash on delivery** (API: "Cash on delivery" = `CASH_ON_DELIVERY`; value in `paymentMethodMappings[].paymentMethod`) - Cash on delivery.
- **P24** (API: "P24" = `P24`; value in `paymentMethodMappings[].paymentMethod`) - Autopay or another operator you want to see separately.

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

![The Payment method mapping card of the Shoper integration with an example assignment of the store's methods](https://ritevo.com/docs/integrations/shoper/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/shoper/{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 numeric Shoper status and payment ids. The current shape is in Swagger.

## What this integration gives you

- **Orders** - new and changed Shoper orders land in the orders table, with the buyer's details, invoice details, delivery and line items with product images.
- **Messages** - through an email integration, see below.

## Orders from Shoper

Ritevo fetches the whole Shoper order: the buyer, billing and delivery address, payment, line items with gross prices and the product's main image. An order whose status changed in the store is fetched again.

- **Statuses and payments** - translated according to your mapping, described above. The paid amount is what the buyer actually paid - including a partial payment.
- **Delivery address** - when the buyer gave no separate delivery address, Ritevo uses the billing address.
- **Dispatch deadline** - the dispatch date the store declared (from the products' lead times) goes into the order as the dispatch deadline.
- **Variants and custom fields** - the chosen variant and whatever the buyer typed into the product's fields (for example an engraving) are appended to the line item's name.
- **Merged orders** - if you merged several orders into one in Shoper, Ritevo fetches the original orders and skips the merged one, so goods are not counted twice.
- **Additional services** - not supported. This integration does not pass on services such as gift wrapping or carry-in. If you want to sell them, list them as a separate product or offer - they then show in the order as a regular line item. More about [additional services](https://ritevo.com/en/docs/orders/fetching-orders#additional-services).
- **Invoice** - if Shoper 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.

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

## Buyer messages from Shoper

Shoper does not expose an inbox through its API - buyers write to you **by email** to the store's address. To see and answer those messages in Ritevo, add an [email integration](https://ritevo.com/en/docs/messages/fetching-messages) for that mailbox. The messages then appear in Ritevo like ordinary emails; they are not linked to the Shoper integration or its orders.

## 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 Shoper.
- It does not support deliveries to pickup points yet (for example parcel lockers). An order with such a delivery is fetched normally, but without the chosen point.
- It does not fetch messages - Shoper does not expose them through its API.
- It sends nothing back to Shoper: when you change an order's status, create a shipment or issue an invoice in Ritevo, the order in Shoper stays unchanged.

## The integration through the API

This integration's endpoints are under `/integrations/shops/shoper`, 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.