Record customer payment

POST

api

{version}

invoices

customer-payments

Record customer payment

curl --request POST \
  --url https://integrations.alvys.com/api/p/v{version}/invoices/customer-payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json-patch+json' \
  --data '
{
  "LoadNumber": "<string>",
  "Amount": {
    "Amount": 123,
    "Currency": 123
  },
  "PaymentDate": "2023-11-07T05:31:56Z",
  "ReferenceNumber": "<string>",
  "InvoiceNumber": "<string>",
  "PaymentMethod": "<string>",
  "CheckNumber": "<string>",
  "Note": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json-patch+json'},
  body: JSON.stringify({
    LoadNumber: '<string>',
    Amount: {Amount: 123, Currency: 123},
    PaymentDate: '2023-11-07T05:31:56Z',
    ReferenceNumber: '<string>',
    InvoiceNumber: '<string>',
    PaymentMethod: '<string>',
    CheckNumber: '<string>',
    Note: '<string>'
  })
};

fetch('https://integrations.alvys.com/api/p/v{version}/invoices/customer-payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://integrations.alvys.com/api/p/v{version}/invoices/customer-payments"

payload = {
    "LoadNumber": "<string>",
    "Amount": {
        "Amount": 123,
        "Currency": 123
    },
    "PaymentDate": "2023-11-07T05:31:56Z",
    "ReferenceNumber": "<string>",
    "InvoiceNumber": "<string>",
    "PaymentMethod": "<string>",
    "CheckNumber": "<string>",
    "Note": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json-patch+json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://integrations.alvys.com/api/p/v{version}/invoices/customer-payments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'LoadNumber' => '<string>',
    'Amount' => [
        'Amount' => 123,
        'Currency' => 123
    ],
    'PaymentDate' => '2023-11-07T05:31:56Z',
    'ReferenceNumber' => '<string>',
    'InvoiceNumber' => '<string>',
    'PaymentMethod' => '<string>',
    'CheckNumber' => '<string>',
    'Note' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json-patch+json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://integrations.alvys.com/api/p/v{version}/invoices/customer-payments"

	payload := strings.NewReader("{\n  \"LoadNumber\": \"<string>\",\n  \"Amount\": {\n    \"Amount\": 123,\n    \"Currency\": 123\n  },\n  \"PaymentDate\": \"2023-11-07T05:31:56Z\",\n  \"ReferenceNumber\": \"<string>\",\n  \"InvoiceNumber\": \"<string>\",\n  \"PaymentMethod\": \"<string>\",\n  \"CheckNumber\": \"<string>\",\n  \"Note\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json-patch+json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://integrations.alvys.com/api/p/v{version}/invoices/customer-payments")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json-patch+json")
  .body("{\n  \"LoadNumber\": \"<string>\",\n  \"Amount\": {\n    \"Amount\": 123,\n    \"Currency\": 123\n  },\n  \"PaymentDate\": \"2023-11-07T05:31:56Z\",\n  \"ReferenceNumber\": \"<string>\",\n  \"InvoiceNumber\": \"<string>\",\n  \"PaymentMethod\": \"<string>\",\n  \"CheckNumber\": \"<string>\",\n  \"Note\": \"<string>\"\n}")
  .asString();

{
  "Id": "<string>",
  "LoadNumber": "<string>",
  "Status": "<string>",
  "TotalPaid": {
    "Amount": 123,
    "Currency": 123
  },
  "TotalBillable": {
    "Amount": 123,
    "Currency": 123
  }
}

{
  "Errors": {},
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

This endpoint allows external systems to post customer payments into Alvys and apply them to the corresponding load.

Path Parameters

Parameter	Type	Required	Description
version	string	Yes	API version (e.g., `1.0`)

Request Body

Content-Type: application/json-patch+json

Field	Type	Required	Description
LoadNumber	string	Yes	Load number the payment should be applied to
Amount	object	Yes	Payment amount object
Amount.Amount	number	Yes	Payment amount value
Amount.Currency	integer	Yes	Currency identifier
CheckNumber	string	No	Check number if the payment method uses a check
InvoiceNumber	string	No	Invoice number associated with the payment
Note	string	No	Additional note related to the payment
PaymentDate	string (date-time)	Yes	Date when the payment was made
PaymentMethod	string	No	Payment method used (for example Check, ACH, Wire)
ReferenceNumber	string	Yes	External reference number for idempotency and payment tracking

Example Request

{
  "LoadNumber": "string",
  "Amount": {
    "Amount": 0,
    "Currency": 0
  },
  "PaymentDate": "2026-03-16T13:57:56.427Z",
  "ReferenceNumber": "string",
  "InvoiceNumber": "string",
  "PaymentMethod": "string",
  "CheckNumber": "string",
  "Note": "string"
}

Response Body

Field	Type	Description
Id	string	Unique identifier of the recorded payment
LoadNumber	string	Load number the payment was applied to
Status	string	Current load status after applying the payment
TotalPaid	object	Total amount paid by the customer to date
TotalPaid.Amount	number	Monetary amount
TotalPaid.Currency	integer	Currency identifier
TotalBillable	object	Total billable amount for the load
TotalBillable.Amount	number	Monetary amount
TotalBillable.Currency	integer	Currency identifier

Notes

This endpoint records customer payments against loads.
The request body content type exposed by the API is application/json-patch+json.
ReferenceNumber is required and is used for idempotency. Repeating the same ReferenceNumber for the same load returns the original payment instead of creating a duplicate.
This endpoint accepts payments only when the load is in one of these statuses:
- Invoiced
- Completed
- Financed
Loads in non-payable statuses such as Dispatched are rejected with:

400 Bad Request
Load must be in one of: Invoiced, Completed, Financed.

If the LoadNumber does not exist, the endpoint returns:

404 Not Found

If Amount.Amount is negative or zero, the endpoint returns:

400 Bad Request
Amount must be greater than zero.

If ReferenceNumber is empty or omitted, the endpoint returns:

400 Bad Request
The ReferenceNumber field is required.

Authorizations

Authorization

string

header

required

OAuth 2.0 client-credentials access token. Obtain one from https://auth.alvys.com/oauth/token (grant_type=client_credentials, audience=https://api.alvys.com/public/), then paste it here. The playground sends it as Authorization: Bearer <token>.

Path Parameters

version

string

default:1.0

required

API version (e.g., 1.0)

Example:

"1.0"

Body

LoadNumber

string

required

Amount

object

required

Show child attributes

PaymentDate

string<date-time>

required

ReferenceNumber

string

required

InvoiceNumber

string | null

PaymentMethod

string | null

CheckNumber

string | null

Note

string | null

Response

string

required

LoadNumber

string

required

Status

string

required

TotalPaid

object

required

Show child attributes

TotalBillable

object

required

Show child attributes

⌘I

Record customer payment

curl --request POST \
  --url https://integrations.alvys.com/api/p/v{version}/invoices/customer-payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json-patch+json' \
  --data '
{
  "LoadNumber": "<string>",
  "Amount": {
    "Amount": 123,
    "Currency": 123
  },
  "PaymentDate": "2023-11-07T05:31:56Z",
  "ReferenceNumber": "<string>",
  "InvoiceNumber": "<string>",
  "PaymentMethod": "<string>",
  "CheckNumber": "<string>",
  "Note": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json-patch+json'},
  body: JSON.stringify({
    LoadNumber: '<string>',
    Amount: {Amount: 123, Currency: 123},
    PaymentDate: '2023-11-07T05:31:56Z',
    ReferenceNumber: '<string>',
    InvoiceNumber: '<string>',
    PaymentMethod: '<string>',
    CheckNumber: '<string>',
    Note: '<string>'
  })
};

fetch('https://integrations.alvys.com/api/p/v{version}/invoices/customer-payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://integrations.alvys.com/api/p/v{version}/invoices/customer-payments"

payload = {
    "LoadNumber": "<string>",
    "Amount": {
        "Amount": 123,
        "Currency": 123
    },
    "PaymentDate": "2023-11-07T05:31:56Z",
    "ReferenceNumber": "<string>",
    "InvoiceNumber": "<string>",
    "PaymentMethod": "<string>",
    "CheckNumber": "<string>",
    "Note": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json-patch+json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://integrations.alvys.com/api/p/v{version}/invoices/customer-payments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'LoadNumber' => '<string>',
    'Amount' => [
        'Amount' => 123,
        'Currency' => 123
    ],
    'PaymentDate' => '2023-11-07T05:31:56Z',
    'ReferenceNumber' => '<string>',
    'InvoiceNumber' => '<string>',
    'PaymentMethod' => '<string>',
    'CheckNumber' => '<string>',
    'Note' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json-patch+json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://integrations.alvys.com/api/p/v{version}/invoices/customer-payments"

	payload := strings.NewReader("{\n  \"LoadNumber\": \"<string>\",\n  \"Amount\": {\n    \"Amount\": 123,\n    \"Currency\": 123\n  },\n  \"PaymentDate\": \"2023-11-07T05:31:56Z\",\n  \"ReferenceNumber\": \"<string>\",\n  \"InvoiceNumber\": \"<string>\",\n  \"PaymentMethod\": \"<string>\",\n  \"CheckNumber\": \"<string>\",\n  \"Note\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json-patch+json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://integrations.alvys.com/api/p/v{version}/invoices/customer-payments")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json-patch+json")
  .body("{\n  \"LoadNumber\": \"<string>\",\n  \"Amount\": {\n    \"Amount\": 123,\n    \"Currency\": 123\n  },\n  \"PaymentDate\": \"2023-11-07T05:31:56Z\",\n  \"ReferenceNumber\": \"<string>\",\n  \"InvoiceNumber\": \"<string>\",\n  \"PaymentMethod\": \"<string>\",\n  \"CheckNumber\": \"<string>\",\n  \"Note\": \"<string>\"\n}")
  .asString();

{
  "Id": "<string>",
  "LoadNumber": "<string>",
  "Status": "<string>",
  "TotalPaid": {
    "Amount": 123,
    "Currency": 123
  },
  "TotalBillable": {
    "Amount": 123,
    "Currency": 123
  }
}

{
  "Errors": {},
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

​Path Parameters

​Request Body

​Example Request

​Response Body

​Notes

Authorizations

Path Parameters

Body

Response

Path Parameters

Request Body

Example Request

Response Body

Notes