@tailor-platform/erp-kit 0.4.0 → 0.5.0

package/src/modules/sales/docs/commands/ActivateSalesPaymentTerm.md

@@ -0,0 +1,41 @@
+# ActivateSalesPaymentTerm
+
+## Overview
+
+ActivateSalesPaymentTerm moves a draft SalesPaymentTerm into ACTIVE status so it can participate in downstream commercial processing.
+
+## Business Rules
+
+- Only DRAFT SalesPaymentTerm records may be activated.
+- At least one schedule line is required.
+- Percentage-based schedules must total 100 percent.
+- Discount cutoff must not fall after the final due date.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate request] --> B[Load SalesPaymentTerm]
+    B --> C{Status is DRAFT?}
+    C -->|No| D[Return INVALID_SALESPAYMENTTERM_STATUS]
+    C -->|Yes| E[Validate activation prerequisites]
+    E --> F[Set status to ACTIVE]
+    F --> G[Return activated SalesPaymentTerm]
+```
+
+## External Dependencies
+
+- [organization::GetCompany](../../../organization/docs/queries/GetCompany.md) - Validate company scope for the term.
+
+## Error Scenarios
+
+- **SALESPAYMENTTERM_NOT_FOUND**: Referenced SalesPaymentTerm does not exist.
+- **INVALID_SALESPAYMENTTERM_STATUS**: Only DRAFT SalesPaymentTerm records may be activated.
+- **INVALID_PAYMENT_SCHEDULE**: Schedule lines do not satisfy payment-term rules.
+
+## Test Cases
+
+- activates a draft SalesPaymentTerm
+- throws when SalesPaymentTerm is not in DRAFT status
+- throws when SalesPaymentTerm does not exist
+- throws on invalid payment schedule

package/src/modules/sales/docs/commands/ActivateSalesPriceList.md

@@ -0,0 +1,39 @@
+# ActivateSalesPriceList
+
+## Overview
+
+ActivateSalesPriceList moves a draft SalesPriceList into ACTIVE status so it can participate in downstream commercial processing.
+
+## Business Rules
+
+- Only DRAFT SalesPriceList records may be activated.
+- Company must be ACTIVE or otherwise eligible for commercial configuration.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate request] --> B[Load SalesPriceList]
+    B --> C{Status is DRAFT?}
+    C -->|No| D[Return INVALID_SALESPRICELIST_STATUS]
+    C -->|Yes| E[Validate activation prerequisites]
+    E --> F[Set status to ACTIVE]
+    F --> G[Return activated SalesPriceList]
+```
+
+## External Dependencies
+
+- [organization::GetCompany](../../../organization/docs/queries/GetCompany.md) - Validate company scope for the price list.
+
+## Error Scenarios
+
+- **SALESPRICELIST_NOT_FOUND**: Referenced SalesPriceList does not exist.
+- **INVALID_SALESPRICELIST_STATUS**: Only DRAFT SalesPriceList records may be activated.
+- **COMPANY_NOT_FOUND**: Referenced company does not exist.
+
+## Test Cases
+
+- activates a draft SalesPriceList
+- throws when SalesPriceList is not in DRAFT status
+- throws when SalesPriceList does not exist
+- throws when the referenced company does not exist

package/src/modules/sales/docs/commands/ActivateSalesPriceRule.md

@@ -0,0 +1,48 @@
+# ActivateSalesPriceRule
+
+## Overview
+
+ActivateSalesPriceRule moves a draft SalesPriceRule into ACTIVE status so it can participate in downstream commercial processing.
+
+## Business Rules
+
+- Only DRAFT SalesPriceRule records may be activated.
+- Unit price must be positive.
+- Effective end date cannot precede start date.
+- Minimum quantity cannot be negative.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate request] --> B[Load SalesPriceRule]
+    B --> C{Status is DRAFT?}
+    C -->|No| D[Return INVALID_SALESPRICERULE_STATUS]
+    C -->|Yes| E[Validate activation prerequisites]
+    E --> F[Set status to ACTIVE]
+    F --> G[Return activated SalesPriceRule]
+```
+
+## External Dependencies
+
+- [item-management::GetItem](../../../item-management/docs/queries/GetItem.md) - Validate the referenced sellable item.
+- [primitives::GetCurrency](../../../primitives/docs/queries/GetCurrency.md) - Validate currency assignment.
+- [primitives::GetUnit](../../../primitives/docs/queries/GetUnit.md) - Validate sales UoM assignment.
+- [getSalesPriceList](../queries/GetSalesPriceList.md) - Validate parent price-list scope.
+
+## Error Scenarios
+
+- **SALESPRICERULE_NOT_FOUND**: Referenced SalesPriceRule does not exist.
+- **INVALID_SALESPRICERULE_STATUS**: Only DRAFT SalesPriceRule records may be activated.
+- **PRICE_LIST_NOT_FOUND**: Parent sales price list does not exist.
+- **INVALID_UNIT_PRICE**: Unit price must be greater than zero.
+- **INVALID_EFFECTIVE_RANGE**: Effective end date precedes start date.
+
+## Test Cases
+
+- activates a draft SalesPriceRule
+- throws when SalesPriceRule is not in DRAFT status
+- throws when SalesPriceRule does not exist
+- throws when the parent price list does not exist
+- throws on invalid unit price
+- throws on invalid effective date range

package/src/modules/sales/docs/commands/CancelChannelOrder.md

@@ -0,0 +1,37 @@
+# CancelChannelOrder
+
+## Overview
+
+CancelChannelOrder records channel-originated cancellation before internal execution progresses too far. It preserves external traceability and prevents stale conversion jobs from materializing cancelled demand.
+
+## Business Rules
+
+- Pending or exceptional channel orders may be cancelled by the originating channel.
+- Cancellation must block later stale conversion attempts for the same channel order.
+- If an internal sales order already exists, downstream sales cancellation policy must be followed separately.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive channel cancellation] --> B[Load channel order]
+    B --> C{Cancellation allowed?}
+    C -->|No| D[Return INVALID_CHANNEL_ORDER_STATUS]
+    C -->|Yes| E[Set status to CANCELLED_BY_CHANNEL]
+    E --> F[Return cancelled channel order]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **CHANNEL_ORDER_NOT_FOUND**: Referenced channel order does not exist.
+- **INVALID_CHANNEL_ORDER_STATUS**: Channel-order status does not allow channel-side cancellation.
+
+## Test Cases
+
+- cancels a pending channel order
+- cancels an exceptional channel order before replay
+- prevents stale conversion after cancellation

package/src/modules/sales/docs/commands/CancelSalesInvoice.md

@@ -0,0 +1,39 @@
+# CancelSalesInvoice
+
+## Overview
+
+CancelSalesInvoice cancels a draft or issued invoice while the commercial document is still owned by sales. It is blocked once downstream AR handoff has been accepted.
+
+## Business Rules
+
+- Only DRAFT or ISSUED invoices may be cancelled.
+- Invoices already accepted by downstream AR cannot be cancelled through this command.
+- Cancellation must preserve historical invoice lines and issue evidence.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive cancel request] --> B[Load invoice]
+    B --> C[Check invoice status and AR handoff state]
+    C --> D{Cancellation allowed?}
+    D -->|No| E[Return INVOICE_CANCELLATION_BLOCKED]
+    D -->|Yes| F[Set status to CANCELLED]
+    F --> G[Return cancelled invoice]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **SALES_INVOICE_NOT_FOUND**: Referenced sales invoice does not exist.
+- **INVALID_INVOICE_STATUS**: Invoice status does not allow cancellation.
+- **INVOICE_CANCELLATION_BLOCKED**: Downstream AR handoff already accepted the invoice.
+
+## Test Cases
+
+- cancels a draft invoice
+- cancels an issued invoice before AR handoff
+- throws when AR handoff already accepted the invoice

package/src/modules/sales/docs/commands/CancelSalesOrder.md

@@ -0,0 +1,40 @@
+# CancelSalesOrder
+
+## Overview
+
+CancelSalesOrder voids a sales order that should no longer proceed. It preserves audit history while preventing further execution on the commercial document.
+
+## Business Rules
+
+- Orders with posted shipment or issued invoice evidence cannot be cancelled through this command.
+- Draft, submitted, confirmed, and held orders may be cancelled when irreversible downstream execution has not occurred.
+- Cancellation must preserve historical order and line references for audit purposes.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive cancel request] --> B[Load sales order]
+    B --> C[Check shipment and invoice progress]
+    C --> D{Downstream evidence exists?}
+    D -->|Yes| E[Return CANCELLATION_BLOCKED]
+    D -->|No| F[Set status to CANCELLED]
+    F --> G[Return cancelled order]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **SALES_ORDER_NOT_FOUND**: Referenced sales order does not exist.
+- **INVALID_ORDER_STATUS**: Order status does not allow cancellation.
+- **CANCELLATION_BLOCKED**: Posted shipment or issued invoice evidence already exists.
+
+## Test Cases
+
+- cancels a draft order
+- cancels a confirmed order with no shipment or invoice evidence
+- throws when posted shipment evidence exists
+- throws when issued invoice evidence exists

package/src/modules/sales/docs/commands/CancelSyncJob.md

@@ -0,0 +1,36 @@
+# CancelSyncJob
+
+## Overview
+
+CancelSyncJob stops a running sync execution when policy allows. It preserves timing and count context already collected by the job.
+
+## Business Rules
+
+- Only RUNNING sync jobs may be cancelled.
+- Cancellation must preserve processed counts and error context already recorded.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive cancel request] --> B[Load sync job]
+    B --> C{Status is RUNNING?}
+    C -->|No| D[Return INVALID_SYNC_JOB_STATUS]
+    C -->|Yes| E[Mark sync job as CANCELLED]
+    E --> F[Return cancelled job]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **SYNC_JOB_NOT_FOUND**: Referenced sync job does not exist.
+- **INVALID_SYNC_JOB_STATUS**: Only RUNNING sync jobs may be cancelled.
+
+## Test Cases
+
+- cancels a running sync job
+- preserves existing counts and error context when cancelled
+- throws when sync job is not running

package/src/modules/sales/docs/commands/CloseSalesOrder.md

@@ -0,0 +1,39 @@
+# CloseSalesOrder
+
+## Overview
+
+CloseSalesOrder marks the commercial commitment as complete once no meaningful open balance remains. It is used when all obligations are fulfilled or the residual balance has been cancelled or written off according to policy.
+
+## Business Rules
+
+- Only executable or post-execution orders may be closed.
+- All remaining open quantities must be fulfilled, cancelled, or written off before closure.
+- Closing the order must preserve line-level shipped and invoiced history.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive close request] --> B[Load sales order]
+    B --> C[Calculate remaining open balance]
+    C --> D{Open balance cleared?}
+    D -->|No| E[Return ORDER_NOT_CLOSABLE]
+    D -->|Yes| F[Set status to CLOSED]
+    F --> G[Return closed order]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **SALES_ORDER_NOT_FOUND**: Referenced sales order does not exist.
+- **INVALID_ORDER_STATUS**: Order status does not allow closure.
+- **ORDER_NOT_CLOSABLE**: Remaining open balance still exists.
+
+## Test Cases
+
+- closes an order with no remaining open balance
+- throws when remaining quantity is still open
+- throws when order status does not allow closure

package/src/modules/sales/docs/commands/ConfirmSalesOrder.md

@@ -0,0 +1,43 @@
+# ConfirmSalesOrder
+
+## Overview
+
+ConfirmSalesOrder freezes the commercial commitment and makes the sales order executable. It snapshots the applied price, payment-term, and customer-facing context that downstream shipment and invoice flows must honor.
+
+## Business Rules
+
+- Only SUBMITTED orders may be confirmed.
+- Customer must still be ACTIVE and valid for sales use at confirmation time.
+- Each line must preserve a final unit price and currency before confirmation succeeds.
+- Confirmation freezes mutable commercial fields until an explicit revision workflow exists.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive confirm request] --> B[Load submitted order]
+    B --> C[Revalidate customer, lines, pricing, and payment term]
+    C --> D[Snapshot final commercial context]
+    D --> E[Set status to CONFIRMED]
+    E --> F[Return confirmed order]
+```
+
+## External Dependencies
+
+- [business-partner::GetPartner](../../../business-partner/docs/queries/GetPartner.md) - Revalidate customer activity and role status.
+- [getApplicableSalesPrice](../queries/GetApplicableSalesPrice.md) - Validate matched pricing context where a default rule exists.
+- [getSalesPaymentTerm](../queries/GetSalesPaymentTerm.md) - Revalidate payment-term assignment before snapshotting.
+
+## Error Scenarios
+
+- **SALES_ORDER_NOT_FOUND**: Referenced sales order does not exist.
+- **INVALID_ORDER_STATUS**: Only SUBMITTED orders may be confirmed.
+- **CUSTOMER_NOT_ACTIVE**: Customer is no longer active for sales use.
+- **MISSING_FINAL_PRICE**: A line lacks final price or currency information.
+
+## Test Cases
+
+- confirms a submitted order and snapshots commercial context
+- throws when order is not submitted
+- throws when customer became inactive before confirmation
+- throws when a line lacks final pricing data

package/src/modules/sales/docs/commands/ConvertChannelOrder.md

@@ -0,0 +1,44 @@
+# ConvertChannelOrder
+
+## Overview
+
+ConvertChannelOrder materializes or links the internal sales order for a pending channel order once required mappings succeed. It is the write path that moves normalized external demand into the standard sales-order lifecycle without bypassing sales rules.
+
+## Business Rules
+
+- Only PENDING_CONVERSION channel orders may be converted.
+- Required customer, listing, item, currency, and company mappings must be valid before conversion.
+- Successful conversion must create or update the internal sales order before the channel order moves to CONVERTED.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive convert request] --> B[Load pending channel order]
+    B --> C[Validate customer, listing, item, and currency mappings]
+    C --> D{Mappings valid?}
+    D -->|No| E[Return CHANNEL_ORDER_MAPPING_FAILED]
+    D -->|Yes| F[Create or update SalesOrder]
+    F --> G[Store linked sales order reference and set status to CONVERTED]
+    G --> H[Return converted channel order]
+```
+
+## External Dependencies
+
+- [getChannelOrder](../queries/GetChannelOrder.md) - Load pending conversion context.
+- [business-partner::GetPartner](../../../business-partner/docs/queries/GetPartner.md) - Validate resolved customer mapping.
+- [getListingByExternalIdentifier](../queries/GetListingByExternalIdentifier.md) - Validate listing to item mapping.
+- [primitives::GetCurrency](../../../primitives/docs/queries/GetCurrency.md) - Validate resolved currency.
+
+## Error Scenarios
+
+- **CHANNEL_ORDER_NOT_FOUND**: Referenced channel order does not exist.
+- **INVALID_CHANNEL_ORDER_STATUS**: Only PENDING_CONVERSION channel orders may be converted.
+- **CHANNEL_ORDER_MAPPING_FAILED**: Required customer, listing, item, or currency mapping is missing.
+
+## Test Cases
+
+- converts a pending channel order into a sales order
+- stores linked sales order reference after conversion
+- throws when channel order is not pending conversion
+- throws when required mappings are missing

package/src/modules/sales/docs/commands/CreateChannel.md

@@ -0,0 +1,40 @@
+# CreateChannel
+
+## Overview
+
+CreateChannel creates a draft sales channel for one company and one external sell-side context such as a marketplace or storefront.
+
+## Business Rules
+
+- Record is always created in DRAFT status.
+- Channel type is required.
+- Channel name must be unique enough to avoid operational ambiguity within the company.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B[Validate references and required fields]
+    B --> C{Validation passed?}
+    C -->|No| D[Return validation error]
+    C -->|Yes| E[Insert draft Channel record]
+    E --> F[Return created Channel]
+```
+
+## External Dependencies
+
+- [organization::GetCompany](../../../organization/docs/queries/GetCompany.md) - Validate company scope for the channel.
+
+## Error Scenarios
+
+- **CHANNEL_NOT_FOUND**: Prerequisite context for Channel is missing.
+- **INVALID_CHANNEL_TYPE**: Channel type is missing or unsupported.
+- **DUPLICATE_CHANNEL_NAME**: A conflicting channel name already exists.
+
+## Test Cases
+
+- creates a draft channel with valid type and company
+- throws when required Channel fields are missing
+- creates the Channel in DRAFT status
+- throws when the company does not exist
+- throws when a conflicting channel name already exists

package/src/modules/sales/docs/commands/CreateListing.md

@@ -0,0 +1,40 @@
+# CreateListing
+
+## Overview
+
+CreateListing creates a draft channel listing that maps one internal item into one external channel context. It preserves sellability metadata and external identifier placeholders before activation.
+
+## Business Rules
+
+- Referenced channel and item must exist and belong to the same company scope.
+- The item must be ACTIVE before a listing can be created for new sellability.
+- Listing identity must be unique enough to avoid operational ambiguity within the channel context.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B[Validate channel and item]
+    B --> C[Validate listing identity]
+    C --> D[Insert draft listing]
+    D --> E[Return created listing]
+```
+
+## External Dependencies
+
+- [getChannel](../queries/GetChannel.md) - Validate the target channel exists.
+- [item-management::GetItem](../../../item-management/docs/queries/GetItem.md) - Validate the referenced item exists and is active.
+
+## Error Scenarios
+
+- **CHANNEL_NOT_FOUND**: Referenced channel does not exist.
+- **ITEM_NOT_FOUND**: Referenced item does not exist.
+- **ITEM_NOT_ACTIVE**: Referenced item is not active for listing use.
+- **DUPLICATE_LISTING_IDENTITY**: A conflicting listing identity already exists.
+
+## Test Cases
+
+- creates a draft listing for an active item and valid channel
+- throws when channel does not exist
+- throws when item is inactive
+- throws when listing identity conflicts within the channel

package/src/modules/sales/docs/commands/CreateSalesCreditNote.md

@@ -0,0 +1,37 @@
+# CreateSalesCreditNote
+
+## Overview
+
+CreateSalesCreditNote creates a draft commercial correction document against an issued invoice. It records affected invoice lines or correction amounts before the credit note is issued.
+
+## Business Rules
+
+- Referenced invoice must already be ISSUED.
+- At least one correction line or correction amount is required.
+- Correction lines must reference valid issued invoice lines.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B[Load issued invoice]
+    B --> C[Validate correction lines and reasons]
+    C --> D[Insert draft credit note and lines]
+    D --> E[Return draft credit note]
+```
+
+## External Dependencies
+
+- [getSalesInvoice](../queries/GetSalesInvoice.md) - Validate the invoice being corrected.
+
+## Error Scenarios
+
+- **SALES_INVOICE_NOT_FOUND**: Referenced invoice does not exist.
+- **INVOICE_NOT_ISSUED**: Credit notes require an issued invoice.
+- **INVALID_CREDIT_NOTE_LINE**: Correction line or amount is invalid.
+
+## Test Cases
+
+- creates a draft credit note against an issued invoice
+- throws when invoice is not issued
+- throws when no correction line is provided

package/src/modules/sales/docs/commands/CreateSalesInvoice.md

@@ -0,0 +1,39 @@
+# CreateSalesInvoice
+
+## Overview
+
+CreateSalesInvoice creates a draft customer invoice that references one sales order and one or more invoice lines. It captures the draft billing document before issue-time validation and snapshotting occur.
+
+## Business Rules
+
+- Referenced sales order must exist and belong to the same company as the invoice.
+- At least one invoice line is required.
+- Each invoice line must reference a valid sales-order line and a billed quantity greater than zero.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B[Load sales order]
+    B --> C[Validate invoice lines and customer context]
+    C --> D[Insert draft invoice and invoice lines]
+    D --> E[Return draft invoice]
+```
+
+## External Dependencies
+
+- [getSalesOrder](../queries/GetSalesOrder.md) - Validate the source order and customer context.
+- [getSalesPaymentTerm](../queries/GetSalesPaymentTerm.md) - Resolve the assigned payment term for due schedule generation.
+
+## Error Scenarios
+
+- **SALES_ORDER_NOT_FOUND**: Referenced sales order does not exist.
+- **INVALID_INVOICE_LINE**: Invoice line content is incomplete or invalid.
+- **CROSS_COMPANY_REFERENCE**: Invoice references records from another company.
+
+## Test Cases
+
+- creates a draft invoice for a valid order
+- throws when no invoice lines are provided
+- throws when invoice line references an unknown sales-order line
+- throws when order belongs to another company

package/src/modules/sales/docs/commands/CreateSalesOrder.md

@@ -0,0 +1,51 @@
+# CreateSalesOrder
+
+## Overview
+
+CreateSalesOrder establishes a new sales order in DRAFT status with one or more order lines. It captures the initial customer, company, address, payment-term, pricing, and optional channel context needed to begin the commercial review flow.
+
+## Business Rules
+
+- Order is always created in DRAFT status.
+- Customer must reference an ACTIVE business partner with the CUSTOMER role.
+- At least one order line is required at creation time.
+- Each order line must reference an ACTIVE item, a positive quantity, and a non-negative unit price.
+- All customer, item, site, and channel references must belong to the same company scope.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B[Validate company and customer]
+    B --> C[Validate order lines and references]
+    C --> D[Resolve optional pricing and payment defaults]
+    D --> E[Create SalesOrder and SalesOrderLine records]
+    E --> F[Set status to DRAFT]
+    F --> G[Return created sales order]
+```
+
+## External Dependencies
+
+- [business-partner::GetPartner](../../../business-partner/docs/queries/GetPartner.md) - Validate the referenced customer exists and is active.
+- [item-management::GetItem](../../../item-management/docs/queries/GetItem.md) - Validate each referenced sellable item.
+- [organization::GetSite](../../../organization/docs/queries/GetSite.md) - Validate ship-from or billing-site references when provided.
+- [getApplicableSalesPrice](../queries/GetApplicableSalesPrice.md) - Optionally resolve default draft pricing context.
+- [getSalesPaymentTerm](../queries/GetSalesPaymentTerm.md) - Optionally resolve default payment-term context.
+
+## Error Scenarios
+
+- **CUSTOMER_NOT_FOUND**: Referenced customer does not exist.
+- **CUSTOMER_NOT_ACTIVE**: Referenced customer is not ACTIVE.
+- **CUSTOMER_ROLE_REQUIRED**: Referenced partner does not carry the CUSTOMER role.
+- **ITEM_NOT_FOUND**: One or more referenced items do not exist.
+- **INVALID_ORDER_LINE**: A line is missing quantity, price, or item context.
+- **CROSS_COMPANY_REFERENCE**: One or more referenced records belong to another company.
+
+## Test Cases
+
+- creates a draft sales order with valid customer and lines
+- throws when customer does not exist
+- throws when customer is inactive or lacks CUSTOMER role
+- throws when an order line references an inactive item
+- throws when line quantity is zero or unit price is negative
+- throws when references cross company boundaries

package/src/modules/sales/docs/commands/CreateSalesPaymentTerm.md

@@ -0,0 +1,38 @@
+# CreateSalesPaymentTerm
+
+## Overview
+
+CreateSalesPaymentTerm creates a draft payment-term definition with one or more schedule lines and optional early-payment discount metadata.
+
+## Business Rules
+
+- Record is always created in DRAFT status.
+- At least one schedule line is required.
+- Percentage-based schedules must total 100 percent.
+- Discount cutoff must not fall after the final due date.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B[Validate references and required fields]
+    B --> C{Validation passed?}
+    C -->|No| D[Return validation error]
+    C -->|Yes| E[Insert draft SalesPaymentTerm record]
+    E --> F[Return created SalesPaymentTerm]
+```
+
+## External Dependencies
+
+- [organization::GetCompany](../../../organization/docs/queries/GetCompany.md) - Validate company scope for the term.
+
+## Error Scenarios
+
+- **SALESPAYMENTTERM_NOT_FOUND**: Prerequisite context for SalesPaymentTerm is missing.
+- **INVALID_PAYMENT_SCHEDULE**: Schedule lines do not satisfy payment-term rules.
+
+## Test Cases
+
+- creates a payment term with valid schedule lines
+- throws when required SalesPaymentTerm fields are missing
+- creates the SalesPaymentTerm in DRAFT status