Skip to main content

allocatePayment

Requires at least one of the permissions payments:payment:allocate or purchase:payment:allocate.

Applies a payment's unallocated balance to one or more invoices of the same customer or supplier. At least one allocation is required. The payment must still be allocatable (a voided, reversed or refunded payment is refused), the payment and each invoice must share a currency, and the total cannot exceed the payment's unallocated amount or an invoice's outstanding amount.

Errors: a failed call returns a GraphQL errors entry, not a field on the result, and data may be null or partial. Read the entry's extensions.code and message; every shape and code is in the Error reference.

Example:

mutation AllocatePayment($input: AllocatePaymentInput!) {
  allocatePayment(input: $input) {
    id
    checkNumber
    currencyCode
    paymentNumber
    referenceNumber
    status
    allocations {
      id
      invoiceNumber
      paymentNumber
      createdAt
      amount
      appliedFromAdvance
    }
  }
}

Variables:

{
  "input": {
    "allocations": [
      {
        "amount": 0,
        "invoiceId": "id"
      }
    ],
    "paymentId": "id"
  }
}

Response:

{
  "data": {
    "allocatePayment": {
      "id": "id",
      "checkNumber": "string",
      "currencyCode": "string",
      "paymentNumber": "string",
      "referenceNumber": "string",
      "status": "APPROVED",
      "allocations": [
        {
          "id": "id",
          "invoiceNumber": "string",
          "paymentNumber": "string",
          "createdAt": "2025-01-15T00:00:00Z",
          "amount": 0,
          "appliedFromAdvance": true
        }
      ]
    }
  }
}

Allocate a payment across invoices:

mutation AllocatePayment($input: AllocatePaymentInput!) {
  allocatePayment(input: $input) {
    id
    paymentNumber
    status
  }
}

Variables:

{
  "input": {
    "paymentId": "PAYMENT_ID",
    "allocations": [
      {
        "invoiceId": "INVOICE_ID",
        "amount": 200
      }
    ]
  }
}

Response:

{
  "data": {
    "allocatePayment": {
      "id": "PAYMENT_ID",
      "paymentNumber": "PAYMENT_NUMBER",
      "status": "PAID"
    }
  }
}
allocatePayment(
  input: AllocatePaymentInput!
): Payment!

Arguments​

allocatePayment.input ● AllocatePaymentInput! non-null input​

The payment and the invoices to allocate it to.

Type​

Payment object​

A payment made out to a vendor or a collection received from a customer, with its allocations to invoices.