Operating repairs
Repairs are the fixes a connected assistant can make to your stock and reservation records when something has gone out of step. Every repair works in two steps: the assistant first shows you exactly what it would change, and only applies it afterwards. Every repair it applies is recorded for good, with what it changed.
On this page
Section titled “On this page”- What it takes
- Preview, then apply
- When an apply is refused
- Retrying safely
- Settling a safety-stock reservation
- Writing off held units that are gone
- Correcting a return that should have been a write-off
- Reversing one stock movement
- Booking order lines that never got their components
- Returning or writing off reserved components
- Reactivating a reservation whose hold was released
- Saying how a variant is sold
- The repair record
What it takes
Section titled “What it takes”Reading the repair record needs nothing beyond a connection. Applying a repair needs write access and the Enhanced plan, like the other inventory changes an assistant can make. Previews are reads and are open on every plan. Nothing else turns repairs on or off.
Preview, then apply
Section titled “Preview, then apply”Every repair is a pair. The preview answers, row by row, what the repair would change: the value before, the value after, and the reason a row would be refused. It also answers a preview token, valid for 15 minutes.
The apply names that token. The assistant has to send it in a later request than the one that showed you the preview: a script cannot look at a preview and apply it in the same go. That pause is deliberate: it is where you read the preview and say yes.
Preview the same repair again before anything has changed and you get the same token back, with its 15 minutes restarted.
When an apply is refused
Section titled “When an apply is refused”An apply that cannot go ahead writes nothing. It answers with a fresh preview instead of an error, so the assistant can show you the current picture straight away:
- A preview is needed when the token is unknown, when it was made in the same request as the apply, or when the apply did not come through the assistant connection.
- The preview is out of date when it is more than 15 minutes old, belongs to another repair or to different input, or when the data it was made from has changed since. Something else may have moved your stock in the meantime, so the fresh preview shows what is true now.
Either way, review the fresh preview and apply its token in a later step.
Retrying safely
Section titled “Retrying safely”Every apply carries an idempotency key that the assistant chooses. If a connection drops and the assistant sends the same apply again with the same key, it gets the original answer back and nothing is applied twice. The same key sent with different input is refused, so a key can never quietly apply something you did not preview.
A booking of order lines does one thing more. Its stock changes run after the booking is recorded, so one of them can fail while the booking stands, and the answer warns you when it does. Sending the same booking again with the same key finishes the stock changes still owed, and nothing else, and says for each what this retry did: it went through now, it failed again, or there was nothing left to do.
Settling a safety-stock reservation
Section titled “Settling a safety-stock reservation”A safety-stock reservation sometimes holds components that were in fact used for orders: the orders shipped, but never took their own components, for example because the bill was inactive when they were placed. Releasing the reservation would put those components back on sale although they are gone. Settling closes or shrinks the reservation unit by unit instead, each unit named against the order line it went to:
- Consumed: the reservation’s components went into that order line. The reservation shrinks and your stock does not change. The order is marked as having used them, so no later processing of that order takes the components a second time.
- Return: the components were not used for that order line. They go back to your available stock.
The assistant only needs to name the order: the settlement uses the order’s line with the reservation’s finished good, and the preview shows which line that is.
Each settled unit is recorded against its order line, so it can never be settled twice. A reservation settled down to zero is closed and shows whether all its units were consumed or some were returned.
The preview reads every order live from Shopify and names each unit that cannot be settled, with the reason. The most common ones:
- the order already took its own components, so the unit was not used for it: settle it as return instead, or write it off (next section) if the held components are gone;
- the order line has not shipped, or was refunded or cancelled without saying whether its items were restocked;
- the order line is not the reservation’s finished good, or the order carries that finished good on no line or on more than one;
- the reservation holds a Shopify-managed component: only reservations of virtual materials can be settled for now, so release it instead;
- a conversion of the reservation to pre-assembled stock is still in progress.
An order that is no longer in Shopify can only be settled when the assistant states what happened to the unit and names the order line, which you give it. That statement is kept in the repair record. If any unit of a preview cannot be settled, the apply is refused and nothing changes: drop or change that unit and preview again.
Writing off held units that are gone
Section titled “Writing off held units that are gone”Sometimes a safety-stock reservation holds units whose components are physically gone, but that cannot be settled against an order: the order already took its own components, so settling as consumed is refused, and settling as return would put components back on sale that are not on your shelf. Writing off lowers the reservation by the number of units you name, without putting anything back into your stock and without naming any order.
The assistant needs three things: the reservation, how many units to write off, and your reason in your own words. The reason is kept with the repair and on the reservation. The preview shows the reservation and each of its components before and after; your available stock does not change, because the held components already left it when the reservation was made. A reservation written off to zero is closed, and its history shows it was written off and why.
The preview names the reason when a write-off cannot be done: the reservation is already closed, it holds a Shopify-managed component (only reservations of virtual materials can be written off for now, so release it instead), a conversion to pre-assembled stock is still in progress, or you asked for more units than it holds. Use a write-off only for units that are really gone: units that went into an order are settled as consumed, and units that should go back to stock are settled as return or released.
Correcting a return that should have been a write-off
Section titled “Correcting a return that should have been a write-off”If units of a safety-stock reservation were settled as return but their components are not physically on your shelf, your stock shows components you do not have. The write-off cannot reach those units any more, because the settlement already took them out of the reservation. Instead, the assistant can turn those return settlements into write-offs.
It needs the settlements to correct (each settled unit has its own record, which the settlement’s answer and the repair record show) and your reason in your own words. For each one it takes back exactly what that return put into your stock, component by component, and marks the settlement as written off. The preview shows each component’s stock before and after, and every settlement that cannot be corrected, with the reason. The reservation itself, your orders, your reservations and everything that happened in your stock since stay as they are. The correction is recorded for good, linked to the stock changes it takes back.
Use it only for components that are really gone. If they are on your shelf, the return was right and there is nothing to correct.
Reversing one stock movement
Section titled “Reversing one stock movement”Sometimes a single change to a virtual material’s stock was simply wrong: a restock entered twice, a manual edit on the wrong material, or a released safety-stock reservation that gave back components it never actually held. A reversal takes back exactly that one change, or part of it, as a new entry in the material’s History that points to the one it reverses. The original entry stays, so the History still shows both.
To pick the change, the assistant reads the material’s History, the same list of changes the material’s page shows: every entry it reads there carries the reference a reversal needs. Entries from before the current History was kept carry none and cannot be reversed. Tell the assistant which change you mean, for example by its date, amount and location.
The reversal moves the stock at the same location by the opposite amount, keeps the material’s total in step, and passes the change on to your connected apps. It may take the stock below zero even when your store does not allow negative inventory, because it undoes a change your store already accepted. The preview says so when it happens.
A reversal can take back part of a change and the rest later, but never more than the change itself: every reversal counts against what is left. Only these changes can be reversed:
- a restock or a manual edit of a virtual material’s stock;
- a credit given back by a safety-stock reservation that has since been released.
The preview names the reason when a change cannot be reversed. The most common ones:
- it is Shopify’s stock, or a material whose stock Shopify keeps: correct it in Shopify;
- it belongs to an order: undo it through the order, with a cancel, a refund or a restock;
- its reservation is still open: change the reservation instead;
- it is part of a work order’s pick, or it set a total rather than changing it;
- the material’s unit was converted since;
- it is older than the 30 days the History keeps close at hand;
- earlier reversals already took all of it back, or the amount asked is more than is left.
If the preview names a reason, the apply is refused and nothing changes.
Booking order lines that never got their components
Section titled “Booking order lines that never got their components”An open order line sometimes never reserved or used its components: its bill was inactive when the order came in, the order was never processed, or the order’s reservation counts the line without holding anything for it. The order coverage read tells you which lines these are. Booking reserves their components now, as if the order had been processed normally, so the line ships from them and nothing is taken twice.
The preview reads the order live from Shopify and shows, for each line and fulfilment order, how many units it would book: what the line still has to ship, minus what its reservations already hold. A line that is already partly reserved books only the rest, and a line booked once books nothing the second time. Units the order already used another way are never booked. Each line goes into the fulfilment order’s existing reservation, or into a new one when it has none.
Booking may take a component below zero even when your store does not allow negative inventory, because the order is already there and needs it. The preview names every component that would go below zero, with its stock before and after.
The preview names the reason when a line cannot be booked. The most common ones:
- the order already used its components for these units, or it cannot be told which of two lines of the same bill they belong to;
- the order was placed before you installed Assemblified, and the Open Shopify orders source of the Reservation backfill has not taken it: it cannot be booked here. Reserve it there instead, because only then do its cancellations, refunds and edits reach Assemblified;
- the line’s bill is not active, the line has nothing left to ship, or the fulfilment order’s reservation is already used up;
- the order is ignored because of a tag listed under Ignored order tags, so it gets no reservation;
- the order is handled by order production, or a cancelled fulfilment, a fulfilment or a refund of the order is still being processed: try again once it has landed.
If any line of a preview cannot be booked, the apply is refused and nothing changes: drop that line and preview again.
If a safety-stock reservation was holding components for an order you book, or for one you reserve through the Reservation backfill, lower that reservation afterwards with Edit on the bill’s Reservations tab (see Editing a reservation). The app never decides that for you: until you lower it, the reservation and the order both count when the assistant works out what to buy.
Returning or writing off reserved components
Section titled “Returning or writing off reserved components”The Reserved quantities tool on the raw materials list can also be used by the assistant, behind a preview. It takes the components an open order reservation still holds and either returns them to stock or writes them off. The reservation itself stays open and the order is still marked as having its components, so when the order ships nothing is taken twice.
The preview shows each reservation line with the stock before and after: a return puts the components back on sale, a write-off leaves the stock as it is. Pre-assembled lines are not handled this way: release the reservation instead, which puts them back on the shelf. If a previous attempt was interrupted after it started and before it finished, every apply for that reservation says so and changes nothing, whatever you change: open the Reserved quantities tool on the raw materials list, which checks the reserved stock in Shopify, and settle it there.
Reactivating a reservation whose hold was released
Section titled “Reactivating a reservation whose hold was released”When a fulfilment order is put on hold in Shopify, its order’s reservation is put on hold too and its components go back on sale. When the hold is released, the reservation becomes active again. If a reservation still shows as on hold while its fulfilment order is no longer on hold in Shopify, the assistant can reactivate it.
Reactivating does what a released hold does: the components the order still needs are reserved again at the same location, and the reservation becomes active. Nothing is returned to stock or written off, and the hold in Shopify is not changed. The assistant reads the fulfilment order from Shopify for the preview and again for the apply. The preview shows each component’s stock before and after, which may go below zero because the order already needs it.
The preview names the reason when a reservation cannot be reactivated. The most common ones:
- the reservation is not on hold;
- Shopify still holds the fulfilment order: releasing the hold in Shopify reactivates the reservation;
- the fulfilment order is closed or cancelled, the order was cancelled, or the fulfilment order is now assigned to another location;
- what an order line still needs changed during the hold, or a line was added to the fulfilment order after the reservation was made: book the lines or return the reserved components instead.
Saying how a variant is sold
Section titled “Saying how a variant is sold”Some of what you sell has no bill of materials on purpose: you buy it ready-made, or you build it outside the app and sell it from finished stock. The assistant can mark such a variant as sold from finished stock, or set it back to made from its recipe.
- Sold from finished stock: the variant leaves the Unmodelled sales report and the Unmodelled units on the Sales summary, because there is nothing left to model. When the assistant reads why an open order line was not booked, it says the line is sold from finished stock, and such a line is never booked. A variant whose bill is active cannot be marked: its orders are made from that recipe, so deactivate the bill first. An inactive bill stays as it is.
- Made from its recipe: the mark comes off, and if the variant has one bill and it is inactive, that bill is activated, exactly as switching it on in the bill’s settings does. A variant with several bills, none of them active, is not activated for you: switch on the one you mean first.
Setting the route books and releases nothing. When a recipe is switched on, the preview lists every open order line of the variant that still has to ship and has nothing reserved, each with the booking step that would reserve its components. Booking stays its own step, with its own preview. The preview reads every open order from Shopify, up to 2,500; with more open orders it says that it could not list them.
The repair record
Section titled “The repair record”The assistant can read the record of every repair it applied, newest first, filtered to one kind of repair or one repair by its id. Each entry says:
- which repair it was, who applied it, and when;
- the preview token and idempotency key it was applied with, and the answer it gave;
- the before and after of every stock level and consumption record it changed;
- the hold and reservation log entries and the settlement records it wrote, read back as they stand now;
- for a booking of order lines, what each retry with the same key did;
- every follow-up step it queued, such as a sync to a connected app, and where that step stands now: still queued, done, given up after its retries, or expired once the queue entry was cleaned up and its outcome is no longer known.
The record is permanent. Previews are not: they expire after 15 minutes and are cleaned up afterwards.