@base44/app-plugin-commerce 0.1.0

package/base44/entities/commerce.Order.jsonc

@@ -0,0 +1,287 @@
+{
+  "name": "commerce.Order",
+  "type": "object",
+  "description": "A store order with embedded line items, shipping/tax/fee/coupon lines and totals. Lifecycle side effects are managed by shared/orders transitionOrder.",
+  "properties": {
+    "order_number": {
+      "type": "integer",
+      "description": "Human-facing sequential number, assigned by shared/sequence"
+    },
+    "order_key": {
+      "type": "string",
+      "description": "Random secret key for guest order tracking (order_xxxxx)"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["pending", "processing", "on-hold", "completed", "cancelled", "refunded", "failed"],
+      "default": "pending",
+      "description": "Order status"
+    },
+    "currency": {
+      "type": "string",
+      "default": "USD",
+      "description": "ISO 4217 currency code"
+    },
+    "prices_include_tax": {
+      "type": "boolean",
+      "default": false,
+      "description": "Whether catalog prices included tax at time of order"
+    },
+    "created_via": {
+      "type": "string",
+      "enum": ["checkout", "admin", "api"],
+      "default": "checkout",
+      "description": "Order creation channel"
+    },
+    "customer_id": {
+      "type": "string",
+      "description": "Customer entity id; empty = guest"
+    },
+    "customer_note": {
+      "type": "string",
+      "description": "Note provided by the customer at checkout"
+    },
+    "customer_ip": {
+      "type": "string",
+      "description": "Customer IP address"
+    },
+    "customer_user_agent": {
+      "type": "string",
+      "description": "Customer user agent"
+    },
+    "billing": {
+      "type": "object",
+      "description": "Billing address",
+      "properties": {
+        "first_name": { "type": "string" },
+        "last_name": { "type": "string" },
+        "company": { "type": "string" },
+        "address_1": { "type": "string" },
+        "address_2": { "type": "string" },
+        "city": { "type": "string" },
+        "state": { "type": "string" },
+        "postcode": { "type": "string" },
+        "country": { "type": "string" },
+        "email": { "type": "string", "format": "email" },
+        "phone": { "type": "string" }
+      }
+    },
+    "shipping": {
+      "type": "object",
+      "description": "Shipping address",
+      "properties": {
+        "first_name": { "type": "string" },
+        "last_name": { "type": "string" },
+        "company": { "type": "string" },
+        "address_1": { "type": "string" },
+        "address_2": { "type": "string" },
+        "city": { "type": "string" },
+        "state": { "type": "string" },
+        "postcode": { "type": "string" },
+        "country": { "type": "string" },
+        "phone": { "type": "string" }
+      }
+    },
+    "payment_method": {
+      "type": "string",
+      "description": "PaymentGateway slug (e.g. bacs|cheque|cod|stripe)"
+    },
+    "payment_method_title": {
+      "type": "string",
+      "description": "Customer-facing payment method title"
+    },
+    "transaction_id": {
+      "type": "string",
+      "description": "External gateway transaction id"
+    },
+    "date_paid": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When payment was confirmed"
+    },
+    "date_completed": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the order was completed"
+    },
+    "line_items": {
+      "type": "array",
+      "description": "Product line items",
+      "items": {
+        "type": "object",
+        "properties": {
+          "line_id": { "type": "string", "description": "Stable uuid for refund references" },
+          "product_id": { "type": "string" },
+          "variation_id": { "type": "string" },
+          "name": { "type": "string" },
+          "sku": { "type": "string" },
+          "quantity": { "type": "integer" },
+          "price": { "type": "number", "description": "Per-unit price after discounts, ex tax" },
+          "tax_class": { "type": "string" },
+          "subtotal": { "type": "number", "description": "Line total before discounts, ex tax" },
+          "subtotal_tax": { "type": "number" },
+          "total": { "type": "number", "description": "Line total after discounts, ex tax" },
+          "total_tax": { "type": "number" },
+          "taxes": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "rate_id": { "type": "string" },
+                "total": { "type": "number" },
+                "subtotal": { "type": "number" }
+              }
+            }
+          },
+          "attributes": {
+            "type": "array",
+            "description": "Chosen variation attributes for display",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": { "type": "string" },
+                "option": { "type": "string" }
+              }
+            }
+          },
+          "meta_data": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "key": { "type": "string" },
+                "value": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "shipping_lines": {
+      "type": "array",
+      "description": "Chosen shipping methods",
+      "items": {
+        "type": "object",
+        "properties": {
+          "line_id": { "type": "string" },
+          "method_id": { "type": "string", "description": "flat_rate|free_shipping|local_pickup" },
+          "instance_id": { "type": "string", "description": "ShippingZoneMethod id" },
+          "method_title": { "type": "string" },
+          "total": { "type": "number" },
+          "total_tax": { "type": "number" },
+          "taxes": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "rate_id": { "type": "string" },
+                "total": { "type": "number" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "tax_lines": {
+      "type": "array",
+      "description": "Aggregated tax totals per rate",
+      "items": {
+        "type": "object",
+        "properties": {
+          "rate_id": { "type": "string" },
+          "rate_code": { "type": "string" },
+          "label": { "type": "string" },
+          "rate_percent": { "type": "number" },
+          "compound": { "type": "boolean" },
+          "tax_total": { "type": "number" },
+          "shipping_tax_total": { "type": "number" }
+        }
+      }
+    },
+    "fee_lines": {
+      "type": "array",
+      "description": "Additional fees",
+      "items": {
+        "type": "object",
+        "properties": {
+          "line_id": { "type": "string" },
+          "name": { "type": "string" },
+          "tax_class": { "type": "string" },
+          "tax_status": { "type": "string", "enum": ["taxable", "none"] },
+          "total": { "type": "number" },
+          "total_tax": { "type": "number" }
+        }
+      }
+    },
+    "coupon_lines": {
+      "type": "array",
+      "description": "Applied coupons",
+      "items": {
+        "type": "object",
+        "properties": {
+          "code": { "type": "string" },
+          "coupon_id": { "type": "string" },
+          "discount": { "type": "number" },
+          "discount_tax": { "type": "number" },
+          "free_shipping": { "type": "boolean" }
+        }
+      }
+    },
+    "discount_total": { "type": "number", "default": 0 },
+    "discount_tax": { "type": "number", "default": 0 },
+    "shipping_total": { "type": "number", "default": 0 },
+    "shipping_tax": { "type": "number", "default": 0 },
+    "cart_tax": { "type": "number", "default": 0 },
+    "total_tax": { "type": "number", "default": 0 },
+    "subtotal": { "type": "number", "default": 0, "description": "Sum of line subtotals, ex tax" },
+    "total": { "type": "number", "default": 0, "description": "Grand total incl. tax and shipping" },
+    "total_refunded": {
+      "type": "number",
+      "default": 0,
+      "description": "Sum of refunds. Maintained by commerce/admin-refunds."
+    },
+    "stock_reduced": {
+      "type": "boolean",
+      "default": false,
+      "description": "Lifecycle flag guarding double stock reduce/restore"
+    },
+    "coupon_usages_counted": {
+      "type": "boolean",
+      "default": false,
+      "description": "Lifecycle flag guarding double coupon usage counting"
+    },
+    "download_permissions_granted": {
+      "type": "boolean",
+      "default": false,
+      "description": "Lifecycle flag guarding duplicate download permission grants"
+    },
+    "hold_expires_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Unpaid-order stock hold deadline; expired holds are released opportunistically"
+    },
+    "emails_sent": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Email types already fired for this order, prevents duplicates"
+    },
+    "meta_data": {
+      "type": "array",
+      "description": "Custom key/value metadata",
+      "items": {
+        "type": "object",
+        "properties": {
+          "key": { "type": "string" },
+          "value": { "type": "string" }
+        }
+      }
+    }
+  },
+  "required": ["status", "currency"],
+  "rls": {
+    "read": { "user_condition": { "role": "admin" } },
+    "create": { "user_condition": { "role": "admin" } },
+    "update": { "user_condition": { "role": "admin" } },
+    "delete": { "user_condition": { "role": "admin" } }
+  }
+}

package/base44/entities/commerce.OrderNote.jsonc

@@ -0,0 +1,31 @@
+{
+  "name": "commerce.OrderNote",
+  "type": "object",
+  "description": "Note attached to an order: system, private admin, or customer-facing. Customer notes are served to buyers via commerce/storefront-account.",
+  "properties": {
+    "order_id": {
+      "type": "string",
+      "description": "Order id"
+    },
+    "note": {
+      "type": "string",
+      "description": "Note content"
+    },
+    "is_customer_note": {
+      "type": "boolean",
+      "default": false,
+      "description": "Customer-facing note (triggers customer_note email)"
+    },
+    "added_by": {
+      "type": "string",
+      "description": "\"system\" or the admin's email"
+    }
+  },
+  "required": ["order_id", "note"],
+  "rls": {
+    "read": { "user_condition": { "role": "admin" } },
+    "create": { "user_condition": { "role": "admin" } },
+    "update": { "user_condition": { "role": "admin" } },
+    "delete": { "user_condition": { "role": "admin" } }
+  }
+}

package/base44/entities/commerce.OrderRefund.jsonc

@@ -0,0 +1,64 @@
+{
+  "name": "commerce.OrderRefund",
+  "type": "object",
+  "description": "A full or partial refund of an order. Created via commerce/admin-refunds, which also maintains order.total_refunded and optional restocking.",
+  "properties": {
+    "order_id": {
+      "type": "string",
+      "description": "Order id"
+    },
+    "amount": {
+      "type": "number",
+      "description": "Total amount refunded"
+    },
+    "reason": {
+      "type": "string"
+    },
+    "refunded_by": {
+      "type": "string",
+      "description": "Admin email"
+    },
+    "refunded_payment": {
+      "type": "boolean",
+      "default": false,
+      "description": "True when a real gateway refund was made (Stripe wiring placeholder — see skills/commerce/references/online-payments.md)"
+    },
+    "restock_items": {
+      "type": "boolean",
+      "default": false,
+      "description": "Whether refunded line quantities were restocked"
+    },
+    "line_items": {
+      "type": "array",
+      "description": "Per-line refund breakdown; line_id references Order.line_items",
+      "items": {
+        "type": "object",
+        "properties": {
+          "line_id": { "type": "string" },
+          "product_id": { "type": "string" },
+          "variation_id": { "type": "string" },
+          "quantity": { "type": "integer" },
+          "refund_total": { "type": "number" },
+          "refund_tax": { "type": "number" }
+        }
+      }
+    },
+    "meta_data": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "key": { "type": "string" },
+          "value": { "type": "string" }
+        }
+      }
+    }
+  },
+  "required": ["order_id", "amount"],
+  "rls": {
+    "read": { "user_condition": { "role": "admin" } },
+    "create": { "user_condition": { "role": "admin" } },
+    "update": { "user_condition": { "role": "admin" } },
+    "delete": { "user_condition": { "role": "admin" } }
+  }
+}

package/base44/entities/commerce.PaymentGateway.jsonc

@@ -0,0 +1,48 @@
+{
+  "name": "commerce.PaymentGateway",
+  "type": "object",
+  "description": "Payment gateway configuration (data model only — no processing). Seeded: bacs, cheque, cod, stripe (placeholder). Secrets are never stored here; use Base44 secrets.",
+  "properties": {
+    "slug": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Unique gateway id, e.g. bacs | cheque | cod | stripe"
+    },
+    "title": {
+      "type": "string",
+      "description": "Customer-facing title shown at checkout"
+    },
+    "description": {
+      "type": "string",
+      "description": "Customer-facing description/instructions shown at checkout"
+    },
+    "enabled": {
+      "type": "boolean",
+      "default": false
+    },
+    "order": {
+      "type": "integer",
+      "default": 0,
+      "description": "Display order at checkout and in admin"
+    },
+    "method_title": {
+      "type": "string",
+      "description": "Admin-facing label"
+    },
+    "method_description": {
+      "type": "string",
+      "description": "Admin-facing description"
+    },
+    "settings": {
+      "type": "object",
+      "description": "Per-gateway settings. bacs: {account_details: [{account_name, account_number, bank_name, sort_code, iban, bic}]}; cod: {enable_for_methods, enable_for_virtual}; stripe: {connector: \"stripe\"} placeholder — see skills/commerce/references/online-payments.md"
+    }
+  },
+  "required": ["slug"],
+  "rls": {
+    "read": { "user_condition": { "role": "admin" } },
+    "create": { "user_condition": { "role": "admin" } },
+    "update": { "user_condition": { "role": "admin" } },
+    "delete": { "user_condition": { "role": "admin" } }
+  }
+}