Sales Document Transformation Flow

Context

In Sage Active, sales documents follow a natural business lifecycle.
A document can be transformed into another while preserving the functional link between them.

This transformation mechanism is not handled by a dedicated mutation.
Instead, it relies on the standard creation mutations while providing origin metadata that allows the API to:

• create the relationship between documents
• keep traceability across the sales flow
• update the remaining quantities available on the source document lines

Supported transformation paths

Principle

To transform a document, you do not use a specific transformation mutation.

You use the usual mutations:

• createSalesOrder
• createSalesDeliveryNote
• createSalesInvoice

And you provide three additional fields on each line to indicate the origin of the created lines.

Because these fields are available at line level, a target document can be created from multiple source documents.

This enables advanced scenarios such as:

• creating one Delivery Note from multiple Sales Orders
• creating one Invoice from multiple Delivery Notes or from multiple Quotes or Orders

Each line keeps its own origin, ensuring full traceability and correct quantity management.

mutation ($values: SalesOrderCreateGLDtoInput!) {
  createSalesOrder(input: $values) {
    id
    operationalNumber
  }
}

{
  "values": {
    "customerId": "{{customerId}}",
    "lines": [
      {
        "productId": "{{productId_1}}",
        "totalQuantity": 2,
        "unitPrice": 11,
        "originType": "QUOTE",
        "originId": "{{salesQuoteId}}",
        "originLineId": "{{salesQuoteLineId}}"
      }
    ]
  }
}

mutation ($values: SalesDeliveryNoteCreateGLDtoInput!) {
  createSalesDeliveryNote(input: $values) {
    id
    operationalNumber
  }
}

{
  "values": {
    "customerId": "{{customerId}}",
    "lines": [
      {
        "productId": "{{productId_1}}",
        "totalQuantity": 5,
        "unitPrice": 20,
        "originType": "ORDER",
        "originId": "{{salesOrderId_1}}",
        "originLineId": "{{salesOrderLineId_1}}"
      },
      {
        "productId": "{{productId_2}}",
        "totalQuantity": 3,
        "unitPrice": 18,
        "originType": "ORDER",
        "originId": "{{salesOrderId_2}}",
        "originLineId": "{{salesOrderLineId_2}}"
      }
    ]
  }
}

mutation ($values: SalesInvoiceCreateGLDtoInput!) {
  createSalesInvoice(input: $values) {
    id
    operationalNumber
  }
}

{
  "values": {
    "customerId": "{{customerId}}",
    "lines": [
      {
        "productId": "{{productId_1}}",
        "totalQuantity": 5,
        "unitPrice": 20,
        "originType": "DELIVERY_NOTE",
        "originId": "{{deliveryNoteId}}",
        "originLineId": "{{deliveryNoteLineId}}"
      }
    ]
  }
}

Important behavior

When using originType, originId, and originLineId on lines:

• The API validates that the transformation path is allowed
• The quantity may exceed the remaining quantity of the origin line
• However, the origin document must be in Pending status in order to be referenced by another document.
• Multiple target documents can be created from the same origin document, as long as the origin lines are not completed
• For Invoice creation from Delivery Notes, there is no notion of pendingQuantity on Delivery Note lines
  As soon as a Delivery Note line is used, it becomes Completed and cannot be used again for another Invoice
• The relationship is visible through the RelatedSalesDocument resource

Recommendation

Always use these fields on lines when creating a document that originates from another sales document. Failing to do so will create a standalone document with no traceability and no quantity control against the source document.