Wocart
Wocart API
Wocart API

Schemas

Download schema

OrderCreatedEvent

id
​string · required
sequence
​integer · required
type
​string · enum · required
Enum values:
order.created
version
​integer · required
​object · required
orderId
​string · required
occurredAt
​string · date-time · required
recordedAt
​string · date-time · required
​required
origin
​string · enum · required
Enum values:
dashboard
api
agent
storefront
carrier_webhook
carrier_sync
schedule
​object · required

OrderUpdatedEvent

id
​string · required
sequence
​integer · required
type
​string · enum · required
Enum values:
order.updated
version
​integer · required
​object · required
orderId
​string · required
occurredAt
​string · date-time · required
recordedAt
​string · date-time · required
​required
origin
​string · enum · required
Enum values:
dashboard
api
agent
storefront
carrier_webhook
carrier_sync
schedule
​object · required

OrderConfirmedEvent

id
​string · required
sequence
​integer · required
type
​string · enum · required
Enum values:
order.confirmed
version
​integer · required
​object · required
orderId
​string · required
occurredAt
​string · date-time · required
recordedAt
​string · date-time · required
​required
origin
​string · enum · required
Enum values:
dashboard
api
agent
storefront
carrier_webhook
carrier_sync
schedule
​object · required

OrderUnreachableEvent

id
​string · required
sequence
​integer · required
type
​string · enum · required
Enum values:
order.unreachable
version
​integer · required
​object · required
orderId
​string · required
occurredAt
​string · date-time · required
recordedAt
​string · date-time · required
​required
origin
​string · enum · required
Enum values:
dashboard
api
agent
storefront
carrier_webhook
carrier_sync
schedule
​object · required

OrderPreparingEvent

id
​string · required
sequence
​integer · required
type
​string · enum · required
Enum values:
order.preparing
version
​integer · required
​object · required
orderId
​string · required
occurredAt
​string · date-time · required
recordedAt
​string · date-time · required
​required
origin
​string · enum · required
Enum values:
dashboard
api
agent
storefront
carrier_webhook
carrier_sync
schedule
​object · required

OrderReadyEvent

id
​string · required
sequence
​integer · required
type
​string · enum · required
Enum values:
order.ready
version
​integer · required
​object · required
orderId
​string · required
occurredAt
​string · date-time · required
recordedAt
​string · date-time · required
​required
origin
​string · enum · required
Enum values:
dashboard
api
agent
storefront
carrier_webhook
carrier_sync
schedule
​object · required

OrderCancelledEvent

id
​string · required
sequence
​integer · required
type
​string · enum · required
Enum values:
order.cancelled
version
​integer · required
​object · required
orderId
​string · required
occurredAt
​string · date-time · required
recordedAt
​string · date-time · required
​required
origin
​string · enum · required
Enum values:
dashboard
api
agent
storefront
carrier_webhook
carrier_sync
schedule
​object · required

OrderLineReturnedEvent

id
​string · required
sequence
​integer · required
type
​string · enum · required
Enum values:
order.line_returned
version
​integer · required
​object · required
orderId
​string · required
occurredAt
​string · date-time · required
recordedAt
​string · date-time · required
​required
origin
​string · enum · required
Enum values:
dashboard
api
agent
storefront
carrier_webhook
carrier_sync
schedule
​object · required

OrderDeletedEvent

id
​string · required
sequence
​integer · required
type
​string · enum · required
Enum values:
order.deleted
version
​integer · required
​object · required
orderId
​string · required
occurredAt
​string · date-time · required
recordedAt
​string · date-time · required
​required
origin
​string · enum · required
Enum values:
dashboard
api
agent
storefront
carrier_webhook
carrier_sync
schedule
​object · required

ShipmentHandedOffEvent

id
​string · required
sequence
​integer · required
type
​string · enum · required
Enum values:
shipment.handed_off
version
​integer · required
​object · required
orderId
​string · required
occurredAt
​string · date-time · required
recordedAt
​string · date-time · required
​required
origin
​string · enum · required
Enum values:
dashboard
api
agent
storefront
carrier_webhook
carrier_sync
schedule
​object · required

ShipmentOutForDeliveryEvent

id
​string · required
sequence
​integer · required
type
​string · enum · required
Enum values:
shipment.out_for_delivery
version
​integer · required
​object · required
orderId
​string · required
occurredAt
​string · date-time · required
recordedAt
​string · date-time · required
​required
origin
​string · enum · required
Enum values:
dashboard
api
agent
storefront
carrier_webhook
carrier_sync
schedule
​object · required

ShipmentDeliveryFailedEvent

id
​string · required
sequence
​integer · required
type
​string · enum · required
Enum values:
shipment.delivery_failed
version
​integer · required
​object · required
orderId
​string · required
occurredAt
​string · date-time · required
recordedAt
​string · date-time · required
​required
origin
​string · enum · required
Enum values:
dashboard
api
agent
storefront
carrier_webhook
carrier_sync
schedule
​object · required

ShipmentDeliveredEvent

id
​string · required
sequence
​integer · required
type
​string · enum · required
Enum values:
shipment.delivered
version
​integer · required
​object · required
orderId
​string · required
occurredAt
​string · date-time · required
recordedAt
​string · date-time · required
​required
origin
​string · enum · required
Enum values:
dashboard
api
agent
storefront
carrier_webhook
carrier_sync
schedule
​object · required

ShipmentReturnStartedEvent

id
​string · required
sequence
​integer · required
type
​string · enum · required
Enum values:
shipment.return_started
version
​integer · required
​object · required
orderId
​string · required
occurredAt
​string · date-time · required
recordedAt
​string · date-time · required
​required
origin
​string · enum · required
Enum values:
dashboard
api
agent
storefront
carrier_webhook
carrier_sync
schedule
​object · required

ShipmentReturnedEvent

id
​string · required
sequence
​integer · required
type
​string · enum · required
Enum values:
shipment.returned
version
​integer · required
​object · required
orderId
​string · required
occurredAt
​string · date-time · required
recordedAt
​string · date-time · required
​required
origin
​string · enum · required
Enum values:
dashboard
api
agent
storefront
carrier_webhook
carrier_sync
schedule
​object · required

ShipmentCancelledEvent

id
​string · required
sequence
​integer · required
type
​string · enum · required
Enum values:
shipment.cancelled
version
​integer · required
​object · required
orderId
​string · required
occurredAt
​string · date-time · required
recordedAt
​string · date-time · required
​required
origin
​string · enum · required
Enum values:
dashboard
api
agent
storefront
carrier_webhook
carrier_sync
schedule
​object · required

ShipmentVoidedEvent

id
​string · required
sequence
​integer · required
type
​string · enum · required
Enum values:
shipment.voided
version
​integer · required
​object · required
orderId
​string · required
occurredAt
​string · date-time · required
recordedAt
​string · date-time · required
​required
origin
​string · enum · required
Enum values:
dashboard
api
agent
storefront
carrier_webhook
carrier_sync
schedule
​object · required

StoreConfig

id
​string · required

Store UUID

name
​string · required
domain
​string | null · required
logo
​MediaImage · required
lang
​string · enum · required

The store's primary language

Enum values:
ar
fr
en
locale
​string · enum · required

The language this config is served in: ?locale= when the store publishes it, else lang

Enum values:
ar
fr
en
​StorefrontLanguage[] · required

The published languages, primary first

​object · required

The requesting theme's text edits for the published languages; empty without theme

​object · required

The merchant's values for the requesting theme's settings, as saved, by setting key; empty without theme. The theme reads them against its declaration (resolveThemeSettings in @wocart/theme), which falls back to its defaults.

currency
​string · required
currencySymbol
​string · required
metaTitle
​string | null · required
metaDescription
​string | null · required
ogImage
​MediaImage · required
​MediaDelivery · required

How the storefront fetches and resizes every image key (ADR 0021)

reviewsEnabled
​boolean · required

When false, the reviews section is hidden on the storefront

cartEnabled
​boolean · required

When true the storefront renders the shopping cart alongside the direct order form. False (the default) leaves the storefront exactly as it was.

freeShippingThreshold
​integer | null · required

Order subtotal (DZD) at or above which delivery is free. null = no threshold. Exposed so the storefront can show the promise and how far the shopper is from it.

otpEnabled
​boolean · required

When true, storefront checkout requires WhatsApp phone verification (dzverify). True only when a store_otp_config row exists AND is enabled.

turnstileEnabled
​boolean · required

When true, storefront checkout requires a Cloudflare Turnstile token that the server verifies against siteverify. True only when a store_turnstile_config row exists AND is enabled.

turnstileSiteKey
​string | null · required

Public Turnstile widget site key for rendering the checkout widget. null when Turnstile is disabled. The siteverify secret key is never exposed.

​object[] · required

Published pages that opt into the footer, titled in the store's own language (stores.lang), ordered for display. The checkout consent line resolves Terms/Refund from here by kind, never by a hardcoded slug — a merchant may rename any page's slug freely.

​object · required

How a shopper reaches the store, from its legal profile (Settings → Store Pages); each null until the merchant writes it. RC, NIF and the legal name are never exposed here, only inside the documents themselves. The WhatsApp number is whatsapp.href.

​object · required

The merchant's order-form configuration, already resolved: a store that never customised it gets the defaults, which describe the form exactly as it behaved before this feature existed. The theme renders this and holds no form rules of its own — cod-server enforces every one of them on POST /store/orders, so a hidden field posted from an edge-cached page is dropped and a required one refuses the order. The raw stored column is never exposed.

whatsapp
​StoreWhatsAppWidget · required

The WhatsApp contact widget, already resolved — or null, which is what a store gets when the widget is off, has no number, or holds a number that no longer normalises. A theme's entire gate is this being non-null and the current surface being on in surfaces. The raw stored column is never exposed.

MediaImage

key
​string · minLength: 1 · maxLength: 512 · required

A Media Key: the image's identity in the store's media. Never a URL.

url
​string · uri · required

Where browsers fetch it, from the store's Media Delivery

width
​integer | null · required

Pixels, when known

height
​integer | null · required

Pixels, when known

StorefrontLanguage

code
​string · required

BCP 47 language tag

nativeName
​string · required

The language's name in itself

direction
​string · enum · required
Enum values:
rtl
ltr

MediaDelivery

How the storefront fetches and resizes every image key (ADR 0021)
kind
​string · enum · required

How images are resized: imagekit (?tr=), cloudflare (/cdn-cgi/image/), or direct (not resized)

Enum values:
imagekit
cloudflare
direct
origin
​string · uri · required

A key's URL is this origin, a slash and the key

StoreWhatsAppWidget

The WhatsApp contact widget, already resolved — or null, which is what a store gets when the widget is off, has no number, or holds a number that no longer normalises. A theme's entire gate is this being non-null and the current surface being on in `surfaces`. The raw stored column is never exposed.
href
​string · required

The wa.me link, ready to use. Digits only — a '+' in the path makes WhatsApp answer with an invalid-number page.

agentName
​string | null · required

Who the shopper is talking to. Null means the theme uses the store name.

caption
​string | null · required

The line under the name, e.g. how fast the merchant answers.

avatarUrl
​string | null · required

The avatar's URL, from the store's Media Delivery. Null means the theme falls back to the store logo.

welcomeMessage
​string | null · required

The bubble in the panel, before the shopper opens WhatsApp.

launcherLabel
​string | null · required

Text on the floating launcher.

ctaLabel
​string | null · required

The panel's button that opens WhatsApp.

prefillGeneral
​string | null · required

The message WhatsApp opens with on a page that has no product. May contain {url}, {order} and {store}, which the theme resolves from the page.

prefillProduct
​string | null · required

Same, for a product or landing page. May also contain {product}.

thankYouButtonLabel
​string | null · required

The WhatsApp button on the order confirmation.

prefillThankYou
​string | null · required

The message that button opens WhatsApp with. May contain {order}.

accent
​string · enum · required

Brand green, or the store's own primary colour.

Enum values:
whatsapp
primary
position
​string · enum · required

Which physical side the launcher sits on, in both LTR and RTL.

Enum values:
right
left
attention
​boolean · required

One attention pulse per session, suppressed under prefers-reduced-motion.

​object · required

Which kinds of page the launcher appears on. checkout and landing are off by default: both already carry their own sticky order CTA, and a second floating control competing for the same thumb costs the order.

StorefrontMenu

handle
​string · pattern: ^[a-z0-9][a-z0-9-]{0… · required

Lowercase letters, digits and hyphens; how a theme names the menu

title
​string · required
​StorefrontMenuItem[] · required

Only items a shopper can follow: one whose destination is deleted or not public is left out, with its children

StorefrontMenuItem

label
​string · required

In the requested language when the store translated it

href
​string · required

A path of the store without a language prefix (/products/robe), or the URL the merchant entered

type
​string · enum · required
Enum values:
home
catalog
search
trackOrder
contact
category
collection
product
​object[] · required

ErrorResponse

Standard error envelope returned by all non-2xx responses.
error
​string · required
code
​string · required
category
​string · enum · required
Enum values:
VALIDATION
AUTHENTICATION
BUSINESS_LOGIC
SYSTEM
​object

Additional context about the error (optional)

StorefrontCollection

handle
​string · pattern: ^[a-z0-9][a-z0-9-]{0… · required

Lowercase letters, digits and hyphens; how a theme names the collection

title
​string · required

In the requested language when the store translated it

description
​string | null · required
productCount
​integer · min: 0 · required

How many products a shopper sees in it

image
​StoreProductImage · required

The first photo of the first product it lists, in the merchant's order, that has one; null when none does

StoreProductImage

The first photo of the first product it lists, in the merchant's order, that has one; null when none does
key
​string · minLength: 1 · maxLength: 512 · required

A Media Key: the image's identity in the store's media. Never a URL.

url
​string · uri · required

Where browsers fetch it, from the store's Media Delivery

width
​integer | null · required

Pixels, when known

height
​integer | null · required

Pixels, when known

id
​string · required
altText
​string | null · required

Alt text for accessibility

position
​integer · min: 1 · required

Display order (1 = first)

StoreProductList

id
​string · required
name
​string · required
description
​string | null · required
descriptionFormat
​string · enum · required

How description is stored. text renders as literal text (legacy rows and products created without a format); html is sanitised rich text — render only via a strict HTML sink.

Enum values:
text
html
descriptionPlain
​string | null · required

Tag-free rendering of description for and JSON-LD. Identical to description for text rows; null when description is null.

handle
​string · required
currency
​string · required
price
​number · required
compareAtPrice
​number | null · required
type
​string · enum · required
Enum values:
PHYSICAL
DIGITAL
hasVariants
​boolean · required
sku
​string | null · required
inventory
​integer · required
trackInventory
​boolean · required
lowStockThreshold
​integer · required

Threshold for low stock warnings

categoryId
​string | null · required
metaTitle
​string | null · required

The title search engines and shared links show, in the requested language when translated; null: use the product's name.

metaDescription
​string | null · required

The description search engines and shared links show, in the requested language when translated; null: use descriptionPlain, shortened.

​array | null · required

Parsed variant option axes. null for simple products.

tags
​string[] · required

Parsed tag list

coverImage
​object | null · required

The first photo of the first product it lists, in the merchant's order, that has one; null when none does

reviewStats
​object | null · required

Aggregate review stats (approved reviews only). null if no approved reviews exist for this product.

StoreProductDetail

id
​string · required
name
​string · required
description
​string | null · required
descriptionFormat
​string · enum · required

How description is stored. text renders as literal text (legacy rows and products created without a format); html is sanitised rich text — render only via a strict HTML sink.

Enum values:
text
html
descriptionPlain
​string | null · required

Tag-free rendering of description for and JSON-LD. Identical to description for text rows; null when description is null.

handle
​string · required
currency
​string · required
price
​number · required
compareAtPrice
​number | null · required
type
​string · enum · required
Enum values:
PHYSICAL
DIGITAL
hasVariants
​boolean · required
sku
​string | null · required
inventory
​integer · required
trackInventory
​boolean · required
lowStockThreshold
​integer · required

Threshold for low stock warnings

categoryId
​string | null · required
metaTitle
​string | null · required

The title search engines and shared links show, in the requested language when translated; null: use the product's name.

metaDescription
​string | null · required

The description search engines and shared links show, in the requested language when translated; null: use descriptionPlain, shortened.

​array | null · required

Parsed variant option axes. null for simple products.

tags
​string[] · required

Parsed tag list

category
​object | null · required

Joined category, or null if no category assigned.

​object[] · required

Active variants ordered by position. Empty array for simple products.

images
​StoreProductImage[] · required

All product images ordered by position.

reviewStats
​object | null · required

Aggregate review stats (approved reviews only). null if no approved reviews exist for this product.

quantityPricing
​StoreQuantityPricing · required

The product's live quantity pricing — price tiers by quantity — or null. A separate field from offers (whose kinds published SDKs validate): the highest tier the quantity reaches prices every unit at its per-unit price; the cart quote and the order charge exactly that.

​object[] · required

Live Buy X Get Y and free-delivery offers for this product (quantity pricing is quantityPricing). Only includes offers where status=active and the current time is within the optional schedule window. The storefront uses this list to display offer banners and to show the free reward row in the order summary when the customer selects a matching variant and quantity.

StoreQuantityPricing

The product's live quantity pricing — price tiers by quantity — or null. A separate field from `offers` (whose kinds published SDKs validate): the highest tier the quantity reaches prices every unit at its per-unit price; the cart quote and the order charge exactly that.
offerId
​string · required
name
​string · required

The offer's name, in the requested language

triggerVariantId
​string | null · required

When set, only this variant's units count and are priced by the tiers

​object[] · required

In increasing quantity

StoreLandingPage

id
​string · required
slug
​string · required
name
​string · required
status
​string · enum · required
Enum values:
draft
published
archived
imageGap
​integer · required

Pixels between stacked images

metaTitle
​string | null · required
metaDescription
​string | null · required
publishedAt
​string | null · date-time · required
images
​(object | null)[] · required

The image stack, ordered by position (1 = top)

product
​object | null · required

The product in its full store-product shape — the landing page renders the same data the product page does, so the order form works unmodified. Null when the product is no longer publicly visible.

​PageDocument · required

This page's own composition (its lp:<id> page document) for the requesting theme, written by Wocart Cloud's editor; null when it has none or no theme is named — the theme then renders its landing default.

​StorePublicTracking · required

Which Meta pixel THIS page loads and fires at, already resolved server-side: the page's own pixel when it has one in force, otherwise the store's. The browser never works this out for itself, so it cannot disagree with the Conversions API mirror.

PageDocument

This page's own composition (its `lp:<id>` page document) for the requesting `theme`, written by Wocart Cloud's editor; null when it has none or no `theme` is named — the theme then renders its `landing` default.
version
​integer · required
surface
​string · required
​array · required
No data returned

StorePublicTracking

Which Meta pixel THIS page loads and fires at, already resolved server-side: the page's own pixel when it has one in force, otherwise the store's. The browser never works this out for itself, so it cannot disagree with the Conversions API mirror.
pixelId
​string | null · required

The Meta Pixel to load, or null when no pixel should load at all. Public by definition — it appears in the page source. The Conversions API token is never included.

conversionEvent
​string · enum · required

Which moment counts as a conversion here. Inert while pixelId is null.

Enum values:
Lead
Purchase
Purchase_Confirmed
Purchase_Delivered

StorePagePublic

id
​string · required
kind
​string · enum · required
Enum values:
terms
privacy
refund
shipping
custom
slug
​string · required
locale
​string · enum · required

The locale actually served — the store's own language, or the fallback locale when that translation doesn't exist (see legal/render.ts's resolution order).

Enum values:
ar
fr
en
title
​string · required
bodyHtml
​string · required

Sanitised HTML. Render with set:html and never re-sanitise.

metaTitle
​string | null · required
metaDescription
​string | null · required

StoreOrderTracking

pixelId
​string | null · required

The Meta pixel this order belongs to, or null when tracking is off.

event
​string | null · enum · required

The browser event the thank-you page should fire, or null when none should — tracking is off, or the merchant's conversion fires further down the funnel from the server only.

Enum values:
Purchase
Lead

ShopperOrderStatus

orderNumber
​string · required
placedAt
​string · required

When the order was placed (ISO 8601)

stage
​string · enum · required

Where the order is, in the shopper's words: placed (not confirmed yet), confirmed, preparing, shipped, out_for_delivery, delivered, returned (refused at the door) or cancelled.

Enum values:
placed
confirmed
preparing
shipped
out_for_delivery
delivered
returned
cancelled
deliveryType
​string · enum · required
Enum values:
home
stop_desk
​object[] · required
total
​number · required

What the shopper pays on delivery

tracking
​object | null · required

The carrier's tracking number once the parcel is with it; null before, or with the store's own driver

UploadTicket

mediaId
​string · required

Complete the upload with this id

key
​string · minLength: 1 · maxLength: 512 · required

A Media Key: the image's identity in the store's media. Never a URL.

expiresAt
​string · date-time · required
​required

How to send the file: form — POST multipart fields plus the file as fileField to url; put — PUT the bytes to url with exactly headers; relay — PUT the bytes to this server's url (a path) with headers.

ActivityLog

id
​string · required
actorId
​string · required
actorName
​string · required
actorRole
​string · enum · required
Enum values:
admin
staff
action
​string · required

Dot-notation action identifier. Valid values: order.created, order.status_changed, order.driver_assigned, order.dispatched, order.deleted, shipment.voided, shipment.released, customer.created, customer.updated, customer.deleted, customer_group.created, customer_group.updated, customer_group.deleted, customer_group.member_added, customer_group.member_removed, customer_tag.created, customer_tag.updated, customer_tag.deleted, customer_tag.assigned, customer_tag.unassigned, driver.created, driver.updated, driver.status_changed, driver.deleted, product.created, product.updated, product.status_changed, product.deleted, review.approved, review.rejected, review.deleted, user.created, user.updated, user.role_changed, user.scope_granted, user.scope_revoked, user.api_key_generated, user.api_key_revoked

entityType
​string · required

Entity category the action applies to. Valid values: order, customer, customer_group, customer_tag, driver, product, review, user

entityId
​string · required
entityLabel
​string | null · required

Human-readable label at the time of action (order number, customer name, etc.)

metadata
​string | null · required

JSON-encoded extra context. Shape varies by action: { from, to } for order.status_changed, { amount } for payments, { scope } for permission changes, { role } for role changes, { rating, orderNumber } for review actions

createdAt
​string · date-time · required

BusinessEvent

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: id, sequence, type +8 more
type = object · requires: id, sequence, type +8 more
type = object · requires: id, sequence, type +8 more
type = object · requires: id, sequence, type +8 more
type = object · requires: id, sequence, type +8 more
type = object · requires: id, sequence, type +8 more
type = object · requires: id, sequence, type +8 more
type = object · requires: id, sequence, type +8 more
type = object · requires: id, sequence, type +8 more
type = object · requires: id, sequence, type +8 more
type = object · requires: id, sequence, type +8 more
type = object · requires: id, sequence, type +8 more
type = object · requires: id, sequence, type +8 more
type = object · requires: id, sequence, type +8 more
type = object · requires: id, sequence, type +8 more
type = object · requires: id, sequence, type +8 more
type = object · requires: id, sequence, type +8 more
Properties for Variant 1:
id
​string · required
sequence
​integer · required
type
​string · enum · required
Enum values:
order.created
version
​integer · required
​object · required
orderId
​string · required
occurredAt
​string · date-time · required
recordedAt
​string · date-time · required
​required
origin
​string · enum · required
Enum values:
dashboard
api
agent
storefront
carrier_webhook
carrier_sync
schedule
​object · required

EventConsumer

id
​string · required
kind
​string · required

How it is reached: webhook (an endpoint of the merchant's own) or meta_capi (Meta conversions)

name
​string · required
enabled
​boolean · required
builtIn
​boolean · required

Kept by its App (Meta conversions, by the Meta App): it can be started and stopped, not edited or deleted

subscription
​string[] · required

The Event Types it receives, each named exactly, by subject (order.*), or *

catalogueVersion
​integer · required

The catalogue version its Deliveries are written in

disabledReason
​string | null · enum · required

Why it stopped receiving, while disabled: failing (every Attempt failed for 3 days), merchant, gone (its endpoint answered HTTP 410 Gone), bot_blocked (its Telegram chat blocked the bot), or not_connected (no Telegram chat connected yet)

Enum values:
failing
merchant
gone
bot_blocked
not_connected
failingSince
​string | null · required

Since when every Attempt has failed; null once one succeeds

​object · required
webhook
​object | null · required

A webhook Consumer's endpoint; null for any other kind

createdAt
​string · required
updatedAt
​string · required

WebhookCreated

​EventConsumer · required
signingSecret
​string · required

The Signing Secret, in full: shown this once. Verify Deliveries with it (Standard Webhooks)

MessageResponse

success
​boolean · required
message
​string · required

SigningSecret

signingSecret
​string · required

The Signing Secret, in full: shown this once. Verify Deliveries with it (Standard Webhooks)

previousSecretSignsUntil
​string · date-time · required

Until when Deliveries are also signed with the secret this one replaces

WebhookTest

​object · required
outcome
​string · enum · required

What a Delivery's Attempt would have come to

Enum values:
delivered
retry
reject
httpStatus
​integer | null · required
durationMs
​integer · required
response
​string | null · required

The start of what the endpoint answered

error
​string | null · required

Redelivery

reopened
​integer · required

Settled Deliveries made due again

created
​integer · required

Deliveries made for events the Consumer never had one for

EventDelivery

id
​string · required
consumerId
​string · required
state
​string · enum · required

due (on its way), delivered, skipped (declined on purpose) or dead (given up on)

Enum values:
due
delivered
skipped
dead
attempts
​integer · required

Attempts since it was last made due; a retry or Replay starts them over

nextAttemptAt
​string | null · required
lastError
​string | null · required
createdAt
​string · required
settledAt
​string | null · required
​object · required

EventDeliveryDetail

id
​string · required
consumerId
​string · required
state
​string · enum · required

due (on its way), delivered, skipped (declined on purpose) or dead (given up on)

Enum values:
due
delivered
skipped
dead
attempts
​integer · required

Attempts since it was last made due; a retry or Replay starts them over

nextAttemptAt
​string | null · required
lastError
​string | null · required
createdAt
​string · required
settledAt
​string | null · required
​object · required
​EventDeliveryAttempt[] · required

Every Attempt, oldest first — those before a retry or Replay too

EventDeliveryAttempt

attempt
​integer · required
attemptedAt
​string · required
durationMs
​integer · required
outcome
​string · enum · required
Enum values:
delivered
skipped
retry
reject
httpStatus
​integer | null · required
responseExcerpt
​string | null · required

The first kilobyte of what the Consumer answered

error
​string | null · required

OrderListItem

Order summary for list view - includes joins but not nested arrays
id
​string · required
orderNumber
​string · required
customerId
​string · required
customerName
​string · required
phone
​string · required
wilayaId
​integer | null · min: 1 · max: 58 · required
wilaya
​string | null · required

Wilaya Arabic name, joined from reference table

communeId
​string | null · required
commune
​string | null · required

Commune Arabic name, joined from reference table

city
​string | null · required
address
​string | null · required
price
​number · required

Product subtotal (excluding delivery fee)

deliveryFee
​number · required
codAmount
​number | null · required

What the customer owes on delivery: price + deliveryFee

status
​string · enum · required

The order's processing; its delivery is its shipment's (see stage)

Enum values:
new
confirmed
unreachable
preparing
ready
cancelled
orderType
​string · enum · required
Enum values:
online
offline
deliveryType
​string · enum · required

What the customer asked for; the shipment may ship otherwise

Enum values:
home
stop_desk
stationCode
​string | null · required
driverName
​string | null · required

The name of the store's driver delivering it, when its shipment is a driver's

notes
​string | null · required
landingPageId
​string | null · required

The landing page the order was placed on, if any

createdAt
​string · date-time · required
updatedAt
​string · date-time · required
archivedAt
​string | null · date-time · required

When the finished order was archived: it is left out of the working lists and their counts, and still counts in sales and the customer's history. Null while not archived.

deliveryOfferId
​string | null · required

The offer that made delivery free (a free-shipping offer, or a quantity tier that includes it); null when none did

deliveryOfferName
​string | null · required

That offer's name when the order was placed — kept when the offer is renamed or deleted

couponId
​string | null · required

The coupon the order was placed with; null when none, or once the coupon is deleted

couponCode
​string | null · required

The code the order used, kept when the coupon is deleted

couponDiscount
​integer · required

What the coupon took off; price is already net of it

locale
​string | null · enum · required

The language the order was placed in — the shopper's storefront language, the store's primary for a dashboard or agent order — and the one its customer messages are written in; null for an order placed before it was recorded

Enum values:
ar
fr
en
customerEmail
​string | null

Email supplied at order time

customFieldsJson
​string | null

Custom checkout fields snapshot JSON

hasReview
​integer

1 if a customer review exists for this order, 0 otherwise. Included in list responses only (GET /api/orders).

lastUpdatedBy
​string | null

User ID of the last status-change actor. Included in list responses only (GET /api/orders).

shipmentId
​string | null

The order's shipment, or null before handoff. List responses only.

shipmentKind
​string | null · enum

Handed to a carrier, or to the store's driver; null before handoff. List responses only.

Enum values:
carrier
driver
carrierName
​string | null

The delivery company carrying it, for a carrier shipment. List responses only.

trackingNumber
​string | null

The parcel's tracking number at the carrier. List responses only.

stage
​string · enum

Where the order stands overall — its processing, then its shipment's delivery. List responses only.

Enum values:
new
confirmed
unreachable
preparing
ready_to_ship
handoff_pending
in_transit
out_for_delivery
needsAttention
​boolean

Whether the order's delivery needs the merchant. List responses only.

Order

Complete order record with products and status history
id
​string · required
orderNumber
​string · required
customerId
​string · required
customerName
​string · required
phone
​string · required
wilayaId
​integer | null · min: 1 · max: 58 · required
wilaya
​string | null · required

Wilaya Arabic name, joined from reference table

communeId
​string | null · required
commune
​string | null · required

Commune Arabic name, joined from reference table

city
​string | null · required
address
​string | null · required
price
​number · required

Product subtotal (excluding delivery fee)

deliveryFee
​number · required
codAmount
​number | null · required

What the customer owes on delivery: price + deliveryFee

status
​string · enum · required

The order's processing; its delivery is its shipment's (see stage)

Enum values:
new
confirmed
unreachable
preparing
ready
cancelled
orderType
​string · enum · required
Enum values:
online
offline
deliveryType
​string · enum · required

What the customer asked for; the shipment may ship otherwise

Enum values:
home
stop_desk
stationCode
​string | null · required
driverName
​string | null · required

The name of the store's driver delivering it, when its shipment is a driver's

notes
​string | null · required
landingPageId
​string | null · required

The landing page the order was placed on, if any

createdAt
​string · date-time · required
updatedAt
​string · date-time · required
archivedAt
​string | null · date-time · required

When the finished order was archived: it is left out of the working lists and their counts, and still counts in sales and the customer's history. Null while not archived.

deliveryOfferId
​string | null · required

The offer that made delivery free (a free-shipping offer, or a quantity tier that includes it); null when none did

deliveryOfferName
​string | null · required

That offer's name when the order was placed — kept when the offer is renamed or deleted

couponId
​string | null · required

The coupon the order was placed with; null when none, or once the coupon is deleted

couponCode
​string | null · required

The code the order used, kept when the coupon is deleted

couponDiscount
​integer · required

What the coupon took off; price is already net of it

locale
​string | null · enum · required

The language the order was placed in — the shopper's storefront language, the store's primary for a dashboard or agent order — and the one its customer messages are written in; null for an order placed before it was recorded

Enum values:
ar
fr
en
customerEmail
​string | null

Email supplied at order time

customFieldsJson
​string | null

Custom checkout fields snapshot JSON

​OrderProduct[]

Order line items. Included in GET /api/orders/{id} (detail view only).

​StatusHistoryItem[]

Full status change log. Included in GET /api/orders/{id} (detail view only).

shipment
​object | null

The order's delivery, with its history and the actions available now; null before handoff. Detail view only.

stage
​string · enum

Where the order stands overall — its processing, then its shipment's delivery.

Enum values:
new
confirmed
unreachable
preparing
ready_to_ship
handoff_pending
in_transit
out_for_delivery
needsAttention
​boolean

The merchant must act on the delivery: the carrier flagged it, the handoff outcome is unknown, or the carrier cancelled it

OrderProduct

id
​string · required
orderId
​string · required
productId
​string | null · required

Null once the product was removed: the line keeps what was sold

productName
​string · required
variantId
​string | null · required

Null for a product without variants, or once the variant was removed

variantLabel
​string | null · required
sku
​string | null · required

Denormalized SKU at time of order

quantity
​integer · required
pricePerUnit
​number · required
lineTotal
​number · required
status
​string · enum · required

Per-line fulfilment outcome — updated via PATCH /orders/{id}/products/{productLineId}/return

Enum values:
fulfilled
partially_returned
returned
returnedQuantity
​integer · required

Units the customer refused at the door. Always 0 when status=fulfilled, = quantity when status=returned.

createdAt
​string · date-time · required
offerId
​string | null · required

The offer that shaped the line: the quantity-pricing offer that set its price, or the gift offer that gave it. Null at the catalog price.

offerName
​string | null · required

The offer's name when the order was placed — kept when the offer is renamed or deleted. Null without an offer.

reward
​boolean · required

A gift, given by offerId at no charge

discount
​integer · required

The line's share of the order's coupon discount; lineTotal is already net of it

StatusHistoryItem

id
​string · required
orderId
​string · required
status
​string · enum · required
Enum values:
new
confirmed
unreachable
preparing
ready
cancelled
timestamp
​string · date-time · required

When the status change happened

by
​string | null · required

User ID who triggered the status change

byName
​string | null · required

User display name

ShipmentEvent

id
​string · required
source
​string · enum · required
Enum values:
webhook
pull
handoff
merchant
system
legacy
vocabulary
​string | null · required

Whose words the status is in (the carrier's field, or codflow)

providerStatus
​string | null · required

The status exactly as reported

providerStatusLabel
​string | null · required
interpretation
​string | null · enum · required
Enum values:
milestone
failed_attempt
exception
collection
progress
unknown
milestone
​string | null · enum · required
Enum values:
out_for_delivery
delivered
return_started
returned
cancelled
attention
​boolean · required
anomaly
​string | null · required
reason
​string | null · required

Why, when the carrier says (a refusal, no answer…)

occurredAt
​string · required
recordedAt
​string · required
actorId
​string | null · required

OrderCreatedData

id
​string · required

Newly created order ID

orderNumber
​string · required
deliveryFee
​number · required

Calculated delivery fee (from shipping profile or admin override)

price
​number · required

Product subtotal (excluding delivery fee)

codAmount
​number · required

Total amount to collect (price + deliveryFee)

customerId
​string · required
customerName
​string · required
phone
​string · required
wilayaId
​integer · required
communeId
​string | null · required
deliveryType
​string · enum · required
Enum values:
home
stop_desk
orderType
​string · enum · required
Enum values:
online
offline
status
​string · required

Initial order status

OrderRemoval

id
​string · required
orderNumber
​string · required
shipment
​string · enum · required

No shipment yet, one on its way, or one that ended (delivered, returned, cancelled)

Enum values:
none
open
closed
deletable
​boolean · required

Only an order never handed to delivery

archivable
​boolean · required

A finished order (cancelled, or its shipment ended) not archived yet

archivedAt
​string | null · date-time · required
lines
​integer · required

Its order lines, removed with it

restockUnits
​integer · required

Units deleting it puts back in stock

reviews
​integer · required

Its reviews, removed with it

ReturnProductData

returnedQuantity
​integer · required
status
​string · enum · required
Enum values:
fulfilled
partially_returned
returned

HandoffResult

orderId
​string · required
orderNumber
​string | null · required
outcome
​string · enum · required

accepted: the carrier has the parcel, or the driver has the order · unknown: the carrier may or may not have it — resolve it, never re-send · refused: nothing was created; the order is unchanged

Enum values:
accepted
unknown
refused
​Shipment
validationError
​string | null

Created, but the carrier refused to validate it

message
​string
​object

Shipment

id
​string · required
orderId
​string · required
kind
​string · enum · required
Enum values:
carrier
driver
companyId
​string | null · required
carrierName
​string | null · required

The delivery company carrying it; null for the store's driver

driverId
​string | null · required
handoffState
​string · enum · required

submitting: the carrier is being called · accepted: the carrier has the parcel · unknown: the outcome must be resolved

Enum values:
submitting
accepted
unknown
carrierParcelId
​string | null · required
trackingNumber
​string | null · required
deliveryType
​string · enum · required
Enum values:
home
stop_desk
stationCode
​string | null · required
codAmount
​number · required

Cash the courier collects (price + delivery fee)

driverFee
​number · required
weight
​number | null · required
isFragile
​boolean | null · required
providerStatus
​string | null · required

The carrier's latest status, as reported

providerStatusLabel
​string | null · required
providerStatusKind
​string | null · enum · required
Enum values:
milestone
failed_attempt
exception
collection
progress
unknown
providerStatusAt
​string | null · required

UTC ISO-8601, or null

validatedAt
​string | null · required

UTC ISO-8601, or null

outForDeliveryAt
​string | null · required

UTC ISO-8601, or null

deliveredAt
​string | null · required

UTC ISO-8601, or null

returnStartedAt
​string | null · required

UTC ISO-8601, or null

returnedAt
​string | null · required

UTC ISO-8601, or null

cancelledAt
​string | null · required

UTC ISO-8601, or null

deliveryAttempts
​integer · required
attentionSince
​string | null · required

UTC ISO-8601, or null

lastSyncedAt
​string | null · required

UTC ISO-8601, or null

createdBy
​string | null · required
createdAt
​string · required
updatedAt
​string · required
actions
​string[] · required

What can be done to this shipment now

Enum values:
validate
update
void
resolve
lookup
addRemark
listRemarks
label

BulkHandoffData

​HandoffResult[] · required
​object · required

HandoffResolution

outcome
​string · enum · required
Enum values:
accepted
unknown
not_found
released
​Shipment
message
​string

ShipmentOperationResult

​Shipment · required
recorded
​integer

Events new to the shipment

duplicates
​integer

Events it already had

reached
​string[]

Milestones reached for the first time

Enum values:
out_for_delivery
delivered
return_started
returned
cancelled
anomalies
​string[]

CarrierRemark

content
​string · required
createdAt
​string | null · required

User

Team member record with permission scopes
id
​string · required
name
​string · required
email
​string · email · required
emailVerified
​boolean · required
image
​string | null · required

Avatar image URL

role
​string · enum · required
Enum values:
admin
staff
status
​string · enum · required
Enum values:
active
inactive
language
​string · required

UI language preference for emails: "ar" | "en"

createdAt
​string · date-time · required
updatedAt
​string · date-time · required
scopes
​string[] · required

Permission scopes for this user. Always ["*"] for admins. The apiKey field is never included in these responses — use POST /{id}/api-key/rotate for a one-time key reveal.

Customer

Customer profile with denormalized purchase statistics
id
​string · required
name
​string · required
phone
​string · required

Algerian mobile number starting with 05, 06, or 07

phone2
​string | null · required

Secondary phone number

email
​string | null · required

Email, lower-cased: typed by the merchant, or taken from the first order that brought one

wilayaId
​integer | null · min: 1 · max: 58 · required

Official wilaya number (1–58)

communeId
​string | null · required

Commune UUID from reference table

wilaya
​string · required

Wilaya Arabic name — denormalized display value, derived from wilayaId

commune
​string | null · required

Commune Arabic name — denormalized display value, derived from communeId

address
​string | null · required
totalOrders
​integer · required

Denormalized count, incremented on each order created

totalSpent
​number · required
createdAt
​string · date-time · required
lastOrderAt
​string | null · date-time · required
​object[]

Up to 10 most recent full order records (same shape as the Orders API), newest first. Included only in GET /api/customers/{id}; not present in list responses.

CustomerOrderSummary

Order summary returned by GET /api/customers/{id}/orders, each with its full statusHistory
id
​string · required
orderNumber
​string · required
status
​string · required
price
​number · required
createdAt
​string · date-time · required
wilayaId
​integer | null · required
communeId
​string | null · required
wilaya
​string | null · required

Wilaya Arabic name, joined from reference table

commune
​string | null · required

Commune Arabic name, joined from reference table

stage
​string · enum · required

Where the order stands overall — delivered, returned… (the same stage as GET /api/orders)

Enum values:
new
confirmed
unreachable
preparing
ready_to_ship
handoff_pending
in_transit
out_for_delivery
​CustomerOrderStatus[] · required

CustomerOrderStatus

id
​string · required
orderId
​string · required
status
​string · required
timestamp
​string · date-time · required
by
​string | null · required

CustomerGroupMembership

id
​string · required
name
​string · required
color
​string · required
description
​string | null · required
memberCount
​integer · required
createdAt
​string · date-time · required
updatedAt
​string · date-time · required
assignedAt
​string · date-time · required

When the customer was added to this group

CustomerTagMembership

id
​string · required
name
​string · required
color
​string · required
assignmentCount
​integer · required
createdAt
​string · date-time · required
updatedAt
​string · date-time · required
assignedAt
​string · date-time · required

When the tag was assigned to this customer

CustomerGroup

Group for segmenting customers
id
​string · required
name
​string · required
description
​string | null · required
color
​string · required
memberCount
​integer · required

Denormalized count, kept in sync on add/remove member

createdAt
​string · date-time · required
updatedAt
​string · date-time · required

Included only when ?members=true is passed to GET /api/customer-groups/{id}.

CustomerGroupMember

id
​string · required
name
​string · required
phone
​string · required
wilaya
​string | null · required
totalOrders
​integer · required
totalSpent
​number · required
assignedAt
​string · date-time · required

CustomerTag

Label for tagging customers
id
​string · required
name
​string · required
color
​string · required
assignmentCount
​integer · required

Denormalized count, kept in sync on assign/unassign

createdAt
​string · date-time · required
updatedAt
​string · date-time · required

Included only when ?customers=true is passed to GET /api/customer-tags/{id}.

CustomerTagCustomer

id
​string · required
name
​string · required
phone
​string · required
wilaya
​string | null · required
totalOrders
​integer · required
totalSpent
​number · required
assignedAt
​string · date-time · required

Driver

Delivery driver profile with denormalized earnings statistics
id
​string · required
firstName
​string · required
lastName
​string · required
phone
​string · required

Algerian mobile number starting with 05, 06, or 07

phone2
​string | null · required

Optional secondary phone

vehicleType
​string | null · enum · required

Type of vehicle; null if unknown

Enum values:
motorcycle
car
van
status
​string · enum · required
Enum values:
available
busy
inactive
totalDelivered
​integer · required

Cumulative deliveries completed (incremented on status → delivered)

totalEarnings
​number · required

Cumulative delivery fees earned (incremented on status → delivered)

pendingCash
​number · required

COD cash collected by driver but not yet remitted to the business

totalPaid
​number · required

Total COD cash remitted to the business

notes
​string | null · required

Internal notes about the driver (not visible to customers)

createdAt
​string · date-time · required
updatedAt
​string · date-time · required
compensationWilayaCount
​integer · required

Number of wilayas with a configured per-delivery fee for this driver

​object[]

The 10 most recent orders given to this driver, newest first. Detail, create and update responses only.

openShipmentCount
​integer

Orders the driver still has out (not delivered, returned or cancelled).

​object

DriverCompensationRow

Per-wilaya compensation entry. GET /{id}/compensations always returns all 58 wilayas; a null fee means no row is configured.
wilayaId
​integer · min: 1 · max: 58 · required
wilayaName
​string · required
wilayaNameAr
​string · required
feePerDelivery
​number | null · required

DZD per delivery; null when not configured.

DeliveryCompany

Third-party delivery company integration
id
​string · required
name
​string · required
nameAr
​string · required
code
​string · required
website
​string | null · uri · required
active
​boolean · required
apiEndpoint
​string | null · uri · required
isConnected
​boolean · required

True when API credentials are stored. Credentials themselves are never returned.

supportsHomeDelivery
​boolean · required
supportsStopDesk
​boolean · required
autoValidate
​boolean | null · required

When true, the server calls validateShipment immediately after createShipment on dispatch. The order is locked at the carrier (no edits/deletes). When false, the order stays editable and the team must manually confirm it. If omitted/null, a provider-specific default is used.

notes
​string | null · required
provider
​string | null · enum · required

The carrier adapter serving this company; null = it cannot take parcels.

Enum values:
yalidine
zr_express
noest
ecotrack
​object | null · required

The adapter's settings; secrets masked (•••• + last 4).

webhookSecretSet
​boolean · required

True when the webhook signing secret is stored. The secret itself is never returned.

capabilities
​CarrierCapabilities · required

What its carrier can do; null when it has no provider

webhookEndpointId
​string | null · required
createdAt
​string · date-time · required
updatedAt
​string · date-time · required

CarrierCapabilities

What its carrier can do; null when it has no provider
homeDelivery
​boolean · required
stopDesk
​boolean · required
separateValidation
​boolean · required

A created parcel waits for a separate validation before the carrier handles it

bulkCreate
​integer · required

Most parcels one bulk handoff sends at once; 0 = one at a time

​object · required

Parcel fields the carrier takes at creation

​object · required

The carrier's own ceilings, checked before calling it

update
​boolean · required
cancel
​boolean · required
​object · required
history
​boolean · required

Its status history can be read (sync)

historyBatch
​integer · required
findByReference
​boolean · required

A parcel can be found by the order number — resolves an unknown handoff

updates
​string · enum · required

How its updates reach Wocart: pushed by webhook, or pulled every few minutes

Enum values:
webhook
pull
label
​boolean · required
askReturn
​boolean · required
requestNewAttempt
​boolean · required
confirmReturn
​boolean · required
stopDeskList
​boolean · required
geoNames
​boolean · required
verifyConnection
​boolean · required

StopDesk

id
​string · required
companyId
​string · required
code
​string · required

Station code to use as stationCode when dispatching a stop-desk order. Format differs by provider: Noest = alphanumeric code (e.g. "16A"); Yalidine = numeric center_id (e.g. "160101"); ZR Express = territory UUID; EcoTrack = postal code string.

name
​string · required
commune
​string | null · required
wilayaId
​integer | null · required
address
​string | null · required
phones
​string[] · required

Contact phone numbers for the stop-desk station.

active
​boolean · required

Admin toggle. When false, this stop desk is hidden from merchant UI. Survives re-sync.

syncedAt
​string · date-time · required

Last time this row was fetched from the carrier API (via POST .../sync-stop-desks).

Product

id
​string · required
name
​string · required
description
​string | null · required
descriptionFormat
​string · enum · required

How description is stored. text renders as literal text (legacy rows and products created without a format); html was sanitised at write against the rich-text allow-list.

Enum values:
text
html
descriptionPlain
​string | null · required

Tag-free rendering of description for meta/JSON-LD (tags stripped, images dropped, entities decoded, whitespace collapsed). Identical to description for text rows; null when description is null.

handle
​string · required

URL slug — auto-generated from name if not provided

currency
​string · required
price
​integer · min: 0 · required

Price in DZD (smallest unit)

compareAtPrice
​integer | null · min: 0 · required
costPrice
​integer | null · min: 0 · required
type
​string · enum · required
Enum values:
PHYSICAL
DIGITAL
hasVariants
​boolean · required
​array | null · required

Variant option axes. Parsed from JSON storage — null when the product has no options.

sku
​string | null · required

Only used by simple products (hasVariants=false); variant products carry SKU on each variant.

inventory
​integer · min: 0 · required

Stock for simple products; ignored for variant products.

lowStockThreshold
​integer · min: 0 · required

Alert when stock drops to this level. Ignored for variant products (threshold is per-variant).

trackInventory
​boolean · required
categoryId
​string | null · required
tags
​string[] · required

Parsed from JSON storage.

visibility
​boolean · required
status
​string · enum · required
Enum values:
DRAFT
ACTIVE
ARCHIVED
showInStore
​boolean · required
publishedAt
​string | null · date-time · required

Auto-set when status changes to ACTIVE

shippingProfileId
​string | null · required

Shipping profile ID for this product. Null = store default profile is used.

createdAt
​string · date-time · required
updatedAt
​string · date-time · required
metaTitle
​string | null · required

Search-engine title (60 characters at most); null: the product's name

metaDescription
​string | null · required

Search-engine description (160 characters at most); null: the product's description, shortened

variantsCount
​integer · required

Number of variants attached to this product

totalInventory
​integer · required

Sum of variant inventory for variant products; product.inventory for simple products

​ProductVariant[] · required

Variants ordered by position; variations are parsed into objects

primaryImage
​object | null

The gallery's first image. Included in list responses only.

reviewCount
​integer

Approved review count. Included in list responses only.

avgRating
​number | null

Average approved rating (1 decimal), null when unreviewed. Included in list responses only.

category
​object | null

Full category record. Included only in GET /{id} detail responses.

Images ordered by position. Included only in GET /{id} detail and mutation responses.

ProductVariant

id
​string · required
productId
​string · required
​object · required

Key-value map matching the product's variantOptions axes

currency
​string · required
price
​integer · min: 0 · required

Price in DZD

compareAtPrice
​integer | null · min: 0 · required
sku
​string · required

Unique stock-keeping unit identifier. Used for order tracking and inventory management.

barcode
​string | null · required
inventory
​integer · min: 0 · required
lowStockThreshold
​integer · min: 0 · required

Alert when this variant's stock drops to this level.

weightKg
​number | null · min: 0 · required
imageId
​string | null · required

Product image ID associated with this variant

isDefault
​boolean · required
active
​boolean · required
position
​integer · min: 1 · required
createdAt
​string · date-time · required
updatedAt
​string · date-time · required

ProductImage

id
​string · required
productId
​string · required
key
​string · minLength: 1 · maxLength: 512 · required

A Media Key: the image's identity in the store's media. Never a URL.

url
​string · uri · required

Where browsers fetch it, from the store's Media Delivery

width
​integer | null · required
height
​integer | null · required
altText
​string | null · required

Alt text for accessibility

position
​integer · min: 1 · required

Display order (1 = first)

createdAt
​string · date-time · required
updatedAt
​string · date-time · required

ProductDetail

id
​string · required
name
​string · required
description
​string | null · required
descriptionFormat
​string · enum · required

How description is stored. text renders as literal text (legacy rows and products created without a format); html was sanitised at write against the rich-text allow-list.

Enum values:
text
html
descriptionPlain
​string | null · required

Tag-free rendering of description for meta/JSON-LD (tags stripped, images dropped, entities decoded, whitespace collapsed). Identical to description for text rows; null when description is null.

handle
​string · required

URL slug — auto-generated from name if not provided

currency
​string · required
price
​integer · min: 0 · required

Price in DZD (smallest unit)

compareAtPrice
​integer | null · min: 0 · required
costPrice
​integer | null · min: 0 · required
type
​string · enum · required
Enum values:
PHYSICAL
DIGITAL
hasVariants
​boolean · required
​array | null · required

Variant option axes. Parsed from JSON storage — null when the product has no options.

sku
​string | null · required

Only used by simple products (hasVariants=false); variant products carry SKU on each variant.

inventory
​integer · min: 0 · required

Stock for simple products; ignored for variant products.

lowStockThreshold
​integer · min: 0 · required

Alert when stock drops to this level. Ignored for variant products (threshold is per-variant).

trackInventory
​boolean · required
categoryId
​string | null · required
tags
​string[] · required

Parsed from JSON storage.

visibility
​boolean · required
status
​string · enum · required
Enum values:
DRAFT
ACTIVE
ARCHIVED
showInStore
​boolean · required
publishedAt
​string | null · date-time · required

Auto-set when status changes to ACTIVE

shippingProfileId
​string | null · required

Shipping profile ID for this product. Null = store default profile is used.

createdAt
​string · date-time · required
updatedAt
​string · date-time · required
metaTitle
​string | null · required

Search-engine title (60 characters at most); null: the product's name

metaDescription
​string | null · required

Search-engine description (160 characters at most); null: the product's description, shortened

variantsCount
​integer · required

Number of variants attached to this product

totalInventory
​integer · required

Sum of variant inventory for variant products; product.inventory for simple products

​ProductVariant[] · required

Variants ordered by position; variations are parsed into objects

collectionIds
​string[] · required

The collections the product is in (curated lists such as featured or best-sellers)

primaryImage
​object | null

The gallery's first image. Included in list responses only.

reviewCount
​integer

Approved review count. Included in list responses only.

avgRating
​number | null

Average approved rating (1 decimal), null when unreviewed. Included in list responses only.

category
​object | null

Full category record. Included only in GET /{id} detail responses.

Images ordered by position. Included only in GET /{id} detail and mutation responses.

ProductRemoval

id
​string · required
name
​string · required
variants
​integer · required
images
​integer · required
reviews
​integer · required
offers
​integer · required

Offers it triggers or rewards: removed with it

landingPages
​integer · required

Its landing pages, with their images and pixel settings: removed with it

landingPageOrders
​integer · required

Orders those landing pages brought: kept, without the landing page link

orderLines
​integer · required

Order lines that sold it: kept as sold, without the product link

ordersToShip
​integer · required

Orders holding it not handed to delivery yet: they keep the line, which is never put back in stock

ProductCategory

Product category/collection group in the catalog hierarchy
id
​string · required
name
​string · required
slug
​string · required

Lowercase letters, numbers and hyphens; auto-generated from name with a unique suffix when omitted

description
​string | null · required
parentId
​string | null · required

Parent group ID for nested hierarchies; null for top-level groups

image
​object | null · required

The group's image, from its Media Key

metaTitle
​string | null · required

SEO page title (max 60 chars)

metaDescription
​string | null · required

SEO description (max 160 chars)

metaKeywords
​string | null · required

Comma-separated SEO keywords

position
​integer · min: 0 · required

Display order; lower values come first

createdAt
​string · date-time · required
updatedAt
​string · date-time · required
productsCount
​integer · required

Number of active (non-deleted) products assigned to this group

​object[]

Immediate sub-categories. Included only in GET /api/product-groups/{id}.

LandingPageListItem

id
​string · required
slug
​string · required
name
​string · required
status
​string · enum · required
Enum values:
draft
published
archived
productId
​string · required
productName
​string | null · required
productHandle
​string | null · required
imageCount
​integer · min: 0 · required
views
​integer · min: 0 · required
orders
​integer · min: 0 · required
revenue
​number · min: 0 · required
publicUrl
​string · required

The shareable storefront URL for this page

publishedAt
​string | null · date-time · required
createdAt
​string · date-time · required
updatedAt
​string · date-time · required
tracking
​object | null · required

This page's own pixel, or null when it inherits the store's. Enough to badge a list row; the access token is never included. Whether it is actually in force also depends on the store's per-page tracking switch.

LandingPage

id
​string · required
slug
​string · required

Public URL identifier — /lp/

name
​string · required

Internal label, never rendered publicly

productId
​string · required
status
​string · enum · required

draft → published → archived. Only published pages resolve publicly.

Enum values:
draft
published
archived
imageGap
​integer · min: 0 · max: 200 · required

Pixels between stacked images — the only spacing setting

metaTitle
​string | null · required
metaDescription
​string | null · required
views
​integer · min: 0 · required
publicUrl
​string · required

The shareable storefront URL (from the store's domain, or the deployment's storefront fallback; relative /lp/ when neither is set)

publishedAt
​string | null · date-time · required
createdAt
​string · date-time · required
updatedAt
​string · date-time · required
​LandingPageImage[] · required

The image stack, ordered by position (1 = top)

product
​object | null · required

The single product this page sells

​LandingPageStats · required

LandingPageImage

id
​string · required
landingPageId
​string · required
key
​string · minLength: 1 · maxLength: 512 · required

A Media Key: the image's identity in the store's media. Never a URL.

url
​string · uri · required

Where browsers fetch it, from the store's Media Delivery

altText
​string | null · required

Alt text for accessibility

source
​string · enum · required

How the image entered the stack (AI generation is a future phase)

Enum values:
upload
ai
position
​integer · min: 1 · required

Stack order (1 = top of the page)

width
​integer | null · required

Intrinsic pixel width — the storefront reserves this space to prevent layout shift; null on legacy rows

height
​integer | null · required

Intrinsic pixel height — the storefront reserves this space to prevent layout shift; null on legacy rows

createdAt
​string · date-time · required

LandingPageStats

views
​integer · min: 0 · required
orders
​integer · min: 0 · required
revenue
​number · min: 0 · required

Sum of attributed order prices in DZD

LandingPageTrackingState

config
​LandingPageTracking · required

The page's own pixel, or null when it inherits the store's.

lastEvent
​LandingPageTrackingActivity · required

The last Conversions API attempt for this page, or null when there has been none.

LandingPageTracking

The page's own pixel, or null when it inherits the store's.
id
​string · required
landingPageId
​string · required
pixelId
​string · required

The Meta Pixel this page reports to. Public by definition — it appears in the page source.

adAccountName
​string | null · required

The merchant's own label for the ad account. Reference only, never sent to Meta.

accessTokenMasked
​string · required

Last four characters of the stored Conversions API token. The token itself never leaves the server.

testEventCode
​string | null · required
conversionEvent
​string · enum · required

Which moment counts as a conversion for THIS page's campaigns — independent of the store's choice.

Enum values:
Lead
Purchase
Purchase_Confirmed
Purchase_Delivered
testMode
​boolean · required
enabled
​boolean · required

Switched off returns the page to the store pixel without losing what was configured.

createdAt
​string · date-time · required
updatedAt
​string · date-time · required

LandingPageTrackingActivity

The last Conversions API attempt for this page, or null when there has been none.
eventName
​string · required
stage
​string · required

Which business moment produced it: checkout, confirmed, or delivered.

status
​string · required

sent | failed | skipped | claimed

pixelId
​string | null · required

Which pixel it went to. Null only for rows written before this was recorded.

error
​string | null · required

Meta's own message when the attempt failed.

sentAt
​string · required

StorePageSummary

id
​string · required
kind
​string · enum · required
Enum values:
terms
privacy
refund
shipping
custom
slug
​string · required

Public URL segment — /pages/

status
​string · enum · required
Enum values:
published
draft
showInFooter
​boolean · required
position
​integer · required
templateVersion
​integer | null · required

Which template revision this page's prose was last seeded/reset from. Null for custom pages.

createdAt
​string · date-time · required
updatedAt
​string · date-time · required
​StorePageTranslationSummary[] · required

StorePageTranslationSummary

locale
​string · enum · required
Enum values:
ar
fr
en
title
​string · required
source
​string · enum · required

'template' = still the seeded text, never reviewed. 'merchant' = edited at least once.

Enum values:
template
merchant
updatedAt
​string · date-time · required

StoreLegalProfile

storeId
​string · required
legalName
​string | null · required
rcNumber
​string | null · required

Registre de Commerce number

nif
​string | null · required

Numéro d'Identification Fiscale

address
​string | null · required
contactEmail
​string | null · required
contactPhone
​string | null · required
returnWindowDays
​integer · min: 0 · required

0 = no post-delivery return window offered; the refund page's return clause is dropped.

deliveryMinDays
​integer · min: 0 · required
deliveryMaxDays
​integer · min: 0 · required
updatedAt
​string · date-time · required

StorePageDetail

id
​string · required
kind
​string · enum · required
Enum values:
terms
privacy
refund
shipping
custom
slug
​string · required

Public URL segment — /pages/

status
​string · enum · required
Enum values:
published
draft
showInFooter
​boolean · required
position
​integer · required
templateVersion
​integer | null · required

Which template revision this page's prose was last seeded/reset from. Null for custom pages.

createdAt
​string · date-time · required
updatedAt
​string · date-time · required
​StorePageTranslationSummary[] · required
​object · required

Full body per locale. A locale never saved is absent, not null.

StorePageTranslationBody

pageId
​string · required
locale
​string · enum · required
Enum values:
ar
fr
en
title
​string · required
bodyHtml
​string · required

Sanitised HTML — h2/p/strong/ul/li/etc. Render with set:html, never re-sanitise.

bodyPlain
​string · required
metaTitle
​string | null · required
metaDescription
​string | null · required
source
​string · enum · required
Enum values:
template
merchant
updatedAt
​string · date-time · required

MenuSummary

id
​string · required
handle
​string · pattern: ^[a-z0-9][a-z0-9-]{0… · required

Lowercase letters, digits and hyphens; how a theme names the menu

title
​string · required
itemCount
​integer · required
updatedAt
​string · required

MenuDestinationOption

id
​string · required
label
​string · required
path
​string · required

Its public path

visible
​boolean · required

False when shoppers cannot see it now: an item pointing at it is left out of the menu

MenuDetail

id
​string · required
handle
​string · pattern: ^[a-z0-9][a-z0-9-]{0… · required

Lowercase letters, digits and hyphens; how a theme names the menu

title
​string · required
updatedAt
​string · required
​MenuItem[] · required

MenuItem

id
​string · required
label
​string · required
​MenuDestination · required
destinationStatus
​string · enum · required

missing: the destination was deleted. hidden: it exists but shoppers cannot see it (a draft page, an inactive product). Either way the storefront leaves the item out.

Enum values:
ok
missing
hidden
destinationLabel
​string | null · required

The destination's name (a product's or category's name, a page's slug)

​object[] · required

MenuDestination

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: type
type = object · requires: type, ref
type = object · requires: type, url
Properties for Variant 1:
type
​string · enum · required

A page of the store: the home, every product, search, order tracking or contact

Enum values:
home
catalog
search
trackOrder
contact

MenuItemInput

label
​string · minLength: 1 · maxLength: 100 · required
​MenuDestination · required
id
​string · minLength: 1 · maxLength: 100

An existing item's id, to keep it (and its translations)

​object[]

CollectionSummary

id
​string · required
handle
​string · pattern: ^[a-z0-9][a-z0-9-]{0… · required

Lowercase letters, digits and hyphens; how a theme names the collection

title
​string · required
productCount
​integer · required
updatedAt
​string · required

CollectionDetail

id
​string · required
handle
​string · pattern: ^[a-z0-9][a-z0-9-]{0… · required

Lowercase letters, digits and hyphens; how a theme names the collection

title
​string · required
description
​string | null · required
updatedAt
​string · required
​object[] · required

CheckoutFormPolicy

address
​string · enum · required

Home delivery only. Hidden is allowed; the dispatch guard ensures a home parcel has an address before leaving.

Enum values:
required
optional
hidden
notes
​string · enum · required
Enum values:
optional
hidden
email
​string · enum · required

Defaults to hidden, which is the storefront's behaviour before this feature. Stored on the order (orders.customer_email) when the shopper supplies one.

Enum values:
required
optional
hidden
​object · required

At least one must stay on — a form with neither cannot be submitted.

​CheckoutFormCustomField[] · maxItems: 5 · required

CheckoutFormCustomField

label
​string · minLength: 1 · maxLength: 60 · required
type
​string · enum · required
Enum values:
text
textarea
number
select
id
​string · pattern: ^cf_[a-z0-9]{8}$

Server-minted id. Omit it to create a field; send it to edit the field it names. An id the store does not already have is rejected — ids key the answer snapshots on existing orders.

required
​boolean
options
​string[] · minItems: 1 · maxItems: 20

Dropdown choices — select only, and required for it.

CheckoutFormPolicyInput

A policy document. Same shape as CheckoutFormPolicy, with `customFields[].id` optional (omit it to create a field). Validated server-side by the policy module: unknown keys, an empty delivery-option pair, an unknown field id and every authoring limit are refused, with each problem listed in `context.issues`.
No data returned

App

key
​string · enum · required

The App Key: its name in URLs, the API and permissions

Enum values:
meta
dzverify
turnstile
sendili
whatsapp-button
telegram
reviews
category
​string · enum · required
Enum values:
marketing
checkout_protection
messaging
storefront
status
​string · enum · required

not_set_up | on | off | needs_attention (on, but what it sends is failing, or it cannot do what it is on for)

Enum values:
not_set_up
on
off
needs_attention

StorePixelConfig

Meta pixel tracking configuration for server-side conversion events
id
​string · required
storeId
​string · required
pixelId
​string · required
adAccountName
​string | null · required

Merchant's own label for the Meta ad account — reference only, never sent to Meta.

accessTokenMasked
​string · required

Masked hint of the stored Meta access token — the token itself is write-only.

testEventCode
​string | null · required

Meta test event code — used only while Test Mode is on. Set to null in production.

conversionEvent
​string · enum · required

Merchant-chosen conversion event: 'Purchase' fires immediately at checkout, 'Purchase_Confirmed' fires on order confirmation, 'Purchase_Delivered' fires on confirmed delivery, and 'Lead' fires at checkout.

Enum values:
Purchase
Purchase_Confirmed
Purchase_Delivered
Lead
testMode
​boolean · required

When true, Conversions API events carry test_event_code to Meta's test stream.

enabled
​boolean · required
perPageTrackingEnabled
​boolean · required

Master switch for per-landing-page pixels. While false (the default), every landing page reports to this pixel no matter what is configured against it — which is also this feature's rollback.

createdAt
​string · date-time · required
updatedAt
​string · date-time · required

WhatsAppButtonConfig

enabled
​boolean · required
phone
​string | null · required

Stored in E.164, however the merchant typed it.

agentName
​string | null · required
caption
​string | null · required
avatarKey
​string | null · minLength: 1 · maxLength: 512 · required

The agent's photo, from a completed upload; null shows the store's logo.

welcomeMessage
​string | null · required
launcherLabel
​string | null · required
ctaLabel
​string | null · required
prefillGeneral
​string | null · required
prefillProduct
​string | null · required
thankYouButtonLabel
​string | null · required
prefillThankYou
​string | null · required
accent
​string · enum · required
Enum values:
whatsapp
primary
position
​string · enum · required
Enum values:
right
left
attention
​boolean · required
​WhatsAppButtonSurfaces · required

Which kinds of storefront page the launcher appears on. A fixed registry rather than URL patterns, and every surface off is a valid paused state.

WhatsAppButtonSurfaces

Which kinds of storefront page the launcher appears on. A fixed registry rather than URL patterns, and every surface off is a valid paused state.
home
​boolean · required
catalog
​boolean · required
product
​boolean · required
pages
​boolean · required
thankYou
​boolean · required
checkout
​boolean · required
landing
​boolean · required

WhatsAppButtonConfigInput

The button's setup. Same shape as WhatsAppButtonConfig, with every key optional — an omitted key takes its default. `phone` is accepted in any form the merchant knows (0551234567, 00213…, +213…, spaced) and stored normalised. Unknown keys, an unreachable number, an avatar that is not an uploaded image's Media Key and every text cap are refused, with each problem listed in `context.issues`.
No data returned

TelegramApp

consumerId
​string · required

The Telegram Consumer the bot sends through: its deliveries are under /api/event-deliveries

enabled
​boolean · required
disabledReason
​string | null · enum · required

Why it is off: not_connected (no chat yet), bot_blocked (the chat blocked the bot), merchant, failing; null while on

Enum values:
failing
merchant
gone
bot_blocked
not_connected
failingSince
​string | null · required

Since when every message has failed; null once one is delivered

bot
​object | null · required

The saved bot; null once it was disconnected

chat
​object | null · required

The connected chat; null until someone presses Start on a pairing link

pairingExpiresAt
​string | null · required

Until when the latest pairing link works; null when none is open

events
​string[] · required
language
​string | null · enum · required
Enum values:
ar
fr
en
writesIn
​string · enum · required

The language messages are written in now

Enum values:
ar
fr
en

TelegramChange

events
​string[] · minItems: 1

The Event Types the bot tells, one or more

Enum values:
order.created
order.updated
order.confirmed
order.unreachable
order.preparing
order.ready
order.cancelled
order.line_returned
language
​string | null · enum

The language messages are written in; null for the store's primary language

Enum values:
ar
fr
en
enabled
​boolean

On or off. Turning it on needs a connected chat.

ReviewRules

enabled
​boolean · required

When false, reviews are hidden on the storefront and shoppers cannot send one

maxPhotos
​integer · min: 0 · max: 6 · required

Photos a shopper may add to a review, 0 (none) to 6

​required

Longest voice note a shopper may add, in seconds (30, 60, 90, 120); null = no voice notes

autoPublish
​string · enum · required

Which shopper reviews publish without checking: none (off), text-only ones (text_only: anything with a photo or voice note waits), or all

Enum values:
off
text_only
all

ShippingLabelConfig

size
​string · enum · required

The physical label: 100×150 mm, the 4×6 inch roll of thermal printers

Enum values:
100x150
language
​string · enum · required

The language of the label's own words; the order's details print as written

Enum values:
fr
ar
showLogo
​boolean · required
senderPhone
​string | null · required

Printed for the sender; null prints the legal profile's contact phone

showItems
​boolean · required

What is in the parcel: quantity, name and variant of each line

showNotes
​boolean · required

The order's notes, for the driver

openParcel
​string · enum · required

Whether the customer may open the parcel before paying; unset prints nothing

Enum values:
unset
allowed
forbidden
footer
​string | null · maxLength: 120 · required

ShippingLabelSender

The store as its labels print it: its name and logo, and the phone and address of its legal profile
name
​string · required
logoUrl
​string | null · required
phone
​string | null · required
address
​string | null · required

ShippingLabelConfigInput

A ShippingLabelConfig with every key optional
No data returned

ShippingLabelParcel

shipmentId
​string · required
orderNumber
​string · required
handedAt
​string · required

When the order was given to the driver

amount
​number · required

The cash to collect, frozen on the shipment

​object · required
​object[] · required
notes
​string | null · required
driver
​object | null · required

ShippingProfile

Shipping rate profile. List responses include ruleCount; detail responses include the rules array instead.
id
​string · required
name
​string · required
isDefault
​boolean · required

Exactly one profile is always the default; its rates auto-apply on order creation

notes
​string | null · required
productCount
​integer · required

How many products are assigned to this profile

createdAt
​string · date-time · required
updatedAt
​string · date-time · required
ruleCount
​integer · required

Number of wilaya rules in this profile

ShippingProfileWithRules

Shipping profile with its full list of wilaya rules
id
​string · required
name
​string · required
isDefault
​boolean · required

Exactly one profile is always the default; its rates auto-apply on order creation

notes
​string | null · required
productCount
​integer · required

How many products are assigned to this profile

createdAt
​string · date-time · required
updatedAt
​string · date-time · required
​ShippingRule[] · required

ShippingRule

Per-wilaya customer delivery rate within a shipping profile
id
​string · required
profileId
​string · required
wilayaId
​integer · min: 1 · max: 58 · required
wilayaName
​string · required

Wilaya French/name — joined from reference table

wilayaNameAr
​string · required
homePrice
​number · required
stopDeskPrice
​number · required
homeEnabled
​boolean · required
stopDeskEnabled
​boolean · required
createdAt
​string · date-time · required

CommuneOverride

A commune within a wilaya rule, showing both the raw override fields (null = inherited) and the effective values used at fee-resolution time.
communeId
​string · required
communeName
​string · required
communeNameAr
​string · required
postalCode
​string | null · required
homeEnabled
​boolean | null · required

null = inherited from wilaya rule

stopDeskEnabled
​boolean | null · required

null = inherited from wilaya rule

homePrice
​number | null · required

null = inherited from wilaya rule

stopDeskPrice
​number | null · required

null = inherited from wilaya rule

effectiveHomeEnabled
​boolean · required
effectiveStopDeskEnabled
​boolean · required
effectiveHomePrice
​number · required
effectiveStopDeskPrice
​number · required
hasOverride
​boolean · required

DriverPayment

id
​string · required
driverId
​string · required

UUID of the driver this payment is for

type
​string · enum · required

cod_remittance: driver hands COD cash to business. fee_payment: business pays driver fees. net_settlement: both at once (driver hands COD − fees net amount).

Enum values:
cod_remittance
fee_payment
net_settlement
amount
​number · required

Settled amount, computed server-side from the shipments' frozen values: cash total (cod_remittance), fee total (fee_payment), or cash − fees (net_settlement).

orderCount
​integer · required

Number of shipments (one per order) this payment settles.

notes
​string | null · required

Optional internal note about this payment record.

createdBy
​string · required

User ID of the team member who recorded this payment.

createdByName
​string · required

Denormalised display name for audit trail.

createdAt
​string · date-time · required

PendingSettlement

A delivered driver shipment with a part still to settle
shipmentId
​string · required
orderId
​string · required
orderNumber
​string · required
customerName
​string · required
codAmount
​number · required

Cash the driver collected (DZD)

driverFee
​number · required

The driver's frozen fee (DZD)

deliveredAt
​string · date-time · required
codPaymentId
​string | null · required

The payment that settled the cash; null while the driver still holds it

feePaymentId
​string | null · required

The payment that settled the fee; null while it is owed

Store

Single-tenant store configuration: branding, theme, localization, SEO, and feature flags
id
​string · required
name
​string · required
domain
​string | null · required

Custom storefront domain

logo
​object | null · required

The store's logo

themeId
​string · required

The storefront theme's slug, e.g. "theme-00"

lang
​string · enum · required

The store's primary language: its storefront language and first fallback

Enum values:
ar
fr
en
currency
​string · required
currencySymbol
​string · required
metaTitle
​string | null · required
metaDescription
​string | null · required
ogImage
​object | null · required

The image links to the store show when shared

cartEnabled
​boolean · required

When true the storefront renders the shopping cart alongside the direct order form

freeShippingThreshold
​integer | null · required

Order subtotal (DZD) at or above which delivery is free. null = off

cartShippingMode
​string · enum · required

Which rate a basket spanning several shipping profiles pays

Enum values:
highest
default_profile
storeApiKey
​string | null · required

Plaintext storefront API key — visible to the merchant in Store Settings. Not the dashboard API key.

createdAt
​string · date-time · required
updatedAt
​string · date-time · required
​StoreLanguage[] · required

Every language the store has added, primary first, published or not.

StoreLanguage

locale
​string · enum · required
Enum values:
ar
fr
en
published
​boolean · required

Shown to shoppers. Always true for the primary.

primary
​boolean · required

Review

A product review, as the merchant moderates it
id
​string · required
productId
​string · required
productName
​string | null · required
orderId
​string | null · required

The order it rests on; null for a store review without one

orderNumber
​string | null · required
customerId
​string | null · required
customerName
​string · required
rating
​integer · min: 1 · max: 5 · required
title
​string | null · required
body
​string · required
status
​string · enum · required
Enum values:
pending
approved
rejected
source
​string · enum · required

Sent by a shopper (storefront) or entered by the store (merchant)

Enum values:
storefront
merchant
verified
​boolean · required

Rests on a delivered order: the storefront shows it as a verified purchase

mediaDropped
​integer · required

Photos or voice notes received but not kept (unreadable, too long)

createdBy
​string | null · required

The staff member who entered a store review

createdAt
​string · required
updatedAt
​string · required
​ReviewMedia[] · required

ReviewMedia

A photo or the voice note of a review
id
​string · required
kind
​string · enum · required
Enum values:
image
audio
url
​string · uri · required

A photo at 1600 px at most (WebP), or the voice note as recorded

thumbUrl
​string | null · uri · required

A photo's 480 px version for lists

contentType
​string · required
bytes
​integer · required
width
​integer | null · required
height
​integer | null · required
durationMs
​integer | null · required

A voice note's length

Offer

id
​string · required

Offer UUID

name
​string · required

Merchant-facing display name.

triggerProduct
​object | null · required

The product the customer must purchase to trigger this offer. Null when the trigger product no longer exists.

triggerVariant
​object | null · required

Specific variant required to trigger the offer. null = any variant of the trigger product.

triggerQuantity
​integer · min: 1 · required

Minimum quantity of the trigger product the customer must order.

rewardProduct
​object | null · required

The product the customer receives for free when the offer triggers. null for free_shipping offers.

rewardVariant
​object | null · required

Specific variant given as the reward. null = same variant as the ordered item (when same product) or the first active variant (when different product). Always null for free_shipping offers.

rewardQuantity
​integer · min: 0 · required

Number of free reward units added to the order. 0 for free_shipping offers.

discountType
​string · enum · required

free = reward product added at price 0. free_shipping = delivery fee waived (no reward product).

Enum values:
free
free_shipping
startsAt
​string | null · date-time · required

UTC ISO-8601 datetime when the offer becomes active. null = no start restriction.

endsAt
​string | null · date-time · required

UTC ISO-8601 datetime when the offer expires. null = no end restriction.

status
​string · enum · required

Only active offers within the schedule window are auto-applied to store orders.

Enum values:
active
inactive
state
​string · enum · required

Where the offer stands now: switched off, not started, ended, or live — the only state shoppers see it in.

Enum values:
inactive
scheduled
expired
live
createdAt
​string · date-time · required
updatedAt
​string · date-time · required

CouponSummary

id
​string · required
code
​string · required
kind
​string · enum · required
Enum values:
percentage
fixed_amount
free_shipping
value
​integer · required
maxDiscount
​integer | null · required
minSubtotal
​integer | null · required
minQuantity
​integer | null · required
scope
​string · enum · required
Enum values:
store
products
collections
audience
​string · enum · required
Enum values:
everyone
selected
usageLimit
​integer | null · required
oncePerCustomer
​boolean · required
startsAt
​string | null · required
endsAt
​string | null · required
status
​string · enum · required
Enum values:
active
inactive
state
​string · enum · required

Where the coupon stands now.

Enum values:
inactive
scheduled
expired
used_up
live
uses
​integer · required

Orders that used it and are not cancelled.

discountGiven
​integer · required

What those orders were given off, in dinars.

createdAt
​string · required
updatedAt
​string · required
​object · required

Coupon

id
​string · required
code
​string · required
kind
​string · enum · required
Enum values:
percentage
fixed_amount
free_shipping
value
​integer · required
maxDiscount
​integer | null · required
minSubtotal
​integer | null · required
minQuantity
​integer | null · required
scope
​string · enum · required
Enum values:
store
products
collections
audience
​string · enum · required
Enum values:
everyone
selected
usageLimit
​integer | null · required
oncePerCustomer
​boolean · required
startsAt
​string | null · required
endsAt
​string | null · required
status
​string · enum · required
Enum values:
active
inactive
state
​string · enum · required

Where the coupon stands now.

Enum values:
inactive
scheduled
expired
used_up
live
uses
​integer · required

Orders that used it and are not cancelled.

discountGiven
​integer · required

What those orders were given off, in dinars.

createdAt
​string · required
updatedAt
​string · required
​object[] · required
​object[] · required
​object[] · required
​object[] · required

StockOverview

totalSkus
​integer · required

Total number of tracked SKUs (simple + variants).

outOfStockCount
​integer · required
lowStockCount
​integer · required
totalInventoryValue
​integer · required

Sum of (inventory × price) across all tracked SKUs, in DZD.

currency
​string · required
​StockAlertItem[] · required
​StockAlertItem[] · required

Items at or below their low stock threshold (but still in stock).

​StockAlertItem[] · required

Every tracked SKU. Sorted: out-of-stock first, then by inventory ascending. Used by the inventory table.

StockAlertItem

productId
​string · required
variantId
​string | null · required
productName
​string · required
variantLabel
​string | null · required

Concatenated variant option values, e.g. 'Red / M'. Null for simple products.

sku
​string | null · required

SKU code of the tracked row. Null when a simple product has none.

inventory
​integer · required
lowStockThreshold
​integer · required
isOutOfStock
​boolean · required
updatedAt
​string · required

Last write to the SKU row — every stock adjustment updates it.

StockMovement

id
​string · required
productId
​string · required
variantId
​string | null · required

Variant ID for variant-level movements; null for simple products

type
​string · enum · required
Enum values:
PURCHASE
ADJUSTMENT_ADD
ADJUSTMENT_REMOVE
ORDER_DEDUCTED
ORDER_CANCELLED
ORDER_RETURNED
OFFLINE_SALE
delta
​integer · required

Positive = stock in, negative = stock out. Never zero.

qtyBefore
​integer · required
qtyAfter
​integer · required
reason
​string | null · required

User-supplied note. Required by the API for ADJUSTMENT_ADD, ADJUSTMENT_REMOVE and OFFLINE_SALE.

reference
​string | null · required

orderId for ORDER_* movement types; null otherwise.

createdBy
​string · required
createdByName
​string · required
createdAt
​string · date-time · required

AbandonedOrder

id
​string · required
sessionId
​string · required

Storefront session ID — unique per abandoned checkout

customerName
​string · required
phone
​string · required
wilayaId
​integer | null · min: 1 · max: 58 · required
communeId
​string | null · required
wilayaName
​string | null · required
communeName
​string | null · required
productId
​string | null · required
productName
​string | null · required

The only product, or the FIRST line of the basket. Always populated, so this column reads the same for both shapes.

variantId
​string | null · required
variantLabel
​string | null · required
price
​number | null · required

Cart value at abandonment — the basket subtotal, or one unit's price

​array | null · required

The whole basket, when the shopper abandoned a cart checkout. Null for a single-product checkout, where the flat product fields above are the record.

itemCount
​integer | null · required

Distinct lines in the basket. Null for a single-product checkout.

deliveryType
​string | null · enum · required
Enum values:
home
stop_desk
fbc
​string | null · required

_fbc cookie captured at input — links recovery back to the ad click

fbp
​string | null · required

_fbp browser identity cookie

ipAddress
​string | null · required
userAgent
​string | null · required
status
​string · enum · required
Enum values:
pending
abandoned
contacted
converted
convertedOrderId
​string | null · required

Set when the customer completes an order after contact

convertedOrderNumber
​string | null · required
recoveryAttempts
​integer · required
createdAt
​string · date-time · required
updatedAt
​string · date-time · required

AbandonedOrderItem

productId
​string · required
productName
​string · required
quantity
​integer · required
unitPrice
​number · required

Price shown to the shopper at abandonment. Display only.

variantId
​string | null
variantLabel
​string | null

AbandonedOrderStats

totalAbandoned
​integer · required

Orders currently in abandoned status

totalConverted
​integer · required
conversionRate
​integer · required

Recovered percentage: converted / (abandoned + converted), rounded

estimatedLostRevenue
​number · required

Sum of cart values still sitting in abandoned status, in DZD