PurchaseInvoice

Quick Links

Accounts Accounting Entries Products Customers Sales quotes Sales invoices Suppliers Purchase invoices

HTTP Operation Type Object DTO Why-DTOs?
Mutation Why 200? createPurchaseInvoice PurchaseInvoiceCreateGLDtoInput
Mutation Why 200? updatePurchaseInvoice How to update? PurchaseInvoiceUpdateGLDtoInput
Mutation Why 200? deletePurchaseInvoice PurchaseInvoiceDeleteGLDtoInput
Query purchaseInvoices filtered by id Why?  
Query purchaseInvoices  

Description

Both known as Purchase Invoices in the API context and in the product interface.
This resource is pivotal for managing payments to suppliers after receiving goods or services and serves as a legally binding documentation of the purchase.

The Purchase Invoices entity utilizes a simplified model that primarily includes key information of the purchase invoice: invoice number, invoice date, fulfillment date, total amount, amount excluding tax, and taxes.

In addition, via AP Automation, it is possible to upload supplier invoices as PDF or image files (and XML files for DE legislation).
The uploaded document is analyzed by the OCR engine, which automatically creates a corresponding purchase invoice draft linked to the file through the fileId and fileName fields.
This process significantly reduces manual data entry and speeds up the recording of supplier invoices in Sage Active.

img

Workflow

  1. Create the Invoice and Optionally View or Modify It: Start by creating a purchase invoice using the PurchaseInvoice service.
    Once created, you can view and make any necessary modifications to the invoice before finalizing it.

  2. Post the Invoice to Generate Accounting Entries: Proceed with posting the invoice using the PostPurchaseInvoice service.
    Posting the invoice will generate the necessary accounting entries, making the invoice part of the company’s financial records.

  3. View the Invoice’s Payment Due Dates: Check the payment due dates and related information using the PurchaseInvoiceOpenItems service.
    This allows you to see when payments are expected and track outstanding amounts for the invoice.

  4. Apply Partial or Full Payments to the Invoice: Manage the payments on the invoice by using the PurchaseOpenItemSettlement service.
    You can apply both partial and full payments, keeping track of amounts paid and any remaining balances.


To see examples of mutations that include the adding of Purchase :
download the Postman collection: Quick start / 5. Test your first query in Postman

graphQL Mutation
mutation ($values: PurchaseCreateGLDtoInput!) {  
    createPurchaseInvoice(input: $values) {
    id
  }
}
graphQL Variables
{
  "values": {
    "supplierId": "b647b9e4-6d2a-4c9d-96e3-54be55457096",
    "invoiceDate": "2024-08-19",
    "invoiceNumber": "AA123",
    "totalLiquid": 240,
    "hasCashVat": false,
    "operationDate": "2024-08-19T00:00:00+00:00",
    "vatLines": [
      {
        "invoiceDate": "2024-08-19T00:00:00+00:00",
        "vatPercentage": 20,
        "totalVat": 40,
        "totalVatBase": 200
      }
    ]
  }
}
Example of Response
{
    "data": {
        "createPurchaseInvoice": {
            "id": "e451aff7-074f-4e72-a6fb-4ea25e9d9c64"
        }
    }
}
graphQL Mutation
mutation ($values: PurchaseCreateGLDtoInput!) {  
    createPurchaseInvoice(input: $values) {
    id
  }
}
graphQL Variables
{
  "values": {
    "supplierId": "b647b9e4-6d2a-4c9d-96e3-54be55457096",
    "invoiceDate": "2024-08-19",
    "invoiceNumber": "AA123",
    "totalLiquid": 240,
    "hasCashVat": false,
    "operationDate": "2024-08-19T00:00:00+00:00",
    "vatLines": [
      {
        "invoiceDate": "2024-08-19T00:00:00+00:00",
        "totalVat": 40,
        "totalVatBase": 200
        "purchaseAccountingAccountId":"550e8400-e29b-41d4-a716-446655440000",
        "taxId":"f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "taxTreatmentId":"9a19d7f2-c524-41fc-9e7f-d59775cd8953"
      }
    ]
  }
}
Example of Response
{
    "data": {
        "createPurchaseInvoice": {
            "id": "e451aff7-074f-4e72-a6fb-4ea25e9d9c64"
        }
    }
}
Key Value
Authorization Bearer Current access Token How to find?
X-TenantId Current tenant id Why deprecated ?
X-OrganizationId Current organization Id How to find?
x-api-key Primary or secondary subscription key of your app How to find?

purchaseInvoices

Fields Type Description Length
id UUID ID  
creationDate DateTime Creation Date  
modificationDate DateTime Modification Date  
sourceType
  • null
  • AP_AUTOMATION
  • PUBLIC_API
  • SAGE_MOBILE_APP_AP_AUTOMATION
  • PUBLIC_API_AP_AUTOMATION
  • EMAIL_AP_AUTOMATION
  • E_INVOICING_AP_AUTOMATION
 indicates the origin of the purchaseInvoice (null=Manual Entry )  
       
invoiceDate DateTime Date when the invoice was issued  
firstDueDate DateTime The first due date for payment of the invoice  
invoiceNumber String Document number of the invoice 50
operationDate DateTime Fulfillment date  
supplier Supplier Fields of supplier  
supplierId UUID ID of the supplier entity  
pendingAmount Decimal Amount still due on the invoice  
status String
  • Pending
  • Closed
  • Posted
  • PartiallyPaid
  • Paid
  • Uploading
  • SbdRejected
  
eInvoicingStatus
  • NEW
  • CREATED
  • SUBMITTED
  • ISSUE_BY_THE_PLATFORM
  • PAYMENT_RECEIVED
  • COMPLETED
  • RECEIVED_BY_PLATFORM
  • MADE_AVAILABLE
  • IN_HAND
  • APPROVED
  • REFUSED
  • PARTIALLY_APPROVED
  • PAYMENT_SENT
  • REJECTED
  • DISPUTED
  • SUSPENDED
  • FAILED_TO_SEND
  • RECEIVED
 Standardized status for e-invoicing that enables tracking of the invoice lifecycle  
description String Provides additional details about the current status  
totalLiquid Decimal Total amount due including taxes  
hasCashVat Boolean Indicates if the invoice is subject to Cash VAT  
       
fileId String ID of the file used for OCR recognition  
fileName String Name of the file used for OCR recognition 255
       
vatLines[] Array Vat lines of purchase Invoice  
openItems[] Array Open items of purchase Invoice  
Info
  • operationDate: The date cannot be later than the invoice date.
  • status
    • OCR Recognization
      • Uploading: The invoice has been created but only contains the file name; it has not yet been processed.
      • SbdRejected: It is returned when the uploaded document was rejected by the antivirus (for example, if the file was password-protected or infected).
    • Purchase Invoice
      • Pending: (Pending) The invoice can be modified; it has not yet been transferred to accounting.
      • Closed: (Pending) The invoice was supposed to be transferred to accounting, but the operation failed or was canceled.
      • Posted: (Awaiting payment) The invoice can no longer be modified; it has been transferred to accounting.
      • PartiallyPaid: (Partially paid) The invoice is partially paid. Payments are pending.
      • Paid: (Paid) The invoice is fully paid.
    Attention!

    The Sage Active interface overrides the values Posted and PartiallyPaid of the status field with Overdue and PartiallyOverdue if the value of the firstDueDate field is earlier than the current date.
    However, these values Overdue and PartiallyOverdue are not returned by the API, which instead returns Posted and PartiallyPaid, respectively.

    To filter invoices that are overdue, you can use the following filter, replacing the date with the desired date (e.g., the current date or the current date minus a few days to allow for a grace period in overdue days):

    query {
  purchaseInvoices(
    where: {
      status: { in: ["Posted","PartiallyPaid"] }
      firstDueDate: { lt: "2024-10-09" }
    }
  )
}
  • eInvoicingStatus:
    • Standardized status for e-invoicing that enables tracking of the invoice lifecycle.
    • Unused for the Spanish market.
    • Unused for the German market.
  • description: Returns a message in the form of a businessErrors code.
    For example:
    • sales.businessErrors.simplifiedPurchaseInvoiceOcrStatusErrorMessage → “Data extraction unsuccessful. Enter manually the required information to post the invoice.”
    • sales.businessErrors.simplifiedPurchaseInvoiceManuallyAddedMessage → “Enter the required information to post the invoice.”

    Although these values are returned under businessErrors, they do not always represent an error.
    You can use localizedErrorMessage to resolve the associated label in the desired language.

  • fileId: Id of the file used for OCR recognition. Example value: 4dd0a4792b404a3abd50b5991a381990.pdf

  • fileName: Name of the file used for OCR recognition. Example value: invoice2025-01-1200.pdf

    File information can also be retrieved directly via files by applying a filter on id.

    query ($fileId: String!) {
  files(
    where: { id: { eq: $fileId } }
  ) {
    edges {
      node {
        fileName
        type
        size
        downloadPath
        previewPath
        # other fields
      }
    }
  }
}

purchaseInvoices/vatLines

Fields Type Description Length
id UUID ID  
creationDate DateTime Creation Date  
modificationDate DateTime IModification Date  
       
vatPercentage Decimal VAT percentage (only for mutations)  
totalVat Decimal Total VAT amount calculated for the invoice.  
totalVatBase Decimal Total VAT base amount (before tax) for the invoice.  
invoiceDate 1 DateTime Date when the invoice was issued  
tax Tax Fields of Tax including percentage  
taxId UUID ID for the tax applied to the invoice.  
taxTreatment TaxTreatment Fields of TaxTreatment  
taxTreatmentId UUID ID for the tax treatment applied to the invoice  
purchaseAccountingAccount AccountingAccount Fields of AccountingAccount  
purchaseAccountingAccountId UUID ID Account  
       
transactionCategory Category Fields of TransactionCategory  
transactionCategoryId UUID Transaction category used to determine default accounting settings  
Info
  • vatPercentage: The percentage of VAT applicable to this line.
    Used only for mutations to simplify specifying the tax percentage for the line.
    In this case, taxId should not be provided, as it will be automatically inferred based on the VAT percentage.
  • taxId: The unique identifier of the tax to be applied.
    Not required in mutations if vatPercentage is set, as the system will select the appropriate tax automatically based on the VAT percentage.
  • taxTreatmentId: The ID of the tax treatment that determines how the tax is handled.
    Optional in mutations, if not specified the system will select the first tax treatment consistent with the tax rate automatically.
  • purchaseAccountingAccountId: The ID of the accounting account applicable to this line.
    Optional in mutations, if not specified the system will automatically choose the first account consistent with the tax rate.

  • transactionCategoryId:

    This field references a transaction category of type PURCHASE, used to determine default accounting settings for the invoice line.
    Each transaction category is associated with a default purchase account and a tax treatment.

    At the moment, this field is available in read-only mode only.
    Data entry will be supported in a future version, allowing interfaces to let users select a purchase transaction category and automatically derive the related accounting and tax configuration, similar to the behavior in the Sage Active web application.

  • taxes{percentage}: In queries, this allows retrieving the tax percentage, as vatPercentage is only available for mutations.

purchaseInvoices/openItems

An Open Item is a financial transaction that allows you to know if it has been fully settled or paid.
Each open item includes detailed information such as the total amount, accumulated amount paid, and the payment due date.

For a single invoice, there can be as many open items as there are different payment installments, which is why openItems is structured as an array to accommodate multiple entries per invoice.

The payment status provides insight into the progress of settling each item.
Additionally, the identifier of the payment method used is provided to track the settlement method.

img

Fields Type Description
id UUID Id
creationDate DateTime Creation Date
modificationDate DateTime Modification Date
     
amount Decimal Total amount of the item
paidAmountAccumulated Decimal Accumulated amount that has been paid
dueDate DateTime Due date for the payment
status
  • NOT_SPECIFIED
  • COLLECTED
  • PAID
  • PARTIAL
 Status of the payment
paymentMean PaymentMean Fields of PaymentMean
paymentMeanId UUID Identifier of the payment method used
     
purchaseInvoice PurchaseInvoice Fields of PurchaseInvoice
purchaseInvoiceId UUID Identifier of the associated purchase invoice
Info
  • amount : Total amount due for the open item.
  • creationDate : Indicates when the item was initially created.
  • modificationDate : Timestamp of the last update to the item, null if no updates have been made.
  • paidAmountAccumulated : Total amount that has been paid towards the item up to the current date.
  • dueDate : Date by which the payment for the item is due.
  • status: Represents the current status of the payment, indicating the extent to which the item has been settled. The possible values are:
    • NOT_SPECIFIED: No specific payment status has been detailed.
    • COLLECTED: Not used for Suppliers
    • PAID: Payment has been fully made to suppliers.
    • PARTIAL: Payment for the item has been made partially.