Upgrading
An upgrade keeps every row your store has: migrations are written to run on a live store and to keep the running release working until the new one is deployed. What changes between releases is listed below, by the migration that brought it.
The order
-
Back up the database.
Code -
Get the code and install it.
Code -
See which migrations are new, and read their entries below:
Code -
Compare your configuration with the examples. A release may add a binding, a variable or a secret: diff
cod-server/wrangler.tomlwithwrangler.toml.example, andcod-client-astro/wrangler.tomlwith its example. Remember the[env.production]copy of every binding. -
Migrate:
npm run db:migrate:remoteincod-server. -
Deploy the API server, then the dashboard, then the storefront. A new dashboard calls routes only the new server has; a new storefront reads fields only the new server sends.
A storefront and its API move together
When a release changes what /store/* sends, a storefront built on an older
@wocart/storefront cannot read the new server. Deploy the storefront right
after the server, from the same checkout.
What each release asks of you
Newest first. Only the entries for migrations your database has not applied concern you.
Storefront contract 4 (no migration)
/store/configand a landing page'strackingno longer sendconversionEvent;GET /store/orders/{id}/trackingaddseventId. A storefront needs@wocart/storefront4: deploy it right after the server.
0079: what each carrier charges, and what each shipment cost
- A company's map of places also holds its prices for the merchant's account
(
home_rate,stop_desk_rate,home_return_fee,stop_desk_return_fee), read from its API with its places: ZR and Yalidine per commune, NOEST and EcoTrack per wilaya.GET /api/delivery-companies/{id}/ratesanswers them by wilaya, and the company's page under Delivery shows them. - A carrier shipment keeps its
shippingCostandreturnFeefrom the day it was handed off. Shipments handed off before this release have none. - A Yalidine read takes about a minute and a half: its prices come one wilaya at a time, paced under its quota of 50 calls a minute.
0078: Algeria's 69 wilayas; one map of places per carrier
- The wilayas and communes move to law 26-06 (2026): 69 wilayas, 1541
communes. Wilayas 59–69 are added; every commune is under its wilaya of
today, with corrected French and Arabic names; the ten placeholder copies
migration 0000 made of the 2019 capitals are merged into their communes.
A commune keeps its id when it moves (Besbes stays
c-07-007, in Ouled Djellal). - Every order, customer and abandoned checkout takes its commune's wilaya. Each new wilaya's shipping prices and drivers' fees start as those of the wilaya it was taken from, and a commune's price override follows the commune.
carrier_wilayasandcarrier_communesgive way tocarrier_places: each delivery company's own list of places, read from its API. Until a company's list is read, every order handed to it is refused (CARRIER_PLACES_NOT_READ). The hourly cron reads it within the hour of the upgrade; to read it at once, open the company under Delivery and choose "Read its places". An order to a commune the carrier does not list is refused by name (PLACE_NOT_SERVED) instead of being sent under a guessed name.POST /api/delivery-companies/{id}/sync-geois now…/sync-places; the capabilitygeoNamesis gone.communes.postal_codeis dropped: it was not a postal code. The commune API no longer sendspostalCode.
0077: unread columns dropped
- The store's old colours, font and
status, and the URLs and R2 keys images had before Media Keys (0068), are dropped; nothing read them.review_mediais rebuilt without its old key, keeping every row.
0076: a customer's totals are read from their orders
customers.total_orders,total_spentandlast_order_atare dropped; the API still sendstotalOrders,totalSpentandlastOrderAt, read from the orders.totalSpentnow counts only the goods of delivered orders, net of units refused at the door: it used to count an order from the moment it was placed.
0075: an order's timeline is its events
order_status_historyis dropped: an order'sstatusHistory(GET /api/orders/{id}) is read from its Business Events, with the name the event recorded. Orders from before 0059 have no events, so their timeline is empty.GET /api/ordersno longer sendslastUpdatedBy, andGET /api/customers/{id}/ordersno longer sends each order'sstatusHistory.
0074: landing pages count nothing; one conversions path
landing_pages.viewsis dropped, and the landing-page API no longer sendsviews,orders,revenueorstats;GET /api/landing-pages/compareand thegetLandingPageStatsAI-agent tool are gone.- The old Meta conversions Workflow is gone: delete both
CAPI_WORKFLOW[[workflows]]entries (top level and[env.production]) fromcod-server/wrangler.tomlbefore you deploy, or the deploy fails on a class the server no longer has. Conversions are sent by the Meta conversions Consumer, as they were since 0061. GET /api/analytics/order-activitynames its moneyorderValue(it wassales);GET /api/analytics/order-stagesaddsdeliveryRate;GET /api/abandoned-orders/statssends onlytotalAbandonedandtotalConverted.
0072–0073: storefront contract 3
/store/configno longer sends the store's colours, fonts, announcement, theme id,status,cartShippingModeorlegalContact; it sendscontact:{ phone, email, address }. Product reads drop internal fields and sendvariantOptionsandtagsalready parsed.GET /store/products?featured=trueis gone: usecollection=featured.- Menu items may open search, order tracking and contact.
- A storefront on
@wocart/storefront2.x cannot read this server. Theme-00 from this checkout is already on 3.0.0. A theme of your own moves to@wocart/storefront3.0.0 and@wocart/theme4.0.0 (Production and upgrades).
Review settings become an App (no migration)
- The review rules leave
GET/PATCH /api/stores/meforGET/PUT /api/apps/reviews(enabled,maxPhotos,voiceMaxSeconds,autoPublish), with thereviews:readandreviews:managepermissions. statusleaves/api/stores/me: it never had an effect.- Move scripts that called the old fields.
0071: landing page documents
- Additive: two triggers. Deleting a landing page now deletes its page
documents (
lp:<id>) and their drafts with it.
0069: customer email
- Additive:
customers.email, nullable. Existing customers start without one; it is not filled in from their past orders.
0068: media hosts
- The API server needs
MEDIA_HOST,MEDIA_DELIVERYandMEDIA_ORIGIN(Media). Every file stored before this migration is on R2: keep them there withMEDIA_HOST = "r2"and the bucket's domain asMEDIA_ORIGIN.
0067: Telegram
- Additive: a new table for the Telegram App. Telegram sends the bot's updates
to the API server's own origin (
WORKER_SELF_URL), so it must be public and https. On a local server, setTELEGRAM_UPDATES_ORIGINto an https tunnel.
0065–0066: Apps
- Meta tracking, DZVerify, Turnstile, Sendili and the WhatsApp button move to
/api/apps/<key>, each with its own read and manage permissions. 0065 gives every holder of an old permission its new ones; 0066 then removes the old ones. Nobody loses access. - Move scripts and API clients to the new paths.
0064: unused dashboard brand
- Drops the
dashboard_brandtable and its rows. Nothing ever displayed them, and the release before stopped reading it. Apply it only after that release is deployed.
0062–0063: signed carrier webhooks
- A Yalidine or ZR Express webhook is refused unless the company has its signing secret. The dashboard marks each company without one; add it as Carrier webhooks shows. Carriers retry a refused webhook for hours, so nothing is lost while you add it.
0059–0061: business events
- The API server needs the events queue, as producer and consumer: create it
(
npx wrangler queues create <name>) and declare it aswrangler.toml.exampledoes. A release that needs it does not work without it.
0056–0058: drivers and shipping labels
- A shipment given to the store's own driver is always home delivery with no
stop desk: the database refuses any other (
DRIVER_DELIVERS_HOME) for new writes. Shipments recorded before keep their values. A customer who chose a stop desk keeps that choice and its price on the order. - Shipping label settings for drivers are a new nullable column; nothing changes until a merchant saves them.
- A new index on drivers' shipments. No row changes.
0049–0055: collections, offers, coupons, theme drafts, product SEO
products.store_featuredbecomes each store'sfeaturedcollection, and the column goes. Menu items can point at a collection.- Offers gain quantity pricing, and the database checks every offer. A gift offer saved without a gift is repaired to give its own product and switched off, so review your offers after migrating. An offer whose end came before its start loses its end date and is switched off too.
- Coupons are new tables. Orders keep the name of the offer that shaped them.
- Page documents are kept per theme. A stored document that was not valid JSON, or named no known surface, could never be shown and is not carried over.
- Products gain an SEO title and description, empty until the merchant writes them.
0045–0048: theme settings and menus
- A store's colours and font become Theme-00's settings; each store's choice is
copied over, so storefronts look the same. The announcement bar and
stores.font_urlgo: a theme that shows an announcement declares it as a setting. - Navigation menus become store data, read by handle.
0044: theme label
- Stores still labelled
theme01taketheme-00. Nothing else changes.
0043: review photos and voice notes
- Set
REVIEW_UPLOAD_SECRET, and add theREVIEW_MEDIA_WORKFLOWandREVIEW_RATE_LIMITERbindings. Without them, reviews are text only. - Run
npm run r2:lifecycleonce.
0042: deleting products and orders
- Back up first: it rebuilds three log and line tables and drops
products.deleted_at. - Deleting a product is permanent; order lines keep its name and price, and
their
productIdbecomes null. - An order with a shipment can never be deleted, even in SQL
(
ORDER_HAS_SHIPMENT). Archive a finished one withPOST /api/orders/{id}/archive;GET /api/orders/{id}/removalsays which applies. A script that wipes orders must delete their shipments first. GET /api/ordersleaves archived orders out unlessarchivedis passed.- Deploy the API server, then the dashboard.
0038–0041: orders and shipments
- An order's delivery moves to its shipment. Before migrating, run
cod-server/scripts/preflight-0041.sqlon the deployed database: everyguard_*row must be 0, or the migration stops with nothing changed. After it, compare withcod-server/scripts/verify-0041.sql. - Add the five-minute schedule:
crons = ["0 * * * *", "*/5 * * * *"].
0035–0037: store languages
- These migrations drop columns once their data has moved. Back up first.