@ingenx-io/valets-schema-mcp-server 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/README.md +65 -0
  2. package/data/docs/collections/firestore-paths.md +48 -0
  3. package/data/docs/decisions/migrations.md +56 -0
  4. package/data/docs/decisions/summary.md +78 -0
  5. package/data/docs/enums/booking-status.md +26 -0
  6. package/data/docs/enums/customer-payment-status.md +26 -0
  7. package/data/docs/enums/customer-payment-target-type.md +23 -0
  8. package/data/docs/enums/delivery-type.md +23 -0
  9. package/data/docs/enums/event-status.md +30 -0
  10. package/data/docs/enums/fulfillment-status.md +32 -0
  11. package/data/docs/enums/loyalty-transaction-type.md +32 -0
  12. package/data/docs/enums/order-status.md +65 -0
  13. package/data/docs/enums/payment-method.md +36 -0
  14. package/data/docs/enums/payment-proof-status.md +23 -0
  15. package/data/docs/enums/payment-status.md +34 -0
  16. package/data/docs/enums/return-status.md +32 -0
  17. package/data/docs/enums/session-status.md +32 -0
  18. package/data/docs/enums/ticket-status.md +29 -0
  19. package/data/docs/index.md +95 -0
  20. package/data/docs/models/booking-version.md +295 -0
  21. package/data/docs/models/booking.md +1754 -0
  22. package/data/docs/models/customer-payment-allocation.md +336 -0
  23. package/data/docs/models/customer-payment.md +392 -0
  24. package/data/docs/models/customer.md +475 -0
  25. package/data/docs/models/event.md +386 -0
  26. package/data/docs/models/loyalty-config.md +317 -0
  27. package/data/docs/models/loyalty-reward.md +236 -0
  28. package/data/docs/models/loyalty-status.md +328 -0
  29. package/data/docs/models/loyalty-transaction.md +326 -0
  30. package/data/docs/models/metrics-current.md +532 -0
  31. package/data/docs/models/metrics-daily.md +548 -0
  32. package/data/docs/models/metrics-monthly.md +548 -0
  33. package/data/docs/models/order-item.md +361 -0
  34. package/data/docs/models/order.md +1637 -0
  35. package/data/docs/models/sale.md +540 -0
  36. package/data/docs/models/ticket.md +405 -0
  37. package/data/docs/triggers/event-ticket-triggers.md +204 -0
  38. package/data/docs/triggers/loyalty-automation.md +123 -0
  39. package/data/static/decisions.json +966 -0
  40. package/data/static/llms.txt +1046 -0
  41. package/data/static/openapi.yaml +3090 -0
  42. package/data/static/schemas.json +4012 -0
  43. package/package.json +1 -1
package/data/docs/models/order.md ADDED
@@ -0,0 +1,1637 @@
1
+ ---
2
+ title: "Order"
3
+ sidebar_label: "Order"
4
+ sidebar_position: 14
5
+ ---
6
+
7
+ # Order
8
+
9
+ <details>
10
+ <summary>Example JSON</summary>
11
+
12
+ ```json
13
+ {
14
+ "id": "bk_abc123def456",
15
+ "uid": "user_u8x92kqm",
16
+ "companyId": "comp_xyz789",
17
+ "orderNumber": "ORD-2026-0042",
18
+ "status": "status",
19
+ "paymentStatus": "paymentStatus",
20
+ "fulfillmentStatus": "fulfillmentStatus",
21
+ "returnStatus": "returnStatus",
22
+ "deliveryType": "deliveryType",
23
+ "paymentMethod": "paymentMethod",
24
+ "invoiceId": null,
25
+ "customerId": null,
26
+ "customerName": null,
27
+ "customerEmail": null,
28
+ "customerPhone": null,
29
+ "clientEmail": null,
30
+ "clientPhoneNumber": null,
31
+ "items": null,
32
+ "amount": 45000,
33
+ "amountPaid": null,
34
+ "total": null,
35
+ "createdAt": "createdAt",
36
+ "orderDate": "orderDate",
37
+ "PROCESSING_ON": "PROCESSING_ON",
38
+ "COMPLETED_ON": "COMPLETED_ON",
39
+ "CANCELLED_ON": "CANCELLED_ON",
40
+ "cancellationReason": null,
41
+ "shippingCarrier": null,
42
+ "trackingNumber": null,
43
+ "estimatedDeliveryDate": "estimatedDeliveryDate",
44
+ "shippingCost": null,
45
+ "paymentProofUrl": null,
46
+ "paymentProofStatus": "paymentProofStatus",
47
+ "paymentProofAddedAt": "paymentProofAddedAt",
48
+ "paymentProofAddedBy": null,
49
+ "paymentProofReviewedAt": "paymentProofReviewedAt",
50
+ "paymentProofReviewedBy": null,
51
+ "paymentProofRejectionReason": null,
52
+ "paymentStatusChangeReason": null,
53
+ "paymentStatusChangedBy": null,
54
+ "paymentStatusChangedAt": "paymentStatusChangedAt",
55
+ "payments": null,
56
+ "totalOverridden": null,
57
+ "notes": null,
58
+ "additionalInfo": null,
59
+ "appliedDiscountCode": null,
60
+ "purchaseId": null
61
+ }
62
+ ```
63
+
64
+ </details>
65
+
66
+
67
+ - [1. Property `id`](#id)
68
+ - [2. Property `uid`](#uid)
69
+ - [3. Property `companyId`](#companyId)
70
+ - [4. Property `orderNumber`](#orderNumber)
71
+ - [5. Property `status`](#status)
72
+ - [6. Property `paymentStatus`](#paymentStatus)
73
+ - [6.1. Property `payment-status`](#paymentStatus_anyOf_i0)
74
+ - [6.2. Property `item 1`](#paymentStatus_anyOf_i1)
75
+ - [7. Property `fulfillmentStatus`](#fulfillmentStatus)
76
+ - [7.1. Property `fulfillment-status`](#fulfillmentStatus_anyOf_i0)
77
+ - [7.2. Property `item 1`](#fulfillmentStatus_anyOf_i1)
78
+ - [8. Property `returnStatus`](#returnStatus)
79
+ - [8.1. Property `return-status`](#returnStatus_anyOf_i0)
80
+ - [8.2. Property `item 1`](#returnStatus_anyOf_i1)
81
+ - [9. Property `deliveryType`](#deliveryType)
82
+ - [9.1. Property `delivery-type`](#deliveryType_anyOf_i0)
83
+ - [9.2. Property `item 1`](#deliveryType_anyOf_i1)
84
+ - [10. Property `paymentMethod`](#paymentMethod)
85
+ - [10.1. Property `payment-method`](#paymentMethod_anyOf_i0)
86
+ - [10.2. Property `item 1`](#paymentMethod_anyOf_i1)
87
+ - [11. Property `invoiceId`](#invoiceId)
88
+ - [12. Property `customerId`](#customerId)
89
+ - [13. Property `customerName`](#customerName)
90
+ - [14. Property `customerEmail`](#customerEmail)
91
+ - [15. Property `customerPhone`](#customerPhone)
92
+ - [16. Property `clientEmail`](#clientEmail)
93
+ - [17. Property `clientPhoneNumber`](#clientPhoneNumber)
94
+ - [18. Property `items`](#items)
95
+ - [18.1. order-item](#items_items)
96
+ - [18.1.1. Property `name`](#items_items_name)
97
+ - [18.1.2. Property `quantity`](#items_items_quantity)
98
+ - [18.1.3. Property `price`](#items_items_price)
99
+ - [18.1.4. Property `productId`](#items_items_productId)
100
+ - [18.1.5. Property `increment`](#items_items_increment)
101
+ - [18.1.6. Property `variantId`](#items_items_variantId)
102
+ - [18.1.7. Property `supplierId`](#items_items_supplierId)
103
+ - [18.1.8. Property `supplierName`](#items_items_supplierName)
104
+ - [18.1.9. Property `sentAt`](#items_items_sentAt)
105
+ - [18.1.9.1. Property `_seconds`](#items_items_sentAt__seconds)
106
+ - [18.1.9.2. Property `_nanoseconds`](#items_items_sentAt__nanoseconds)
107
+ - [18.1.10. Property `startedCookingAt`](#items_items_startedCookingAt)
108
+ - [18.1.10.1. Property `_seconds`](#items_items_startedCookingAt__seconds)
109
+ - [18.1.10.2. Property `_nanoseconds`](#items_items_startedCookingAt__nanoseconds)
110
+ - [18.1.11. Property `readyAt`](#items_items_readyAt)
111
+ - [18.1.11.1. Property `_seconds`](#items_items_readyAt__seconds)
112
+ - [18.1.11.2. Property `_nanoseconds`](#items_items_readyAt__nanoseconds)
113
+ - [18.1.12. Property `servedAt`](#items_items_servedAt)
114
+ - [18.1.12.1. Property `_seconds`](#items_items_servedAt__seconds)
115
+ - [18.1.12.2. Property `_nanoseconds`](#items_items_servedAt__nanoseconds)
116
+ - [19. Property `amount`](#amount)
117
+ - [20. Property `amountPaid`](#amountPaid)
118
+ - [21. Property `total`](#total)
119
+ - [22. Property `createdAt`](#createdAt)
120
+ - [22.1. Property `_seconds`](#createdAt__seconds)
121
+ - [22.2. Property `_nanoseconds`](#createdAt__nanoseconds)
122
+ - [23. Property `orderDate`](#orderDate)
123
+ - [24. Property `PROCESSING_ON`](#PROCESSING_ON)
124
+ - [24.1. Property `firestore-timestamp`](#PROCESSING_ON_anyOf_i0)
125
+ - [24.2. Property `item 1`](#PROCESSING_ON_anyOf_i1)
126
+ - [25. Property `COMPLETED_ON`](#COMPLETED_ON)
127
+ - [25.1. Property `firestore-timestamp`](#COMPLETED_ON_anyOf_i0)
128
+ - [25.2. Property `item 1`](#COMPLETED_ON_anyOf_i1)
129
+ - [26. Property `CANCELLED_ON`](#CANCELLED_ON)
130
+ - [26.1. Property `firestore-timestamp`](#CANCELLED_ON_anyOf_i0)
131
+ - [26.2. Property `item 1`](#CANCELLED_ON_anyOf_i1)
132
+ - [27. Property `cancellationReason`](#cancellationReason)
133
+ - [28. Property `shippingCarrier`](#shippingCarrier)
134
+ - [29. Property `trackingNumber`](#trackingNumber)
135
+ - [30. Property `estimatedDeliveryDate`](#estimatedDeliveryDate)
136
+ - [30.1. Property `firestore-timestamp`](#estimatedDeliveryDate_anyOf_i0)
137
+ - [30.2. Property `item 1`](#estimatedDeliveryDate_anyOf_i1)
138
+ - [31. Property `shippingCost`](#shippingCost)
139
+ - [32. Property `paymentProofUrl`](#paymentProofUrl)
140
+ - [33. Property `paymentProofStatus`](#paymentProofStatus)
141
+ - [33.1. Property `payment-proof-status`](#paymentProofStatus_anyOf_i0)
142
+ - [33.2. Property `item 1`](#paymentProofStatus_anyOf_i1)
143
+ - [34. Property `paymentProofAddedAt`](#paymentProofAddedAt)
144
+ - [34.1. Property `firestore-timestamp`](#paymentProofAddedAt_anyOf_i0)
145
+ - [34.2. Property `item 1`](#paymentProofAddedAt_anyOf_i1)
146
+ - [35. Property `paymentProofAddedBy`](#paymentProofAddedBy)
147
+ - [36. Property `paymentProofReviewedAt`](#paymentProofReviewedAt)
148
+ - [36.1. Property `firestore-timestamp`](#paymentProofReviewedAt_anyOf_i0)
149
+ - [36.2. Property `item 1`](#paymentProofReviewedAt_anyOf_i1)
150
+ - [37. Property `paymentProofReviewedBy`](#paymentProofReviewedBy)
151
+ - [38. Property `paymentProofRejectionReason`](#paymentProofRejectionReason)
152
+ - [39. Property `paymentStatusChangeReason`](#paymentStatusChangeReason)
153
+ - [40. Property `paymentStatusChangedBy`](#paymentStatusChangedBy)
154
+ - [41. Property `paymentStatusChangedAt`](#paymentStatusChangedAt)
155
+ - [41.1. Property `firestore-timestamp`](#paymentStatusChangedAt_anyOf_i0)
156
+ - [41.2. Property `item 1`](#paymentStatusChangedAt_anyOf_i1)
157
+ - [42. Property `payments`](#payments)
158
+ - [42.1. payments items](#payments_items)
159
+ - [42.1.1. Property `paymentId`](#payments_items_paymentId)
160
+ - [42.1.2. Property `amount`](#payments_items_amount)
161
+ - [42.1.3. Property `currency`](#payments_items_currency)
162
+ - [42.1.4. Property `paymentMethod`](#payments_items_paymentMethod)
163
+ - [42.1.5. Property `paymentDate`](#payments_items_paymentDate)
164
+ - [42.1.6. Property `referenceNumber`](#payments_items_referenceNumber)
165
+ - [42.1.7. Property `status`](#payments_items_status)
166
+ - [43. Property `totalOverridden`](#totalOverridden)
167
+ - [44. Property `notes`](#notes)
168
+ - [44.1. notes items](#notes_items)
169
+ - [44.1.1. Property `id`](#notes_items_id)
170
+ - [44.1.2. Property `text`](#notes_items_text)
171
+ - [44.1.3. Property `createdAt`](#notes_items_createdAt)
172
+ - [44.1.3.1. Property `_seconds`](#createdAt__seconds)
173
+ - [44.1.3.2. Property `_nanoseconds`](#createdAt__nanoseconds)
174
+ - [44.1.4. Property `createdBy`](#notes_items_createdBy)
175
+ - [44.1.5. Property `createdByName`](#notes_items_createdByName)
176
+ - [45. Property `additionalInfo`](#additionalInfo)
177
+ - [46. Property `appliedDiscountCode`](#appliedDiscountCode)
178
+ - [47. Property `purchaseId`](#purchaseId)
179
+
180
+ | | |
181
+ | ------------------------- | ------------------- |
182
+ | **Type** | `object` |
183
+ | **Required** | No |
184
+ | **Additional properties** | Not allowed |
185
+ | **Defined in** | #/definitions/order |
186
+
187
+ **Description:** Order model (D34). Collection: companies/\{companyId\}/orders/\{orderId\}. Status decomposed into 4 orthogonal fields per D34: status (OrderStatus), paymentStatus, fulfillmentStatus, returnStatus. deliveryType determines the fulfillment channel. MIG-11 migrates the old flat 20-value enum.
188
+
189
+ | Property | Pattern | Type | Deprecated | Definition | Title/Description |
190
+ | -------------------------------------------------------------- | ------- | ----------------------- | ---------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
191
+ | + [id](#id ) | No | string | No | - | (Read-only) Firestore document ID. Note: some models also have uid; see ID conventions. |
192
+ | + [uid](#uid ) | No | string | No | - | (Read-only) Entity UID. Often mirrors id. |
193
+ | + [companyId](#companyId ) | No | string | No | - | (Immutable) FK → Company document ID. Scopes all queries. |
194
+ | + [orderNumber](#orderNumber ) | No | string | No | - | (Read-only) Server-generated order number. |
195
+ | + [status](#status ) | No | enum (of string) | No | In #/definitions/order-status | Core lifecycle status (D34, MIG-11). See OrderStatus enum for the legacy value migration mapping. |
196
+ | - [paymentStatus](#paymentStatus ) | No | Combination | No | - | Payment lifecycle (D34). Null until payment is initiated. |
197
+ | - [fulfillmentStatus](#fulfillmentStatus ) | No | Combination | No | - | Delivery/fulfillment lifecycle (D34). |
198
+ | - [returnStatus](#returnStatus ) | No | Combination | No | - | Return/exchange lifecycle (D34). Null until a return or exchange is initiated. |
199
+ | - [deliveryType](#deliveryType ) | No | Combination | No | - | Fulfillment channel for this order (ON_SITE, PICK_UP, DELIVERY). |
200
+ | - [paymentMethod](#paymentMethod ) | No | Combination | No | - | Unified payment method set with African + global methods (D02). |
201
+ | - [invoiceId](#invoiceId ) | No | string or null | No | - | FK → Invoice document ID. |
202
+ | - [customerId](#customerId ) | No | string or null | No | - | FK → Customer.id (Firestore doc ID). Used to resolve customer details. |
203
+ | - [customerName](#customerName ) | No | string or null | No | - | (Denormalized) From Customer.name at write time. |
204
+ | - [customerEmail](#customerEmail ) | No | string or null | No | - | (Denormalized) From Customer.email at write time. Canonical field per D24. |
205
+ | - [customerPhone](#customerPhone ) | No | string or null | No | - | (Denormalized) From Customer.phone at write time. Canonical field per D24. |
206
+ | - [clientEmail](#clientEmail ) | No | string or null | No | - | (Denormalized) Legacy — use \`customerEmail\`. D24 standardized to customer* prefix. |
207
+ | - [clientPhoneNumber](#clientPhoneNumber ) | No | string or null | No | - | (Denormalized) Legacy — use \`customerPhone\`. D24 standardized to customer* prefix. |
208
+ | - [items](#items ) | No | array or null | No | - | - |
209
+ | + [amount](#amount ) | No | number | No | - | Total order amount. Canonical field for the order total. |
210
+ | - [amountPaid](#amountPaid ) | No | number or null | No | - | Amount of \`amount\` paid to date. Derived from payment allocations. |
211
+ | - [total](#total ) | No | number or null | No | - | Mobile-only legacy total field. Deprecated — use \`amount\`. |
212
+ | + [createdAt](#createdAt ) | No | object | No | In #/definitions/firestore-timestamp | (Read-only) Server-generated creation timestamp. |
213
+ | + [orderDate](#orderDate ) | No | object | No | Same as [createdAt](#createdAt ) | Firestore Timestamp serialized representation |
214
+ | - [PROCESSING_ON](#PROCESSING_ON ) | No | Combination | No | - | (Read-only) Timestamp when order entered PROCESSING (D04 SCREAMING_SNAKE). MIG-01 renames from camelCase. |
215
+ | - [COMPLETED_ON](#COMPLETED_ON ) | No | Combination | No | - | (Read-only) Timestamp when order completed (D04 SCREAMING_SNAKE). MIG-01 renames from camelCase. |
216
+ | - [CANCELLED_ON](#CANCELLED_ON ) | No | Combination | No | - | (Read-only) Timestamp when order cancelled (D04 SCREAMING_SNAKE). MIG-01 renames from camelCase. |
217
+ | - [cancellationReason](#cancellationReason ) | No | string or null | No | - | - |
218
+ | - [shippingCarrier](#shippingCarrier ) | No | string or null | No | - | - |
219
+ | - [trackingNumber](#trackingNumber ) | No | string or null | No | - | - |
220
+ | - [estimatedDeliveryDate](#estimatedDeliveryDate ) | No | Combination | No | - | Firestore Timestamp serialized representation |
221
+ | - [shippingCost](#shippingCost ) | No | number or null | No | - | - |
222
+ | - [paymentProofUrl](#paymentProofUrl ) | No | string or null | No | - | URL to uploaded payment proof image/document. |
223
+ | - [paymentProofStatus](#paymentProofStatus ) | No | Combination | No | - | Payment proof review status. |
224
+ | - [paymentProofAddedAt](#paymentProofAddedAt ) | No | Combination | No | - | (Read-only) Timestamp when proof was uploaded. |
225
+ | - [paymentProofAddedBy](#paymentProofAddedBy ) | No | string or null | No | - | FK → User/staff UID who uploaded the payment proof. |
226
+ | - [paymentProofReviewedAt](#paymentProofReviewedAt ) | No | Combination | No | - | (Read-only) Timestamp when proof was reviewed. |
227
+ | - [paymentProofReviewedBy](#paymentProofReviewedBy ) | No | string or null | No | - | FK → User/staff UID who reviewed the payment proof. |
228
+ | - [paymentProofRejectionReason](#paymentProofRejectionReason ) | No | string or null | No | - | - |
229
+ | - [paymentStatusChangeReason](#paymentStatusChangeReason ) | No | string or null | No | - | - |
230
+ | - [paymentStatusChangedBy](#paymentStatusChangedBy ) | No | string or null | No | - | FK → User/staff UID who changed payment status. |
231
+ | - [paymentStatusChangedAt](#paymentStatusChangedAt ) | No | Combination | No | - | (Read-only) Timestamp of last payment status change. |
232
+ | - [payments](#payments ) | No | array of object or null | No | - | [TBD/WIP — IG-4] Denormalized snapshots of CustomerPayments allocated to this order. Sync rules pending IG-4 resolution. |
233
+ | - [totalOverridden](#totalOverridden ) | No | boolean or null | No | - | Mobile-only. When true, total was manually overridden by user (D14). |
234
+ | - [notes](#notes ) | No | array of object or null | No | - | - |
235
+ | - [additionalInfo](#additionalInfo ) | No | string or null | No | - | - |
236
+ | - [appliedDiscountCode](#appliedDiscountCode ) | No | string or null | No | - | - |
237
+ | - [purchaseId](#purchaseId ) | No | string or null | No | - | FK → Sale.id. Link to associated Sale document. |
238
+
239
+ ## <a name="id"></a>1. Property `id`
240
+
241
+ | | |
242
+ | ------------ | -------- |
243
+ | **Type** | `string` |
244
+ | **Required** | Yes |
245
+
246
+ **Description:** (Read-only) Firestore document ID. Note: some models also have uid; see ID conventions.
247
+
248
+ :::warning Server-set
249
+ Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
250
+ :::
251
+
252
+ ## <a name="uid"></a>2. Property `uid`
253
+
254
+ | | |
255
+ | ------------ | -------- |
256
+ | **Type** | `string` |
257
+ | **Required** | Yes |
258
+
259
+ **Description:** (Read-only) Entity UID. Often mirrors id.
260
+
261
+ :::warning Server-set
262
+ Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
263
+ :::
264
+
265
+ ## <a name="companyId"></a>3. Property `companyId`
266
+
267
+ | | |
268
+ | ------------ | -------- |
269
+ | **Type** | `string` |
270
+ | **Required** | Yes |
271
+
272
+ **Description:** (Immutable) FK → Company document ID. Scopes all queries.
273
+
274
+ :::info Immutable
275
+ Set at creation only. This field cannot be modified after the document is created. Include it in CREATE payloads; omit it (or leave unchanged) in UPDATE payloads.
276
+ :::
277
+
278
+ ## <a name="orderNumber"></a>4. Property `orderNumber`
279
+
280
+ | | |
281
+ | ------------ | -------- |
282
+ | **Type** | `string` |
283
+ | **Required** | Yes |
284
+
285
+ **Description:** (Read-only) Server-generated order number.
286
+
287
+ :::warning Server-set
288
+ Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
289
+ :::
290
+
291
+ ## <a name="status"></a>5. Property `status`
292
+
293
+ | | |
294
+ | -------------- | -------------------------- |
295
+ | **Type** | `enum (of string)` |
296
+ | **Required** | Yes |
297
+ | **Defined in** | #/definitions/order-status |
298
+
299
+ **Description:** Core lifecycle status (D34, MIG-11). See OrderStatus enum for the legacy value migration mapping.
300
+
301
+ Must be one of:
302
+ * "PENDING"
303
+ * "CONFIRMED"
304
+ * "PROCESSING"
305
+ * "READY"
306
+ * "COMPLETED"
307
+ * "CANCELLED"
308
+ * "EXPIRED"
309
+
310
+ ## <a name="paymentStatus"></a>6. Property `paymentStatus`
311
+
312
+ | | |
313
+ | ------------------------- | ---------------- |
314
+ | **Type** | `combining` |
315
+ | **Required** | No |
316
+ | **Additional properties** | Any type allowed |
317
+
318
+ **Description:** Payment lifecycle (D34). Null until payment is initiated.
319
+
320
+ | Any of(Option) |
321
+ | ----------------------------------------- |
322
+ | [payment-status](#paymentStatus_anyOf_i0) |
323
+ | [item 1](#paymentStatus_anyOf_i1) |
324
+
325
+ ### <a name="paymentStatus_anyOf_i0"></a>6.1. Property `payment-status`
326
+
327
+ | | |
328
+ | -------------- | ---------------------------- |
329
+ | **Type** | `enum (of string)` |
330
+ | **Required** | No |
331
+ | **Defined in** | #/definitions/payment-status |
332
+
333
+ **Description:** Payment lifecycle status (D01 amended). Used by Order, Sale/Purchase, Booking.
334
+
335
+ Must be one of:
336
+ * "PENDING"
337
+ * "PAID"
338
+ * "PARTIALLY_PAID"
339
+ * "FAILED"
340
+ * "REFUND_PROCESSING"
341
+ * "REFUNDED"
342
+ * "PARTIALLY_REFUNDED"
343
+
344
+ ### <a name="paymentStatus_anyOf_i1"></a>6.2. Property `item 1`
345
+
346
+ | | |
347
+ | ------------ | ------ |
348
+ | **Type** | `null` |
349
+ | **Required** | No |
350
+
351
+ ## <a name="fulfillmentStatus"></a>7. Property `fulfillmentStatus`
352
+
353
+ | | |
354
+ | ------------------------- | ---------------- |
355
+ | **Type** | `combining` |
356
+ | **Required** | No |
357
+ | **Additional properties** | Any type allowed |
358
+
359
+ **Description:** Delivery/fulfillment lifecycle (D34).
360
+
361
+ | Any of(Option) |
362
+ | ------------------------------------------------- |
363
+ | [fulfillment-status](#fulfillmentStatus_anyOf_i0) |
364
+ | [item 1](#fulfillmentStatus_anyOf_i1) |
365
+
366
+ ### <a name="fulfillmentStatus_anyOf_i0"></a>7.1. Property `fulfillment-status`
367
+
368
+ | | |
369
+ | -------------- | -------------------------------- |
370
+ | **Type** | `enum (of string)` |
371
+ | **Required** | No |
372
+ | **Defined in** | #/definitions/fulfillment-status |
373
+
374
+ **Description:** Delivery/fulfillment lifecycle (D34). Optional — null for in-person orders.
375
+
376
+ Must be one of:
377
+ * "PREPARING"
378
+ * "PARTIALLY_SHIPPED"
379
+ * "SHIPPED"
380
+ * "IN_TRANSIT"
381
+ * "DELIVERED"
382
+ * "PICKED_UP"
383
+
384
+ ### <a name="fulfillmentStatus_anyOf_i1"></a>7.2. Property `item 1`
385
+
386
+ | | |
387
+ | ------------ | ------ |
388
+ | **Type** | `null` |
389
+ | **Required** | No |
390
+
391
+ :::tip When to set
392
+ Null for ON_SITE and PICK_UP orders. Set when deliveryType is DELIVERY and a physical shipment or pickup is involved.
393
+ :::
394
+
395
+ :::info See also
396
+ **Decisions:** `D34`
397
+ :::
398
+
399
+ ## <a name="returnStatus"></a>8. Property `returnStatus`
400
+
401
+ | | |
402
+ | ------------------------- | ---------------- |
403
+ | **Type** | `combining` |
404
+ | **Required** | No |
405
+ | **Additional properties** | Any type allowed |
406
+
407
+ **Description:** Return/exchange lifecycle (D34). Null until a return or exchange is initiated.
408
+
409
+ | Any of(Option) |
410
+ | --------------------------------------- |
411
+ | [return-status](#returnStatus_anyOf_i0) |
412
+ | [item 1](#returnStatus_anyOf_i1) |
413
+
414
+ ### <a name="returnStatus_anyOf_i0"></a>8.1. Property `return-status`
415
+
416
+ | | |
417
+ | -------------- | --------------------------- |
418
+ | **Type** | `enum (of string)` |
419
+ | **Required** | No |
420
+ | **Defined in** | #/definitions/return-status |
421
+
422
+ **Description:** Post-sale return/exchange lifecycle (D34). Optional — null until return or exchange initiated.
423
+
424
+ Must be one of:
425
+ * "RETURN_REQUESTED"
426
+ * "RETURN_PROCESSING"
427
+ * "RETURNED"
428
+ * "EXCHANGE_REQUESTED"
429
+ * "EXCHANGE_PROCESSING"
430
+ * "EXCHANGE_COMPLETED"
431
+
432
+ ### <a name="returnStatus_anyOf_i1"></a>8.2. Property `item 1`
433
+
434
+ | | |
435
+ | ------------ | ------ |
436
+ | **Type** | `null` |
437
+ | **Required** | No |
438
+
439
+ ## <a name="deliveryType"></a>9. Property `deliveryType`
440
+
441
+ | | |
442
+ | ------------------------- | ---------------- |
443
+ | **Type** | `combining` |
444
+ | **Required** | No |
445
+ | **Additional properties** | Any type allowed |
446
+
447
+ **Description:** Fulfillment channel for this order (ON_SITE, PICK_UP, DELIVERY).
448
+
449
+ | Any of(Option) |
450
+ | --------------------------------------- |
451
+ | [delivery-type](#deliveryType_anyOf_i0) |
452
+ | [item 1](#deliveryType_anyOf_i1) |
453
+
454
+ ### <a name="deliveryType_anyOf_i0"></a>9.1. Property `delivery-type`
455
+
456
+ | | |
457
+ | -------------- | --------------------------- |
458
+ | **Type** | `enum (of string)` |
459
+ | **Required** | No |
460
+ | **Defined in** | #/definitions/delivery-type |
461
+
462
+ **Description:** Fulfillment channel for an order. Determines whether the customer comes to the business (ON_SITE), collects their order themselves (PICK_UP), or receives a physical delivery (DELIVERY). Drives whether fulfillmentStatus is relevant.
463
+
464
+ Must be one of:
465
+ * "ON_SITE"
466
+ * "PICK_UP"
467
+ * "DELIVERY"
468
+
469
+ ### <a name="deliveryType_anyOf_i1"></a>9.2. Property `item 1`
470
+
471
+ | | |
472
+ | ------------ | ------ |
473
+ | **Type** | `null` |
474
+ | **Required** | No |
475
+
476
+ :::note
477
+ Drives whether fulfillmentStatus is relevant. ON_SITE and PICK_UP orders typically have no fulfillmentStatus.
478
+ :::
479
+
480
+ ## <a name="paymentMethod"></a>10. Property `paymentMethod`
481
+
482
+ | | |
483
+ | ------------------------- | ---------------- |
484
+ | **Type** | `combining` |
485
+ | **Required** | No |
486
+ | **Additional properties** | Any type allowed |
487
+
488
+ **Description:** Unified payment method set with African + global methods (D02).
489
+
490
+ | Any of(Option) |
491
+ | ----------------------------------------- |
492
+ | [payment-method](#paymentMethod_anyOf_i0) |
493
+ | [item 1](#paymentMethod_anyOf_i1) |
494
+
495
+ ### <a name="paymentMethod_anyOf_i0"></a>10.1. Property `payment-method`
496
+
497
+ | | |
498
+ | -------------- | ---------------------------- |
499
+ | **Type** | `enum (of string)` |
500
+ | **Required** | No |
501
+ | **Defined in** | #/definitions/payment-method |
502
+
503
+ **Description:** Unified payment method set with African + global methods (D02).
504
+
505
+ Must be one of:
506
+ * "CASH"
507
+ * "CREDIT_CARD"
508
+ * "ORANGE_MONEY"
509
+ * "WAVE"
510
+ * "MTN_MONEY"
511
+ * "MOOV_MONEY"
512
+ * "BANK_TRANSFER"
513
+ * "PAYPAL"
514
+ * "STRIPE"
515
+ * "OTHER"
516
+
517
+ ### <a name="paymentMethod_anyOf_i1"></a>10.2. Property `item 1`
518
+
519
+ | | |
520
+ | ------------ | ------ |
521
+ | **Type** | `null` |
522
+ | **Required** | No |
523
+
524
+ ## <a name="invoiceId"></a>11. Property `invoiceId`
525
+
526
+ | | |
527
+ | ------------ | ---------------- |
528
+ | **Type** | `string or null` |
529
+ | **Required** | No |
530
+
531
+ **Description:** FK → Invoice document ID.
532
+
533
+ ## <a name="customerId"></a>12. Property `customerId`
534
+
535
+ | | |
536
+ | ------------ | ---------------- |
537
+ | **Type** | `string or null` |
538
+ | **Required** | No |
539
+
540
+ **Description:** FK → Customer.id (Firestore doc ID). Used to resolve customer details.
541
+
542
+ ## <a name="customerName"></a>13. Property `customerName`
543
+
544
+ | | |
545
+ | ------------ | ---------------- |
546
+ | **Type** | `string or null` |
547
+ | **Required** | No |
548
+
549
+ **Description:** (Denormalized) From Customer.name at write time.
550
+
551
+ ## <a name="customerEmail"></a>14. Property `customerEmail`
552
+
553
+ | | |
554
+ | ------------ | ---------------- |
555
+ | **Type** | `string or null` |
556
+ | **Required** | No |
557
+
558
+ **Description:** (Denormalized) From Customer.email at write time. Canonical field per D24.
559
+
560
+ ## <a name="customerPhone"></a>15. Property `customerPhone`
561
+
562
+ | | |
563
+ | ------------ | ---------------- |
564
+ | **Type** | `string or null` |
565
+ | **Required** | No |
566
+
567
+ **Description:** (Denormalized) From Customer.phone at write time. Canonical field per D24.
568
+
569
+ ## <a name="clientEmail"></a>16. Property `clientEmail`
570
+
571
+ | | |
572
+ | ------------ | ---------------- |
573
+ | **Type** | `string or null` |
574
+ | **Required** | No |
575
+
576
+ **Description:** (Denormalized) Legacy — use `customerEmail`. D24 standardized to customer* prefix.
577
+
578
+ :::danger Deprecated
579
+ This field is deprecated. Do not write it in new code.
580
+ :::
581
+
582
+ :::warning Deprecated
583
+ Use `customerEmail` instead.
584
+ :::
585
+
586
+ ## <a name="clientPhoneNumber"></a>17. Property `clientPhoneNumber`
587
+
588
+ | | |
589
+ | ------------ | ---------------- |
590
+ | **Type** | `string or null` |
591
+ | **Required** | No |
592
+
593
+ **Description:** (Denormalized) Legacy — use `customerPhone`. D24 standardized to customer* prefix.
594
+
595
+ :::danger Deprecated
596
+ This field is deprecated. Do not write it in new code.
597
+ :::
598
+
599
+ :::warning Deprecated
600
+ Use `customerPhone` instead.
601
+ :::
602
+
603
+ ## <a name="items"></a>18. Property `items`
604
+
605
+ | | |
606
+ | ------------ | --------------- |
607
+ | **Type** | `array or null` |
608
+ | **Required** | No |
609
+
610
+ | | Array restrictions |
611
+ | -------------------- | ------------------ |
612
+ | **Min items** | N/A |
613
+ | **Max items** | N/A |
614
+ | **Items unicity** | False |
615
+ | **Additional items** | False |
616
+ | **Tuple validation** | See below |
617
+
618
+ | Each item of this array must be | Description |
619
+ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
620
+ | [order-item](#items_items) | Line item within an Order or Sale/Purchase. Canonical fields: name, quantity, price, productId. Optional commerce fields (increment, variantId, supplierId, supplierName) and kitchen tracking fields (sentAt, startedCookingAt, readyAt, servedAt) are TBD/WIP pending cross-platform alignment. |
621
+
622
+ ### <a name="items_items"></a>18.1. order-item
623
+
624
+ | | |
625
+ | ------------------------- | ------------------------ |
626
+ | **Type** | `object` |
627
+ | **Required** | No |
628
+ | **Additional properties** | Not allowed |
629
+ | **Defined in** | #/definitions/order-item |
630
+
631
+ **Description:** Line item within an Order or Sale/Purchase. Canonical fields: name, quantity, price, productId. Optional commerce fields (increment, variantId, supplierId, supplierName) and kitchen tracking fields (sentAt, startedCookingAt, readyAt, servedAt) are TBD/WIP pending cross-platform alignment.
632
+
633
+ | Property | Pattern | Type | Deprecated | Definition | Title/Description |
634
+ | ---------------------------------------------------- | ------- | ------ | ---------- | ---------- | ------------------------------------------------------------------------------------------------- |
635
+ | + [name](#items_items_name ) | No | string | No | - | Display name of the product or service. |
636
+ | + [quantity](#items_items_quantity ) | No | number | No | - | Number of units ordered. |
637
+ | + [price](#items_items_price ) | No | number | No | - | Unit price. Canonical name per D11. |
638
+ | - [productId](#items_items_productId ) | No | string | No | - | FK → Product document ID. |
639
+ | - [increment](#items_items_increment ) | No | number | No | - | Quantity step for bundle/bulk items (e.g. 5 for a 5-pack). Dashboard/Firebase only. |
640
+ | - [variantId](#items_items_variantId ) | No | string | No | - | FK → ProductVariant ID within the product. Dashboard/Firebase only. |
641
+ | - [supplierId](#items_items_supplierId ) | No | string | No | - | FK → Supplier document ID. B2B orders only. |
642
+ | - [supplierName](#items_items_supplierName ) | No | string | No | - | (Denormalized) From Supplier.name at write time. B2B orders only. |
643
+ | - [sentAt](#items_items_sentAt ) | No | object | No | - | (Read-only) Timestamp when the item was sent to the kitchen. TBD/WIP — archived CBL flow. |
644
+ | - [startedCookingAt](#items_items_startedCookingAt ) | No | object | No | - | (Read-only) Timestamp when the kitchen started preparing this item. TBD/WIP — archived CBL flow. |
645
+ | - [readyAt](#items_items_readyAt ) | No | object | No | - | (Read-only) Timestamp when the item was ready for pickup or service. TBD/WIP — archived CBL flow. |
646
+ | - [servedAt](#items_items_servedAt ) | No | object | No | - | (Read-only) Timestamp when the item was served to the customer. TBD/WIP — archived CBL flow. |
647
+
648
+ #### <a name="items_items_name"></a>18.1.1. Property `name`
649
+
650
+ | | |
651
+ | ------------ | -------- |
652
+ | **Type** | `string` |
653
+ | **Required** | Yes |
654
+
655
+ **Description:** Display name of the product or service.
656
+
657
+ #### <a name="items_items_quantity"></a>18.1.2. Property `quantity`
658
+
659
+ | | |
660
+ | ------------ | -------- |
661
+ | **Type** | `number` |
662
+ | **Required** | Yes |
663
+
664
+ **Description:** Number of units ordered.
665
+
666
+ #### <a name="items_items_price"></a>18.1.3. Property `price`
667
+
668
+ | | |
669
+ | ------------ | -------- |
670
+ | **Type** | `number` |
671
+ | **Required** | Yes |
672
+
673
+ **Description:** Unit price. Canonical name per D11.
674
+
675
+ #### <a name="items_items_productId"></a>18.1.4. Property `productId`
676
+
677
+ | | |
678
+ | ------------ | -------- |
679
+ | **Type** | `string` |
680
+ | **Required** | No |
681
+
682
+ **Description:** FK → Product document ID.
683
+
684
+ #### <a name="items_items_increment"></a>18.1.5. Property `increment`
685
+
686
+ | | |
687
+ | ------------ | -------- |
688
+ | **Type** | `number` |
689
+ | **Required** | No |
690
+
691
+ **Description:** Quantity step for bundle/bulk items (e.g. 5 for a 5-pack). Dashboard/Firebase only.
692
+
693
+ #### <a name="items_items_variantId"></a>18.1.6. Property `variantId`
694
+
695
+ | | |
696
+ | ------------ | -------- |
697
+ | **Type** | `string` |
698
+ | **Required** | No |
699
+
700
+ **Description:** FK → ProductVariant ID within the product. Dashboard/Firebase only.
701
+
702
+ #### <a name="items_items_supplierId"></a>18.1.7. Property `supplierId`
703
+
704
+ | | |
705
+ | ------------ | -------- |
706
+ | **Type** | `string` |
707
+ | **Required** | No |
708
+
709
+ **Description:** FK → Supplier document ID. B2B orders only.
710
+
711
+ #### <a name="items_items_supplierName"></a>18.1.8. Property `supplierName`
712
+
713
+ | | |
714
+ | ------------ | -------- |
715
+ | **Type** | `string` |
716
+ | **Required** | No |
717
+
718
+ **Description:** (Denormalized) From Supplier.name at write time. B2B orders only.
719
+
720
+ #### <a name="items_items_sentAt"></a>18.1.9. Property `sentAt`
721
+
722
+ | | |
723
+ | ------------------------- | ----------- |
724
+ | **Type** | `object` |
725
+ | **Required** | No |
726
+ | **Additional properties** | Not allowed |
727
+
728
+ **Description:** (Read-only) Timestamp when the item was sent to the kitchen. TBD/WIP — archived CBL flow.
729
+
730
+ | Property | Pattern | Type | Deprecated | Definition | Title/Description |
731
+ | --------------------------------------------------- | ------- | ------- | ---------- | ---------- | ----------------- |
732
+ | + [_seconds](#items_items_sentAt__seconds ) | No | integer | No | - | - |
733
+ | + [_nanoseconds](#items_items_sentAt__nanoseconds ) | No | integer | No | - | - |
734
+
735
+ ##### <a name="items_items_sentAt__seconds"></a>18.1.9.1. Property `_seconds`
736
+
737
+ | | |
738
+ | ------------ | --------- |
739
+ | **Type** | `integer` |
740
+ | **Required** | Yes |
741
+
742
+ | Restrictions | |
743
+ | ------------ | ---------------------- |
744
+ | **Minimum** | &ge; -9007199254740991 |
745
+ | **Maximum** | &le; 9007199254740991 |
746
+
747
+ ##### <a name="items_items_sentAt__nanoseconds"></a>18.1.9.2. Property `_nanoseconds`
748
+
749
+ | | |
750
+ | ------------ | --------- |
751
+ | **Type** | `integer` |
752
+ | **Required** | Yes |
753
+
754
+ | Restrictions | |
755
+ | ------------ | ---------------------- |
756
+ | **Minimum** | &ge; -9007199254740991 |
757
+ | **Maximum** | &le; 9007199254740991 |
758
+
759
+ #### <a name="items_items_startedCookingAt"></a>18.1.10. Property `startedCookingAt`
760
+
761
+ | | |
762
+ | ------------------------- | ----------- |
763
+ | **Type** | `object` |
764
+ | **Required** | No |
765
+ | **Additional properties** | Not allowed |
766
+
767
+ **Description:** (Read-only) Timestamp when the kitchen started preparing this item. TBD/WIP — archived CBL flow.
768
+
769
+ | Property | Pattern | Type | Deprecated | Definition | Title/Description |
770
+ | ------------------------------------------------------------- | ------- | ------- | ---------- | ---------- | ----------------- |
771
+ | + [_seconds](#items_items_startedCookingAt__seconds ) | No | integer | No | - | - |
772
+ | + [_nanoseconds](#items_items_startedCookingAt__nanoseconds ) | No | integer | No | - | - |
773
+
774
+ ##### <a name="items_items_startedCookingAt__seconds"></a>18.1.10.1. Property `_seconds`
775
+
776
+ | | |
777
+ | ------------ | --------- |
778
+ | **Type** | `integer` |
779
+ | **Required** | Yes |
780
+
781
+ | Restrictions | |
782
+ | ------------ | ---------------------- |
783
+ | **Minimum** | &ge; -9007199254740991 |
784
+ | **Maximum** | &le; 9007199254740991 |
785
+
786
+ ##### <a name="items_items_startedCookingAt__nanoseconds"></a>18.1.10.2. Property `_nanoseconds`
787
+
788
+ | | |
789
+ | ------------ | --------- |
790
+ | **Type** | `integer` |
791
+ | **Required** | Yes |
792
+
793
+ | Restrictions | |
794
+ | ------------ | ---------------------- |
795
+ | **Minimum** | &ge; -9007199254740991 |
796
+ | **Maximum** | &le; 9007199254740991 |
797
+
798
+ #### <a name="items_items_readyAt"></a>18.1.11. Property `readyAt`
799
+
800
+ | | |
801
+ | ------------------------- | ----------- |
802
+ | **Type** | `object` |
803
+ | **Required** | No |
804
+ | **Additional properties** | Not allowed |
805
+
806
+ **Description:** (Read-only) Timestamp when the item was ready for pickup or service. TBD/WIP — archived CBL flow.
807
+
808
+ | Property | Pattern | Type | Deprecated | Definition | Title/Description |
809
+ | ---------------------------------------------------- | ------- | ------- | ---------- | ---------- | ----------------- |
810
+ | + [_seconds](#items_items_readyAt__seconds ) | No | integer | No | - | - |
811
+ | + [_nanoseconds](#items_items_readyAt__nanoseconds ) | No | integer | No | - | - |
812
+
813
+ ##### <a name="items_items_readyAt__seconds"></a>18.1.11.1. Property `_seconds`
814
+
815
+ | | |
816
+ | ------------ | --------- |
817
+ | **Type** | `integer` |
818
+ | **Required** | Yes |
819
+
820
+ | Restrictions | |
821
+ | ------------ | ---------------------- |
822
+ | **Minimum** | &ge; -9007199254740991 |
823
+ | **Maximum** | &le; 9007199254740991 |
824
+
825
+ ##### <a name="items_items_readyAt__nanoseconds"></a>18.1.11.2. Property `_nanoseconds`
826
+
827
+ | | |
828
+ | ------------ | --------- |
829
+ | **Type** | `integer` |
830
+ | **Required** | Yes |
831
+
832
+ | Restrictions | |
833
+ | ------------ | ---------------------- |
834
+ | **Minimum** | &ge; -9007199254740991 |
835
+ | **Maximum** | &le; 9007199254740991 |
836
+
837
+ #### <a name="items_items_servedAt"></a>18.1.12. Property `servedAt`
838
+
839
+ | | |
840
+ | ------------------------- | ----------- |
841
+ | **Type** | `object` |
842
+ | **Required** | No |
843
+ | **Additional properties** | Not allowed |
844
+
845
+ **Description:** (Read-only) Timestamp when the item was served to the customer. TBD/WIP — archived CBL flow.
846
+
847
+ | Property | Pattern | Type | Deprecated | Definition | Title/Description |
848
+ | ----------------------------------------------------- | ------- | ------- | ---------- | ---------- | ----------------- |
849
+ | + [_seconds](#items_items_servedAt__seconds ) | No | integer | No | - | - |
850
+ | + [_nanoseconds](#items_items_servedAt__nanoseconds ) | No | integer | No | - | - |
851
+
852
+ ##### <a name="items_items_servedAt__seconds"></a>18.1.12.1. Property `_seconds`
853
+
854
+ | | |
855
+ | ------------ | --------- |
856
+ | **Type** | `integer` |
857
+ | **Required** | Yes |
858
+
859
+ | Restrictions | |
860
+ | ------------ | ---------------------- |
861
+ | **Minimum** | &ge; -9007199254740991 |
862
+ | **Maximum** | &le; 9007199254740991 |
863
+
864
+ ##### <a name="items_items_servedAt__nanoseconds"></a>18.1.12.2. Property `_nanoseconds`
865
+
866
+ | | |
867
+ | ------------ | --------- |
868
+ | **Type** | `integer` |
869
+ | **Required** | Yes |
870
+
871
+ | Restrictions | |
872
+ | ------------ | ---------------------- |
873
+ | **Minimum** | &ge; -9007199254740991 |
874
+ | **Maximum** | &le; 9007199254740991 |
875
+
876
+ ## <a name="amount"></a>19. Property `amount`
877
+
878
+ | | |
879
+ | ------------ | -------- |
880
+ | **Type** | `number` |
881
+ | **Required** | Yes |
882
+
883
+ **Description:** Total order amount. Canonical field for the order total.
884
+
885
+ ## <a name="amountPaid"></a>20. Property `amountPaid`
886
+
887
+ | | |
888
+ | ------------ | ---------------- |
889
+ | **Type** | `number or null` |
890
+ | **Required** | No |
891
+
892
+ **Description:** Amount of `amount` paid to date. Derived from payment allocations.
893
+
894
+ ## <a name="total"></a>21. Property `total`
895
+
896
+ | | |
897
+ | ------------ | ---------------- |
898
+ | **Type** | `number or null` |
899
+ | **Required** | No |
900
+
901
+ **Description:** Mobile-only legacy total field. Deprecated — use `amount`.
902
+
903
+ :::danger Deprecated
904
+ This field is deprecated. Do not write it in new code.
905
+ :::
906
+
907
+ :::note
908
+ Sent by Mobile only. Mirrors `amount`. Use `amount` for all new writes. Pending deduplication cleanup.
909
+ :::
910
+
911
+ :::warning Deprecated
912
+ Use `amount` instead.
913
+ :::
914
+
915
+ ## <a name="createdAt"></a>22. Property `createdAt`
916
+
917
+ | | |
918
+ | ------------------------- | --------------------------------- |
919
+ | **Type** | `object` |
920
+ | **Required** | Yes |
921
+ | **Additional properties** | Not allowed |
922
+ | **Defined in** | #/definitions/firestore-timestamp |
923
+
924
+ **Description:** (Read-only) Server-generated creation timestamp.
925
+
926
+ | Property | Pattern | Type | Deprecated | Definition | Title/Description |
927
+ | ------------------------------------------ | ------- | ------- | ---------- | ---------- | ----------------- |
928
+ | + [_seconds](#createdAt__seconds ) | No | integer | No | - | - |
929
+ | + [_nanoseconds](#createdAt__nanoseconds ) | No | integer | No | - | - |
930
+
931
+ ### <a name="createdAt__seconds"></a>22.1. Property `_seconds`
932
+
933
+ | | |
934
+ | ------------ | --------- |
935
+ | **Type** | `integer` |
936
+ | **Required** | Yes |
937
+
938
+ | Restrictions | |
939
+ | ------------ | ---------------------- |
940
+ | **Minimum** | &ge; -9007199254740991 |
941
+ | **Maximum** | &le; 9007199254740991 |
942
+
943
+ ### <a name="createdAt__nanoseconds"></a>22.2. Property `_nanoseconds`
944
+
945
+ | | |
946
+ | ------------ | --------- |
947
+ | **Type** | `integer` |
948
+ | **Required** | Yes |
949
+
950
+ | Restrictions | |
951
+ | ------------ | ---------------------- |
952
+ | **Minimum** | &ge; -9007199254740991 |
953
+ | **Maximum** | &le; 9007199254740991 |
954
+
955
+ :::warning Server-set
956
+ Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
957
+ :::
958
+
959
+ ## <a name="orderDate"></a>23. Property `orderDate`
960
+
961
+ | | |
962
+ | ------------------------- | ----------------------- |
963
+ | **Type** | `object` |
964
+ | **Required** | Yes |
965
+ | **Additional properties** | Not allowed |
966
+ | **Same definition as** | [createdAt](#createdAt) |
967
+
968
+ **Description:** Firestore Timestamp serialized representation
969
+
970
+ ## <a name="PROCESSING_ON"></a>24. Property `PROCESSING_ON`
971
+
972
+ | | |
973
+ | ------------------------- | ---------------- |
974
+ | **Type** | `combining` |
975
+ | **Required** | No |
976
+ | **Additional properties** | Any type allowed |
977
+
978
+ **Description:** (Read-only) Timestamp when order entered PROCESSING (D04 SCREAMING_SNAKE). MIG-01 renames from camelCase.
979
+
980
+ | Any of(Option) |
981
+ | ---------------------------------------------- |
982
+ | [firestore-timestamp](#PROCESSING_ON_anyOf_i0) |
983
+ | [item 1](#PROCESSING_ON_anyOf_i1) |
984
+
985
+ ### <a name="PROCESSING_ON_anyOf_i0"></a>24.1. Property `firestore-timestamp`
986
+
987
+ | | |
988
+ | ------------------------- | ----------------------- |
989
+ | **Type** | `object` |
990
+ | **Required** | No |
991
+ | **Additional properties** | Not allowed |
992
+ | **Same definition as** | [createdAt](#createdAt) |
993
+
994
+ **Description:** Firestore Timestamp serialized representation
995
+
996
+ ### <a name="PROCESSING_ON_anyOf_i1"></a>24.2. Property `item 1`
997
+
998
+ | | |
999
+ | ------------ | ------ |
1000
+ | **Type** | `null` |
1001
+ | **Required** | No |
1002
+
1003
+ :::warning Server-set
1004
+ Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
1005
+ :::
1006
+
1007
+ :::note
1008
+ Never write this field directly. The server sets it automatically on status transition to PROCESSING.
1009
+ :::
1010
+
1011
+ :::info See also
1012
+ **Decisions:** `D04`
1013
+ **Migrations:** `MIG-01`
1014
+ :::
1015
+
1016
+ ## <a name="COMPLETED_ON"></a>25. Property `COMPLETED_ON`
1017
+
1018
+ | | |
1019
+ | ------------------------- | ---------------- |
1020
+ | **Type** | `combining` |
1021
+ | **Required** | No |
1022
+ | **Additional properties** | Any type allowed |
1023
+
1024
+ **Description:** (Read-only) Timestamp when order completed (D04 SCREAMING_SNAKE). MIG-01 renames from camelCase.
1025
+
1026
+ | Any of(Option) |
1027
+ | --------------------------------------------- |
1028
+ | [firestore-timestamp](#COMPLETED_ON_anyOf_i0) |
1029
+ | [item 1](#COMPLETED_ON_anyOf_i1) |
1030
+
1031
+ ### <a name="COMPLETED_ON_anyOf_i0"></a>25.1. Property `firestore-timestamp`
1032
+
1033
+ | | |
1034
+ | ------------------------- | ----------------------- |
1035
+ | **Type** | `object` |
1036
+ | **Required** | No |
1037
+ | **Additional properties** | Not allowed |
1038
+ | **Same definition as** | [createdAt](#createdAt) |
1039
+
1040
+ **Description:** Firestore Timestamp serialized representation
1041
+
1042
+ ### <a name="COMPLETED_ON_anyOf_i1"></a>25.2. Property `item 1`
1043
+
1044
+ | | |
1045
+ | ------------ | ------ |
1046
+ | **Type** | `null` |
1047
+ | **Required** | No |
1048
+
1049
+ :::warning Server-set
1050
+ Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
1051
+ :::
1052
+
1053
+ ## <a name="CANCELLED_ON"></a>26. Property `CANCELLED_ON`
1054
+
1055
+ | | |
1056
+ | ------------------------- | ---------------- |
1057
+ | **Type** | `combining` |
1058
+ | **Required** | No |
1059
+ | **Additional properties** | Any type allowed |
1060
+
1061
+ **Description:** (Read-only) Timestamp when order cancelled (D04 SCREAMING_SNAKE). MIG-01 renames from camelCase.
1062
+
1063
+ | Any of(Option) |
1064
+ | --------------------------------------------- |
1065
+ | [firestore-timestamp](#CANCELLED_ON_anyOf_i0) |
1066
+ | [item 1](#CANCELLED_ON_anyOf_i1) |
1067
+
1068
+ ### <a name="CANCELLED_ON_anyOf_i0"></a>26.1. Property `firestore-timestamp`
1069
+
1070
+ | | |
1071
+ | ------------------------- | ----------------------- |
1072
+ | **Type** | `object` |
1073
+ | **Required** | No |
1074
+ | **Additional properties** | Not allowed |
1075
+ | **Same definition as** | [createdAt](#createdAt) |
1076
+
1077
+ **Description:** Firestore Timestamp serialized representation
1078
+
1079
+ ### <a name="CANCELLED_ON_anyOf_i1"></a>26.2. Property `item 1`
1080
+
1081
+ | | |
1082
+ | ------------ | ------ |
1083
+ | **Type** | `null` |
1084
+ | **Required** | No |
1085
+
1086
+ :::warning Server-set
1087
+ Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
1088
+ :::
1089
+
1090
+ ## <a name="cancellationReason"></a>27. Property `cancellationReason`
1091
+
1092
+ | | |
1093
+ | ------------ | ---------------- |
1094
+ | **Type** | `string or null` |
1095
+ | **Required** | No |
1096
+
1097
+ ## <a name="shippingCarrier"></a>28. Property `shippingCarrier`
1098
+
1099
+ | | |
1100
+ | ------------ | ---------------- |
1101
+ | **Type** | `string or null` |
1102
+ | **Required** | No |
1103
+
1104
+ ## <a name="trackingNumber"></a>29. Property `trackingNumber`
1105
+
1106
+ | | |
1107
+ | ------------ | ---------------- |
1108
+ | **Type** | `string or null` |
1109
+ | **Required** | No |
1110
+
1111
+ ## <a name="estimatedDeliveryDate"></a>30. Property `estimatedDeliveryDate`
1112
+
1113
+ | | |
1114
+ | ------------------------- | ---------------- |
1115
+ | **Type** | `combining` |
1116
+ | **Required** | No |
1117
+ | **Additional properties** | Any type allowed |
1118
+
1119
+ **Description:** Firestore Timestamp serialized representation
1120
+
1121
+ | Any of(Option) |
1122
+ | ------------------------------------------------------ |
1123
+ | [firestore-timestamp](#estimatedDeliveryDate_anyOf_i0) |
1124
+ | [item 1](#estimatedDeliveryDate_anyOf_i1) |
1125
+
1126
+ ### <a name="estimatedDeliveryDate_anyOf_i0"></a>30.1. Property `firestore-timestamp`
1127
+
1128
+ | | |
1129
+ | ------------------------- | ----------------------- |
1130
+ | **Type** | `object` |
1131
+ | **Required** | No |
1132
+ | **Additional properties** | Not allowed |
1133
+ | **Same definition as** | [createdAt](#createdAt) |
1134
+
1135
+ **Description:** Firestore Timestamp serialized representation
1136
+
1137
+ ### <a name="estimatedDeliveryDate_anyOf_i1"></a>30.2. Property `item 1`
1138
+
1139
+ | | |
1140
+ | ------------ | ------ |
1141
+ | **Type** | `null` |
1142
+ | **Required** | No |
1143
+
1144
+ ## <a name="shippingCost"></a>31. Property `shippingCost`
1145
+
1146
+ | | |
1147
+ | ------------ | ---------------- |
1148
+ | **Type** | `number or null` |
1149
+ | **Required** | No |
1150
+
1151
+ ## <a name="paymentProofUrl"></a>32. Property `paymentProofUrl`
1152
+
1153
+ | | |
1154
+ | ------------ | ---------------- |
1155
+ | **Type** | `string or null` |
1156
+ | **Required** | No |
1157
+
1158
+ **Description:** URL to uploaded payment proof image/document.
1159
+
1160
+ ## <a name="paymentProofStatus"></a>33. Property `paymentProofStatus`
1161
+
1162
+ | | |
1163
+ | ------------------------- | ---------------- |
1164
+ | **Type** | `combining` |
1165
+ | **Required** | No |
1166
+ | **Additional properties** | Any type allowed |
1167
+
1168
+ **Description:** Payment proof review status.
1169
+
1170
+ | Any of(Option) |
1171
+ | ---------------------------------------------------- |
1172
+ | [payment-proof-status](#paymentProofStatus_anyOf_i0) |
1173
+ | [item 1](#paymentProofStatus_anyOf_i1) |
1174
+
1175
+ ### <a name="paymentProofStatus_anyOf_i0"></a>33.1. Property `payment-proof-status`
1176
+
1177
+ | | |
1178
+ | -------------- | ---------------------------------- |
1179
+ | **Type** | `enum (of string)` |
1180
+ | **Required** | No |
1181
+ | **Defined in** | #/definitions/payment-proof-status |
1182
+
1183
+ **Description:** Payment proof review status. Used by Order and Booking payment proof workflows.
1184
+
1185
+ Must be one of:
1186
+ * "PENDING"
1187
+ * "APPROVED"
1188
+ * "REJECTED"
1189
+
1190
+ ### <a name="paymentProofStatus_anyOf_i1"></a>33.2. Property `item 1`
1191
+
1192
+ | | |
1193
+ | ------------ | ------ |
1194
+ | **Type** | `null` |
1195
+ | **Required** | No |
1196
+
1197
+ ## <a name="paymentProofAddedAt"></a>34. Property `paymentProofAddedAt`
1198
+
1199
+ | | |
1200
+ | ------------------------- | ---------------- |
1201
+ | **Type** | `combining` |
1202
+ | **Required** | No |
1203
+ | **Additional properties** | Any type allowed |
1204
+
1205
+ **Description:** (Read-only) Timestamp when proof was uploaded.
1206
+
1207
+ | Any of(Option) |
1208
+ | ---------------------------------------------------- |
1209
+ | [firestore-timestamp](#paymentProofAddedAt_anyOf_i0) |
1210
+ | [item 1](#paymentProofAddedAt_anyOf_i1) |
1211
+
1212
+ ### <a name="paymentProofAddedAt_anyOf_i0"></a>34.1. Property `firestore-timestamp`
1213
+
1214
+ | | |
1215
+ | ------------------------- | ----------------------- |
1216
+ | **Type** | `object` |
1217
+ | **Required** | No |
1218
+ | **Additional properties** | Not allowed |
1219
+ | **Same definition as** | [createdAt](#createdAt) |
1220
+
1221
+ **Description:** Firestore Timestamp serialized representation
1222
+
1223
+ ### <a name="paymentProofAddedAt_anyOf_i1"></a>34.2. Property `item 1`
1224
+
1225
+ | | |
1226
+ | ------------ | ------ |
1227
+ | **Type** | `null` |
1228
+ | **Required** | No |
1229
+
1230
+ :::warning Server-set
1231
+ Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
1232
+ :::
1233
+
1234
+ ## <a name="paymentProofAddedBy"></a>35. Property `paymentProofAddedBy`
1235
+
1236
+ | | |
1237
+ | ------------ | ---------------- |
1238
+ | **Type** | `string or null` |
1239
+ | **Required** | No |
1240
+
1241
+ **Description:** FK → User/staff UID who uploaded the payment proof.
1242
+
1243
+ ## <a name="paymentProofReviewedAt"></a>36. Property `paymentProofReviewedAt`
1244
+
1245
+ | | |
1246
+ | ------------------------- | ---------------- |
1247
+ | **Type** | `combining` |
1248
+ | **Required** | No |
1249
+ | **Additional properties** | Any type allowed |
1250
+
1251
+ **Description:** (Read-only) Timestamp when proof was reviewed.
1252
+
1253
+ | Any of(Option) |
1254
+ | ------------------------------------------------------- |
1255
+ | [firestore-timestamp](#paymentProofReviewedAt_anyOf_i0) |
1256
+ | [item 1](#paymentProofReviewedAt_anyOf_i1) |
1257
+
1258
+ ### <a name="paymentProofReviewedAt_anyOf_i0"></a>36.1. Property `firestore-timestamp`
1259
+
1260
+ | | |
1261
+ | ------------------------- | ----------------------- |
1262
+ | **Type** | `object` |
1263
+ | **Required** | No |
1264
+ | **Additional properties** | Not allowed |
1265
+ | **Same definition as** | [createdAt](#createdAt) |
1266
+
1267
+ **Description:** Firestore Timestamp serialized representation
1268
+
1269
+ ### <a name="paymentProofReviewedAt_anyOf_i1"></a>36.2. Property `item 1`
1270
+
1271
+ | | |
1272
+ | ------------ | ------ |
1273
+ | **Type** | `null` |
1274
+ | **Required** | No |
1275
+
1276
+ :::warning Server-set
1277
+ Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
1278
+ :::
1279
+
1280
+ ## <a name="paymentProofReviewedBy"></a>37. Property `paymentProofReviewedBy`
1281
+
1282
+ | | |
1283
+ | ------------ | ---------------- |
1284
+ | **Type** | `string or null` |
1285
+ | **Required** | No |
1286
+
1287
+ **Description:** FK → User/staff UID who reviewed the payment proof.
1288
+
1289
+ ## <a name="paymentProofRejectionReason"></a>38. Property `paymentProofRejectionReason`
1290
+
1291
+ | | |
1292
+ | ------------ | ---------------- |
1293
+ | **Type** | `string or null` |
1294
+ | **Required** | No |
1295
+
1296
+ ## <a name="paymentStatusChangeReason"></a>39. Property `paymentStatusChangeReason`
1297
+
1298
+ | | |
1299
+ | ------------ | ---------------- |
1300
+ | **Type** | `string or null` |
1301
+ | **Required** | No |
1302
+
1303
+ ## <a name="paymentStatusChangedBy"></a>40. Property `paymentStatusChangedBy`
1304
+
1305
+ | | |
1306
+ | ------------ | ---------------- |
1307
+ | **Type** | `string or null` |
1308
+ | **Required** | No |
1309
+
1310
+ **Description:** FK → User/staff UID who changed payment status.
1311
+
1312
+ ## <a name="paymentStatusChangedAt"></a>41. Property `paymentStatusChangedAt`
1313
+
1314
+ | | |
1315
+ | ------------------------- | ---------------- |
1316
+ | **Type** | `combining` |
1317
+ | **Required** | No |
1318
+ | **Additional properties** | Any type allowed |
1319
+
1320
+ **Description:** (Read-only) Timestamp of last payment status change.
1321
+
1322
+ | Any of(Option) |
1323
+ | ------------------------------------------------------- |
1324
+ | [firestore-timestamp](#paymentStatusChangedAt_anyOf_i0) |
1325
+ | [item 1](#paymentStatusChangedAt_anyOf_i1) |
1326
+
1327
+ ### <a name="paymentStatusChangedAt_anyOf_i0"></a>41.1. Property `firestore-timestamp`
1328
+
1329
+ | | |
1330
+ | ------------------------- | ----------------------- |
1331
+ | **Type** | `object` |
1332
+ | **Required** | No |
1333
+ | **Additional properties** | Not allowed |
1334
+ | **Same definition as** | [createdAt](#createdAt) |
1335
+
1336
+ **Description:** Firestore Timestamp serialized representation
1337
+
1338
+ ### <a name="paymentStatusChangedAt_anyOf_i1"></a>41.2. Property `item 1`
1339
+
1340
+ | | |
1341
+ | ------------ | ------ |
1342
+ | **Type** | `null` |
1343
+ | **Required** | No |
1344
+
1345
+ :::warning Server-set
1346
+ Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
1347
+ :::
1348
+
1349
+ ## <a name="payments"></a>42. Property `payments`
1350
+
1351
+ | | |
1352
+ | ------------ | ------------------------- |
1353
+ | **Type** | `array of object or null` |
1354
+ | **Required** | No |
1355
+
1356
+ **Description:** [TBD/WIP — IG-4] Denormalized snapshots of CustomerPayments allocated to this order. Sync rules pending IG-4 resolution.
1357
+
1358
+ | | Array restrictions |
1359
+ | -------------------- | ------------------ |
1360
+ | **Min items** | N/A |
1361
+ | **Max items** | N/A |
1362
+ | **Items unicity** | False |
1363
+ | **Additional items** | False |
1364
+ | **Tuple validation** | See below |
1365
+
1366
+ | Each item of this array must be | Description |
1367
+ | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1368
+ | [payments items](#payments_items) | [TBD/WIP — IG-4] Denormalized payment snapshot. Subset of CustomerPayment (D22), written when a payment is allocated to this order. Sync rules pending IG-4 resolution. |
1369
+
1370
+ ### <a name="payments_items"></a>42.1. payments items
1371
+
1372
+ | | |
1373
+ | ------------------------- | ----------- |
1374
+ | **Type** | `object` |
1375
+ | **Required** | No |
1376
+ | **Additional properties** | Not allowed |
1377
+
1378
+ **Description:** [TBD/WIP — IG-4] Denormalized payment snapshot. Subset of CustomerPayment (D22), written when a payment is allocated to this order. Sync rules pending IG-4 resolution.
1379
+
1380
+ | Property | Pattern | Type | Deprecated | Definition | Title/Description |
1381
+ | ----------------------------------------------------- | ------- | ---------------- | ---------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------- |
1382
+ | + [paymentId](#payments_items_paymentId ) | No | string | No | - | (Immutable) FK → CustomerPayment.id. Source document for this snapshot. |
1383
+ | + [amount](#payments_items_amount ) | No | number | No | - | Total payment amount. |
1384
+ | + [currency](#payments_items_currency ) | No | const | No | - | Currency code. Locked to XOF. |
1385
+ | + [paymentMethod](#payments_items_paymentMethod ) | No | enum (of string) | No | Same as [paymentMethod_anyOf_i0](#paymentMethod_anyOf_i0 ) | Payment method used (D02). |
1386
+ | + [paymentDate](#payments_items_paymentDate ) | No | object | No | Same as [createdAt](#createdAt ) | Firestore Timestamp serialized representation |
1387
+ | - [referenceNumber](#payments_items_referenceNumber ) | No | string | No | - | Payment reference (receipt number, transaction ID, etc.). |
1388
+ | + [status](#payments_items_status ) | No | enum (of string) | No | In #/definitions/customer-payment-status | Payment status at time of snapshot. May lag CustomerPayment.status until re-synced. |
1389
+
1390
+ #### <a name="payments_items_paymentId"></a>42.1.1. Property `paymentId`
1391
+
1392
+ | | |
1393
+ | ------------ | -------- |
1394
+ | **Type** | `string` |
1395
+ | **Required** | Yes |
1396
+
1397
+ **Description:** (Immutable) FK → CustomerPayment.id. Source document for this snapshot.
1398
+
1399
+ #### <a name="payments_items_amount"></a>42.1.2. Property `amount`
1400
+
1401
+ | | |
1402
+ | ------------ | -------- |
1403
+ | **Type** | `number` |
1404
+ | **Required** | Yes |
1405
+
1406
+ **Description:** Total payment amount.
1407
+
1408
+ #### <a name="payments_items_currency"></a>42.1.3. Property `currency`
1409
+
1410
+ | | |
1411
+ | ------------ | ------- |
1412
+ | **Type** | `const` |
1413
+ | **Required** | Yes |
1414
+
1415
+ **Description:** Currency code. Locked to XOF.
1416
+
1417
+ Specific value: `"XOF"`
1418
+
1419
+ #### <a name="payments_items_paymentMethod"></a>42.1.4. Property `paymentMethod`
1420
+
1421
+ | | |
1422
+ | ---------------------- | ------------------------------------------------- |
1423
+ | **Type** | `enum (of string)` |
1424
+ | **Required** | Yes |
1425
+ | **Same definition as** | [paymentMethod_anyOf_i0](#paymentMethod_anyOf_i0) |
1426
+
1427
+ **Description:** Payment method used (D02).
1428
+
1429
+ #### <a name="payments_items_paymentDate"></a>42.1.5. Property `paymentDate`
1430
+
1431
+ | | |
1432
+ | ------------------------- | ----------------------- |
1433
+ | **Type** | `object` |
1434
+ | **Required** | Yes |
1435
+ | **Additional properties** | Not allowed |
1436
+ | **Same definition as** | [createdAt](#createdAt) |
1437
+
1438
+ **Description:** Firestore Timestamp serialized representation
1439
+
1440
+ #### <a name="payments_items_referenceNumber"></a>42.1.6. Property `referenceNumber`
1441
+
1442
+ | | |
1443
+ | ------------ | -------- |
1444
+ | **Type** | `string` |
1445
+ | **Required** | No |
1446
+
1447
+ **Description:** Payment reference (receipt number, transaction ID, etc.).
1448
+
1449
+ #### <a name="payments_items_status"></a>42.1.7. Property `status`
1450
+
1451
+ | | |
1452
+ | -------------- | ------------------------------------- |
1453
+ | **Type** | `enum (of string)` |
1454
+ | **Required** | Yes |
1455
+ | **Defined in** | #/definitions/customer-payment-status |
1456
+
1457
+ **Description:** Payment status at time of snapshot. May lag CustomerPayment.status until re-synced.
1458
+
1459
+ Must be one of:
1460
+ * "PENDING"
1461
+ * "CONFIRMED"
1462
+ * "PARTIALLY_APPLIED"
1463
+ * "FULLY_APPLIED"
1464
+ * "REFUNDED"
1465
+ * "CANCELLED"
1466
+
1467
+ :::note
1468
+ Shape and sync rules are TBD pending IG-4 resolution. Do not build production logic against this field until IG-4 is closed.
1469
+ :::
1470
+
1471
+ :::info See also
1472
+ **Issues:** `IG-4`
1473
+ :::
1474
+
1475
+ ## <a name="totalOverridden"></a>43. Property `totalOverridden`
1476
+
1477
+ | | |
1478
+ | ------------ | ----------------- |
1479
+ | **Type** | `boolean or null` |
1480
+ | **Required** | No |
1481
+
1482
+ **Description:** Mobile-only. When true, total was manually overridden by user (D14).
1483
+
1484
+ :::tip When to set
1485
+ Set only by the mobile app when the user manually edits the order total. Dashboard and Cloud Functions should treat this field as read-only.
1486
+ :::
1487
+
1488
+ :::info See also
1489
+ **Decisions:** `D14`
1490
+ :::
1491
+
1492
+ ## <a name="notes"></a>44. Property `notes`
1493
+
1494
+ | | |
1495
+ | ------------ | ------------------------- |
1496
+ | **Type** | `array of object or null` |
1497
+ | **Required** | No |
1498
+
1499
+ | | Array restrictions |
1500
+ | -------------------- | ------------------ |
1501
+ | **Min items** | N/A |
1502
+ | **Max items** | N/A |
1503
+ | **Items unicity** | False |
1504
+ | **Additional items** | False |
1505
+ | **Tuple validation** | See below |
1506
+
1507
+ | Each item of this array must be | Description |
1508
+ | ------------------------------- | -------------------------------------- |
1509
+ | [notes items](#notes_items) | Timestamped note attached to an Order. |
1510
+
1511
+ ### <a name="notes_items"></a>44.1. notes items
1512
+
1513
+ | | |
1514
+ | ------------------------- | ----------- |
1515
+ | **Type** | `object` |
1516
+ | **Required** | No |
1517
+ | **Additional properties** | Not allowed |
1518
+
1519
+ **Description:** Timestamped note attached to an Order.
1520
+
1521
+ | Property | Pattern | Type | Deprecated | Definition | Title/Description |
1522
+ | ---------------------------------------------- | ------- | ------ | ---------- | ------------------------------------ | ---------------------------------------------------------- |
1523
+ | + [id](#notes_items_id ) | No | string | No | - | (Read-only) Note ID. Server-generated. |
1524
+ | + [text](#notes_items_text ) | No | string | No | - | - |
1525
+ | + [createdAt](#notes_items_createdAt ) | No | object | No | In #/definitions/firestore-timestamp | (Read-only) Firestore Timestamp serialized representation. |
1526
+ | - [createdBy](#notes_items_createdBy ) | No | string | No | - | (Immutable) FK → User/staff UID who created this note. |
1527
+ | - [createdByName](#notes_items_createdByName ) | No | string | No | - | (Denormalized) From User display name at write time. |
1528
+
1529
+ #### <a name="notes_items_id"></a>44.1.1. Property `id`
1530
+
1531
+ | | |
1532
+ | ------------ | -------- |
1533
+ | **Type** | `string` |
1534
+ | **Required** | Yes |
1535
+
1536
+ **Description:** (Read-only) Note ID. Server-generated.
1537
+
1538
+ #### <a name="notes_items_text"></a>44.1.2. Property `text`
1539
+
1540
+ | | |
1541
+ | ------------ | -------- |
1542
+ | **Type** | `string` |
1543
+ | **Required** | Yes |
1544
+
1545
+ #### <a name="notes_items_createdAt"></a>44.1.3. Property `createdAt`
1546
+
1547
+ | | |
1548
+ | ------------------------- | --------------------------------- |
1549
+ | **Type** | `object` |
1550
+ | **Required** | Yes |
1551
+ | **Additional properties** | Not allowed |
1552
+ | **Defined in** | #/definitions/firestore-timestamp |
1553
+
1554
+ **Description:** (Read-only) Firestore Timestamp serialized representation.
1555
+
1556
+ | Property | Pattern | Type | Deprecated | Definition | Title/Description |
1557
+ | ------------------------------------------ | ------- | ------- | ---------- | ---------- | ----------------- |
1558
+ | + [_seconds](#createdAt__seconds ) | No | integer | No | - | - |
1559
+ | + [_nanoseconds](#createdAt__nanoseconds ) | No | integer | No | - | - |
1560
+
1561
+ ##### <a name="createdAt__seconds"></a>44.1.3.1. Property `_seconds`
1562
+
1563
+ | | |
1564
+ | ------------ | --------- |
1565
+ | **Type** | `integer` |
1566
+ | **Required** | Yes |
1567
+
1568
+ | Restrictions | |
1569
+ | ------------ | ---------------------- |
1570
+ | **Minimum** | &ge; -9007199254740991 |
1571
+ | **Maximum** | &le; 9007199254740991 |
1572
+
1573
+ ##### <a name="createdAt__nanoseconds"></a>44.1.3.2. Property `_nanoseconds`
1574
+
1575
+ | | |
1576
+ | ------------ | --------- |
1577
+ | **Type** | `integer` |
1578
+ | **Required** | Yes |
1579
+
1580
+ | Restrictions | |
1581
+ | ------------ | ---------------------- |
1582
+ | **Minimum** | &ge; -9007199254740991 |
1583
+ | **Maximum** | &le; 9007199254740991 |
1584
+
1585
+ #### <a name="notes_items_createdBy"></a>44.1.4. Property `createdBy`
1586
+
1587
+ | | |
1588
+ | ------------ | -------- |
1589
+ | **Type** | `string` |
1590
+ | **Required** | No |
1591
+
1592
+ **Description:** (Immutable) FK → User/staff UID who created this note.
1593
+
1594
+ #### <a name="notes_items_createdByName"></a>44.1.5. Property `createdByName`
1595
+
1596
+ | | |
1597
+ | ------------ | -------- |
1598
+ | **Type** | `string` |
1599
+ | **Required** | No |
1600
+
1601
+ **Description:** (Denormalized) From User display name at write time.
1602
+
1603
+ ## <a name="additionalInfo"></a>45. Property `additionalInfo`
1604
+
1605
+ | | |
1606
+ | ------------ | ---------------- |
1607
+ | **Type** | `string or null` |
1608
+ | **Required** | No |
1609
+
1610
+ ## <a name="appliedDiscountCode"></a>46. Property `appliedDiscountCode`
1611
+
1612
+ | | |
1613
+ | ------------ | ---------------- |
1614
+ | **Type** | `string or null` |
1615
+ | **Required** | No |
1616
+
1617
+ ## <a name="purchaseId"></a>47. Property `purchaseId`
1618
+
1619
+ | | |
1620
+ | ------------ | ---------------- |
1621
+ | **Type** | `string or null` |
1622
+ | **Required** | No |
1623
+
1624
+ **Description:** FK → Sale.id. Link to associated Sale document.
1625
+
1626
+ ----------------------------------------------------------------------------------------------------------------------------
1627
+ Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-03-09 at 13:15:53 +0000
1628
+
1629
+ ## Related Decisions
1630
+
1631
+ | Decision | Title |
1632
+ |---|---|
1633
+ | **D04** | Canonical timestamp/status field casing |
1634
+ | **D12** | Payments canonical location model |
1635
+ | **D14** | Keep Mobile order override fields (calculatedTotal, manualTotal, totalOverridden) |
1636
+ | **D24** | Customer reference naming standardization |
1637
+ | **D34** | Order status decomposition into orthogonal fields |