Catalog sync before Black Week: when new prices and products reach the chat
How catalogue sync works in a shop chat: when new items arrive, why discontinued ones disappear after a complete run and what a failed run leaves in place.
In plain language
Your shop chat only knows the items in its list of goods.
With Shopware, this list is synced with the shop on a plan, which means it is brought up to date. When it answers, the chat asks the shop for the price and if the item is there.
If an item is gone from the shop, the chat stops naming it after the next good sync.
If a sync goes wrong, the old state stays. You see the error in the admin area.
Without Shopware, you send the list yourself. The more often you send it, the more up to date the chat is.
A shop chat is only as current as the catalogue it answers from. New items arrive, others are discontinued, prices change, and in weeks full of promotions, such as the days around Black Friday, this often happens several times a day. Operators then face three questions: when does the chat know the new state? What happens to an item that no longer exists in the shop? And what does the assistant name when a sync fails? This article describes the mechanics behind it: how XICBOT syncs the catalogue on a schedule when connected to Shopware Community Edition, why only a complete run withdraws an item, what a failed run leaves in place and what matters when the catalogue is delivered as a file.
Labels in the illustration
- Shop
- Sync
- Chat names
- Live
- Item B discontinued
- taken out of the sales channel
- Run 1: complete
- B marked as withdrawn
- and set to unavailable
- B no longer named
- not even as an accessory
- on another card
- Item C newly created
- shop answers too slowly
- Run 2: failed
- previous stock stays,
- error at the connection
- C not yet known
- answers from the state
- before run 2
- Shop fast again
- no further change
- Run 3: complete
- C taken over, time shown
- under “Last sync”
- C is named
- as a card, provided the
- shop lists it as available
- Sequence
- Price and availability, in the cart too: looked up in the shop when answering
- If the shop does not answer: last synced state, named with its timestamp
- Complete run: catalogue updated
- Failed run: catalogue unchanged
Two routes into the catalogue
The assistant only names items that are in its catalogue. Whatever is missing there it does not show as a card, and it is instructed not to invent it but to say that the catalogue does not contain it. How items get into this catalogue depends on the shop system. If your shop runs on Shopware Community Edition, you store the shop address and the access key of a sales channel for the Store API. XICBOT uses it only to query items and the currency of the channel and writes nothing into the shop through this connection; the key is stored encrypted and only ever shown masked. With other shop systems, the product catalogue is handed over as a file or through the delivery interface and matched by item number. Both routes lead into the same catalogue, and both require a package that includes the shop connection, as Pro does: without it there is neither the catalogue nor product search and cart in the conversation, not even with a delivery of your own. They differ, however, in how an item drops out again, what happens in case of an error and who sets the pace. How both routes are set up is described on the page about the assistant for online shops.
| Feature | Shopware Community Edition | Other shop systems |
|---|---|---|
| Where the items come from | from the shop, synced on a schedule | as a file or through the delivery interface |
| Price and availability in the conversation | looked up in the shop when answering | state of the last delivery, no query into the warehouse |
| Discontinued item | withdrawn after a complete sync and set to unavailable | once a delivery lists it as unavailable or it is removed from the catalogue by hand |
| Failure | existing stock stays, the error is reported | if a single entry is invalid, the run writes none; the state of the last delivery still applies, as it does when a delivery does not arrive |
| Who sets the pace | the sync schedule, can be brought forward manually | you, with every new delivery |
Two rhythms: sync and live lookup
With a shop connection, two processes work side by side, and whoever keeps them apart can answer most questions about how current the chat is. The sync runs in the background on a fixed schedule. It reads the catalogue of the sales channel, creates new items, takes over changed details and withdraws items the shop no longer returns. The live lookup, by contrast, happens in the conversation. When the product search finds an item from the shop, the tool asks the shop for price, strike-through price, availability and delivery time, at the moment of the answer. Whatever the shop does not report as available is dropped from the answer. If the shop does not answer, the last synced state applies, and the assistant says that it is that state. How often the sync runs and how it can be brought forward manually is described in the documentation on catalogue and shop. This article deliberately names no interval as a promise: for the price and availability of an item that has been found it usually does not matter, and for everything else what counts is whether the last run succeeded.
- From the shop when answering: price, strike-through price, availability and delivery time of a hit. If the shop does not answer, the last synced state applies, and the assistant names its timestamp.
- With the sync: title, description, currency, image, product address and rating. You change these details in the shop; the next sync overwrites them in the catalogue.
- Only in the catalogue: features, accessories, “customers also bought”, button target, cart address and number of ratings. You maintain these fields in XICBOT, and the sync leaves them in place.
- New and restocked items: new items are only in the catalogue after a sync. An item that was not available at the last sync and is back in stock by now also only appears after the next sync. The live lookup when answering only asks about hits of the search, and the search only finds items that are set to available in the catalogue.
The price does not wait for the sync
With a connected shop, the price and availability of an item that has been found usually do not depend on the last sync: both are looked up when answering. New items, changed titles and images and the withdrawal of discontinued items, on the other hand, wait for the sync. Even an item that was not available at the last sync and is back in stock by now only appears after the next sync.
What discontinued means for the chat
In a shop there are two ways an item leaves the range, and for the chat they are different. An item that is temporarily sold out stays in the shop but is not reported as available. During the live lookup it drops out of the answer without any sync being needed. If a sync runs during that time, it takes the item over as unavailable; it is then only named again after the sync that reads it as available once more. How the assistant offers alternatives in that case, and when it says openly that nothing fits, is described in the article on sold-out items during the sales week. A discontinued item, by contrast, has disappeared from the sales channel, for example because the range has changed, a model has been replaced by its successor or the manufacturer has stopped making it. The shop simply no longer returns it during the sync. For the assistant’s catalogue this is a different situation from an empty warehouse: there is no stock that could come back and no delivery time that could be named.
For this case the rule is: the assistant no longer names an item discontinued in the shop after the next sync, not even through a reference on another card. Technically, the sync marks the entry as withdrawn and sets it to unavailable. The product search only finds entries set to available, and an accessory reference to such an entry produces no card. Nothing is deleted in the process: features and accessories you maintained on the entry are kept. Between being taken out of the shop and the next complete sync, the item is still in the catalogue as available. If the search finds it during that time, the tool checks with the shop when answering. If the shop does not report it as available there, it is dropped from the answer in that case too. Withdrawal by the sync is therefore the lasting clean-up, and the live lookup is the safeguard for the time before it.
Why only a complete run withdraws items
The sync cannot see directly that an item has been discontinued. All it sees is that the shop no longer returned it. After a complete run that is a reliable conclusion, after an aborted one it is not: a run that ends with a timeout in the middle of the catalogue did not find the rest empty, it did not reach it at all. If it withdrew every item it had not read, a short disruption would make a large part of the range disappear from the chat, and the next successful run would first have to restore it. That is why the catalogue stays unchanged after a failed run, and only a run that has read every page of the shop withdraws items. You may know the principle from write actions in the conversation: an abort is not a result and is not treated as one. How XICBOT distinguishes states there is described in the article on failed write actions.
Only after a run that has read all pages of the shop are shop products that no longer came back set to unavailable as withdrawn. Nothing is deleted.
| Outcome of the run | What happens to the catalogue | What the chat names afterwards |
|---|---|---|
| complete and successful | new items created, changed details taken over, items no longer returned withdrawn | the new state; withdrawn items no longer |
| failed, for example because of the key, reachability or time | stays unchanged | the previous state; price and availability still looked up when answering, as long as the shop answers |
| incomplete, because the shop has more items than one sync reads | what was read is taken over, missing items are not withdrawn | the items read in the new state, the rest in the previous one |
| shop returns no items although it had some before | stays unchanged, with a note to check the sales channel | the previous state |
| connection paused | no sync | the state of the last sync; the live lookup in the conversation is paused as well |
When a sync fails
If a sync fails, the existing stock stays in place and the error is reported. For the chat this initially means: it keeps answering from the catalogue as it was before the failed run. For an item that still exists this is usually not critical, because the tool looks up price and availability when answering, provided the shop can be reached at that moment. A failed run becomes noticeable in two places. New items are missing until a run succeeds, and a discontinued item stays in the catalogue as available until then. During that time, the fact that the assistant still does not offer it depends on the live lookup: if the shop does not report it as available, it is dropped. If the shop itself cannot be reached, the last synced state applies to all hits, and the assistant names its timestamp. Which cause applies is shown as a message at the shop connection. Some of them are quick to assign; the documentation on catalogue and shop has the complete list.
| Message at the shop connection | Typical occasion | What to do |
|---|---|---|
| “The shop rejected the access key. Check that it belongs to this sales channel.” | key renewed in the shop or sales channel changed | enter the access key of the correct sales channel again |
| “The shop could not be reached.” | maintenance, server move or outage | queue a manual sync after the maintenance |
| “The address redirects. Enter the address the shop redirects to.” | new domain or changed path of the shop | enter the redirect target as the shop address |
| “The shop took too long for the whole sync. The catalogue stays unchanged.” | shop under load, for example during a promotion | sync again later; if it persists, have the shop’s response times checked |
| “The shop returned no products although it had some before. The catalogue stays unchanged; check the sales channel.” | sales channel emptied or items hidden there | check how the items are assigned to the sales channel |
Keeping an eye on the sync
The admin area shows the state of the sync at the shop connection. Under “Last sync” it shows whether one is running, or the time of the last run with “successful” or “failed”. The “Products” row counts how many entries were read, newly created, updated and withdrawn. If the last run failed or was incomplete, the “Reason” row names the message, together with the sentence “The catalogue shows the state of …”, provided there was a successful sync before. In the product list, every product from the shop also carries the note “from the shop” with the date and time of its last sync. With the Administration role, “Sync now” queues a manual sync. It takes precedence over the regular one, a sync that is already waiting is not duplicated, and there is a lock period between two manual syncs. Every role in the account may view the state. Who may do what in the team is described in the article on roles and approvals.
- Check the time: Does “Last sync” show a time after your change in the shop, and with “successful”?
- Read the counters: Does the number of withdrawn items roughly match what you took out of the range? An unexpectedly high number can point to a changed sales channel.
- Read the reason: With “failed” or an incomplete run, the “Reason” row names the message; the table above assigns some of them.
- Sync manually: Once a cause has been fixed, choose “Sync now” instead of waiting for the next regular run.
- Ask in a test conversation: about a discontinued item and about a new one. The discontinued item should appear neither as a card nor as an accessory, the new one as a card.
Without a shop connection: delivering the catalogue
If your shop runs on a different system, the catalogue does not come through a sync but through a delivery: as a file or through the delivery interface. According to the page on the assistant for online shops, the catalogue takes up to 500 items per call, matching is by item number, and a second run of the same file therefore creates no duplicates. Nothing is looked up live in the process: availability and delivery time are fields on the item, as current as the last delivery and without any query into the warehouse. How often it is delivered decides how current the answers are. For discontinued items this means: the import creates and updates. The documentation does not describe an item dropping out merely because it is missing from the next list. A discontinued item therefore belongs explicitly in the next delivery as unavailable, or it is removed from the catalogue by hand.
- Complete entries: When the import updates an existing product, every field missing from the entry is reset to empty or to its default. Every entry should therefore go out with all the fields that are to be kept.
- All or nothing: if a single entry is invalid, the run writes none. The catalogue then keeps the state of the last successful delivery; so after every delivery, check the response with the counts of new and changed entries.
- Explicit availability: The default for “Available” is on. A discontinued item delivered without this field counts as available again afterwards.
- Stable item number: Import, cart and accessories find the product by its identifier. If the number changes, a second entry is created and the old one stays.
- Fixed delivery times: The more often you deliver, the closer the answers are to the state of your shop. Before a promotion with many changes, a separate date for the delivery is worthwhile.
- Large ranges in parts: Whatever exceeds the limit per call is delivered in several calls.
Cart: live price or last synced state
In the cart the same separation applies as in the product search. The cart sits with XICBOT, but with no price or stock truth of its own: every change recalculates the whole cart, with Shopware using the live price from the shop and, if the shop does not answer, the last synced state with its timestamp. An item the shop currently does not list as available is not added to the cart; the assistant is told which one it was and tells the visitor. An item without a catalogue entry ends the call with a message instead of inventing a price. In the end, what your shop shows at checkout is binding. The route from the chat into your shop, with pickup token and confirmation in the chat window, is shown by the cart assistant.
If the connection is paused, the cart does not ask the shop; it calculates with the price in the catalogue, which is usually the last synced state, and the assistant is not given a timestamp in that case. With a delivered catalogue, it calculates with the price from the last delivery. For price changes that are only to apply from a certain day, such as the start of a promotion, this mechanism alone is not enough: the chat knows the price the shop states today, not tomorrow’s. How the assistant handles questions about future discounts is described in the article on questions before Black Week.
Card and cart use the same price
The product card and the cart take their price from the same source, the live price of your shop. That way no price that no longer exists is carried along in the cart, and a card with a live price is not accompanied by a total from an older state. If the shop does not answer, both calculate with the last synced state, and the assistant names its timestamp.
Availability as a material characteristic
That a discontinued item should not keep appearing in the chat is not merely a question of customer friendliness. The German Unfair Competition Act expressly lists availability among the material characteristics of goods: if a commercial practice contains untrue or otherwise deceptive information about it, it is misleading (Section 5(2) no. 1 UWG). An answer in a shop chat is usually part of a shop’s communication with its customers, even if an assistant words it.
Eine geschäftliche Handlung ist irreführend, wenn sie unwahre Angaben enthält oder sonstige zur Täuschung geeignete Angaben über folgende Umstände enthält: 1. die wesentlichen Merkmale der Ware oder Dienstleistung wie Verfügbarkeit, Art, Ausführung, Vorteile, Risiken […] In operation, two places therefore deserve attention where a chat can name outdated availability: a sync that fails unnoticed for days, and a delivery that brings discontinued items back with the default “available”. Both can be spotted early with the checks from this article. Whether a single answer is misleading in an individual case depends on the circumstances and is a question for your professional advisers, not for the assistant. How unfair competition law treats offers that are not available in adequate quantities is set out in the article on sold-out items during the sales week.
Before the next range change
Whether it is a change of season, a clearance of old models or a sales week with new items: larger changes to the range can be planned so that the chat keeps up. With a shop connection, this is less about the price than about new and discontinued items, since the price is looked up when answering anyway. With a delivery, it is about everything the list carries, and about the time at which it arrives. In both cases a short, fixed sequence helps that can be repeated before every larger change.
- Beforehand: check that the shop connection is set to “active” and that the access key belongs to the sales channel in which the new items are listed.
- During the changeover: take discontinued items out of the sales channel in the shop or list them as not available; with a delivery, deliver them explicitly as unavailable, with complete entries.
- Afterwards: queue a manual sync and look for “successful” and plausible counters under “Last sync”.
- In the conversation: ask about a new and a discontinued item in a test conversation and look at the accessory suggestions as well.
- In the following week: check the conversation analytics to see which products were asked about and which questions the catalogue did not cover.
Which fields an item should carry so that the assistant can answer well from it in the first place is described in the article on product data for the shop assistant. For the sync itself, the rule of this article is short: a run that succeeds brings the new state. A run that fails leaves the old one in place and shows up at the shop connection. With a connected shop, the assistant looks up the price and availability of an item it has found when answering, and where the catalogue is delivered, it is as current as the last delivery.
Frequent questions
How quickly does the chat know a new price?
With a connection to Shopware Community Edition, the tool looks up price, strike-through price, availability and delivery time of a hit in the shop when answering. A changed price then usually appears without a sync. If the shop does not answer, the assistant names the last synced state with its timestamp. With a delivered catalogue, the price of the last delivery applies.
When does a discontinued item disappear from the chat?
After the next complete sync: it withdraws the item and sets it to unavailable, after which the assistant no longer names it, not even as an accessory. Even before that it is usually dropped from answers if the shop does not report it as available during the live lookup.
What happens if the sync fails?
The existing catalogue stays unchanged, and the error is shown at the shop connection under “Last sync” with a reason. No email is sent about it. New items are missing from the chat until a run succeeds; for existing items this is usually not critical, because price and availability are looked up when answering. Once the cause has been fixed, a manual sync can be queued.
Does the sync delete discontinued items from the catalogue?
No. It marks the item as withdrawn and sets it to unavailable. Features and accessories you maintained in XICBOT stay on the entry. An entry deleted by hand, on the other hand, cannot be restored; that is why you usually take discontinued items out in the shop and leave the withdrawal to the sync.
How often does the sync run?
Regularly, on a fixed schedule named in the documentation on catalogue and shop; in addition it can be queued manually, with a lock period between two manual syncs. That is not a promise that a change will be in the chat within a certain time. With a connected shop, price and availability of a hit usually do not depend on the sync. An item that the last sync took over as not available, however, is only found again after the next sync once it is back in stock.
My shop does not run on Shopware. How does the chat stay current?
Through delivery as a file or through the delivery interface, matched by item number. How often it is delivered decides how current the answers are. Deliver every entry in full and discontinued items explicitly as unavailable, because a missing field falls back to its default. Before promotions with many changes, an additional delivery is usually worthwhile.
Ask it yourself, Assistant of this website
Automated assistant