AyolShop

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

  1. Back up the database.

    TerminalCode
    npx wrangler d1 export <database> --remote --output backup-$(date +%Y%m%d).sql
  2. Get the code and install it.

    TerminalCode
    git pull npm ci (cd cod-astro/theme-00 && npm ci)
  3. See which migrations are new, and read their entries below:

    TerminalCode
    npx wrangler d1 migrations list <database> --remote
  4. Compare your configuration with the examples. A release may add a binding, a variable or a secret: diff cod-server/wrangler.toml with wrangler.toml.example, and cod-client-astro/wrangler.toml with its example. Remember the [env.production] copy of every binding.

  5. Migrate: npm run db:migrate:remote in cod-server.

  6. 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/config and a landing page's tracking no longer send conversionEvent; GET /store/orders/{id}/tracking adds eventId. A storefront needs @wocart/storefront 4: 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}/rates answers them by wilaya, and the company's page under Delivery shows them.
  • A carrier shipment keeps its shippingCost and returnFee from 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_wilayas and carrier_communes give way to carrier_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-geo is now …/sync-places; the capability geoNames is gone.
  • communes.postal_code is dropped: it was not a postal code. The commune API no longer sends postalCode.

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_media is rebuilt without its old key, keeping every row.

0076: a customer's totals are read from their orders

  • customers.total_orders, total_spent and last_order_at are dropped; the API still sends totalOrders, totalSpent and lastOrderAt, read from the orders. totalSpent now 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_history is dropped: an order's statusHistory (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/orders no longer sends lastUpdatedBy, and GET /api/customers/{id}/orders no longer sends each order's statusHistory.

0074: landing pages count nothing; one conversions path

  • landing_pages.views is dropped, and the landing-page API no longer sends views, orders, revenue or stats; GET /api/landing-pages/compare and the getLandingPageStats AI-agent tool are gone.
  • The old Meta conversions Workflow is gone: delete both CAPI_WORKFLOW [[workflows]] entries (top level and [env.production]) from cod-server/wrangler.toml before 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-activity names its money orderValue (it was sales); GET /api/analytics/order-stages adds deliveryRate; GET /api/abandoned-orders/stats sends only totalAbandoned and totalConverted.

0072–0073: storefront contract 3

  • /store/config no longer sends the store's colours, fonts, announcement, theme id, status, cartShippingMode or legalContact; it sends contact: { phone, email, address }. Product reads drop internal fields and send variantOptions and tags already parsed.
  • GET /store/products?featured=true is gone: use collection=featured.
  • Menu items may open search, order tracking and contact.
  • A storefront on @wocart/storefront 2.x cannot read this server. Theme-00 from this checkout is already on 3.0.0. A theme of your own moves to @wocart/storefront 3.0.0 and @wocart/theme 4.0.0 (Production and upgrades).

Review settings become an App (no migration)

  • The review rules leave GET/PATCH /api/stores/me for GET/PUT /api/apps/reviews (enabled, maxPhotos, voiceMaxSeconds, autoPublish), with the reviews:read and reviews:manage permissions.
  • status leaves /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_DELIVERY and MEDIA_ORIGIN (Media). Every file stored before this migration is on R2: keep them there with MEDIA_HOST = "r2" and the bucket's domain as MEDIA_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, set TELEGRAM_UPDATES_ORIGIN to 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_brand table 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 as wrangler.toml.example does. 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_featured becomes each store's featured collection, 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_url go: 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 theme01 take theme-00. Nothing else changes.

0043: review photos and voice notes

  • Set REVIEW_UPLOAD_SECRET, and add the REVIEW_MEDIA_WORKFLOW and REVIEW_RATE_LIMITER bindings. Without them, reviews are text only.
  • Run npm run r2:lifecycle once.

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 productId becomes null.
  • An order with a shipment can never be deleted, even in SQL (ORDER_HAS_SHIPMENT). Archive a finished one with POST /api/orders/{id}/archive; GET /api/orders/{id}/removal says which applies. A script that wipes orders must delete their shipments first.
  • GET /api/orders leaves archived orders out unless archived is 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.sql on the deployed database: every guard_* row must be 0, or the migration stops with nothing changed. After it, compare with cod-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.