Create one-time deduction

POST

api

{version}

deductions

once

Create one-time deduction

curl --request POST \
  --url https://integrations.alvys.com/api/p/v{version}/deductions/once \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json-patch+json' \
  --data '
{
  "Date": "2023-11-07T05:31:56Z",
  "Amount": 123,
  "Category": "<string>",
  "Description": "<string>",
  "DriverId": "<string>",
  "TruckId": "<string>",
  "OwnerOperatorId": "<string>",
  "ExternalId": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json-patch+json'},
  body: JSON.stringify({
    Date: '2023-11-07T05:31:56Z',
    Amount: 123,
    Category: '<string>',
    Description: '<string>',
    DriverId: '<string>',
    TruckId: '<string>',
    OwnerOperatorId: '<string>',
    ExternalId: '<string>'
  })
};

fetch('https://integrations.alvys.com/api/p/v{version}/deductions/once', 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}/deductions/once"

payload = {
    "Date": "2023-11-07T05:31:56Z",
    "Amount": 123,
    "Category": "<string>",
    "Description": "<string>",
    "DriverId": "<string>",
    "TruckId": "<string>",
    "OwnerOperatorId": "<string>",
    "ExternalId": "<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}/deductions/once",
  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([
    'Date' => '2023-11-07T05:31:56Z',
    'Amount' => 123,
    'Category' => '<string>',
    'Description' => '<string>',
    'DriverId' => '<string>',
    'TruckId' => '<string>',
    'OwnerOperatorId' => '<string>',
    'ExternalId' => '<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}/deductions/once"

	payload := strings.NewReader("{\n  \"Date\": \"2023-11-07T05:31:56Z\",\n  \"Amount\": 123,\n  \"Category\": \"<string>\",\n  \"Description\": \"<string>\",\n  \"DriverId\": \"<string>\",\n  \"TruckId\": \"<string>\",\n  \"OwnerOperatorId\": \"<string>\",\n  \"ExternalId\": \"<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}/deductions/once")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json-patch+json")
  .body("{\n  \"Date\": \"2023-11-07T05:31:56Z\",\n  \"Amount\": 123,\n  \"Category\": \"<string>\",\n  \"Description\": \"<string>\",\n  \"DriverId\": \"<string>\",\n  \"TruckId\": \"<string>\",\n  \"OwnerOperatorId\": \"<string>\",\n  \"ExternalId\": \"<string>\"\n}")
  .asString();

{
  "Id": "<string>",
  "Type": "<string>",
  "GroupId": "<string>",
  "Description": "<string>",
  "Category": "<string>",
  "Amount": {
    "Amount": 123,
    "Currency": 123
  },
  "Date": "2023-11-07T05:31:56Z",
  "IsPaid": true,
  "CreatedAt": "2023-11-07T05:31:56Z",
  "DriverId": "<string>",
  "TruckId": "<string>",
  "OwnerOperatorId": "<string>",
  "CreatedBy": "<string>",
  "ExternalId": "<string>"
}

{
  "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>"
}

This endpoint creates a new deduction record for a driver or a truck. Deductions are asset-specific financial adjustments and can be associated with either a driver or a truck, but not both simultaneously. The deduction itself is always tied to a specific asset (Driver or Truck) and can optionally reference an owner operator for ownership context.

Key Rules:

A deduction must include either DriverId or TruckId — one of them is mandatory.
OwnerOperatorId is optional and used only to override the current owner of the asset. It is never the primary subject of the deduction.
The deduction is always created for a specific DriverId or TruckId, not directly for an owner operator.
If DriverId is provided → the deduction appears in that driver’s deductions table.
If TruckId is provided → the deduction appears in that truck’s deductions table.
If OwnerOperatorId is provided → it overrides the current owner of the asset to that specific owner operator (only within this deduction record). If omitted → the system automatically links the deduction to the current owner operator, if one exists.
If the truck or driver has no owner operator → the deduction is created without one.

ExternalId is optional — a plain caller-supplied reference id, trimmed before storage and returned unchanged on the response. Sending the same value twice creates two separate deductions; there is no retry-replay or duplicate-conflict 409 on this route.Track the id this create returns if you need to find the deduction again — POST deductions/search accepts ExternalId as a filter, either alongside DriverId/TruckId/OwnerOperatorId/DateRange to narrow a search, or on its own.

Permissions Required

Only users or client credentials with Create access to the Deductions resource can perform creation. If the API client lacks sufficient privileges, a 403 Forbidden response will be returned.

Request Body Parameters

Parameter	Type	Required	Description
Date	String (Date)	Yes	The effective date of the deduction. Time values are accepted but truncated on save.
Amount	Number	Yes	The deduction amount. Must be negative and have a value of less than - 1.00.
Category	String	Yes	Deduction category (any string value).
Description	String	Yes	Description or reason for the deduction.
DriverId	String	Conditionally	Required when creating a deduction for a driver. Must not be used together with TruckId.
TruckId	String	Conditionally	Required when creating a deduction for a truck. Must not be used together with DriverId.
OwnerOperatorId	String	No	Optional — used only to override the current owner of the asset (Driver or Truck).
ExternalId	String	No	Optional caller-supplied reference id, max 128 characters — see note above.

Example CURL Request

curl --location 'https://integrations.alvys.com/api/p/v1/deductions/once' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "Date": "2025-10-07",
  "Amount": -55,
  "Category": "Drug Test",
  "Description": "DOT Drug Test Fee",
  "DriverId": "DR2517534557938191",
  "OwnerOperatorId": "DR25165000003445290"
}'

Response Body Parameters

Parameter	Type	Required	Description
Id	String	Yes	The unique identifier of the created deduction.
Type	String	Yes	Type of record (`"Deduction"`).
GroupId	String	No	Group ID if part of a recurring rule or batch.
Description	String	Yes	Description of the deduction.
Category	String	Yes	Deduction category (e.g., Fuel, Advance, Drug Test).
Amount.Amount	Number	Yes	Deduction amount (negative value).
Amount.Currency	Integer	Yes	ISO numeric currency code (e.g., 840 for USD).
DriverId	String	Conditionally	The Driver ID if the deduction was created for a driver.
TruckId	String	Conditionally	The Truck ID if the deduction was created for a truck.
OwnerOperatorId	String	No	The Owner Operator ID of the truck or driver (if applicable).
Date	String (Date)	Yes	The effective date of the deduction (date only, without time).
IsPaid	Boolean	No	Indicates whether the deduction has been paid. Default: `false`.
CreatedAt	String (Date-Time)	Yes	Timestamp when the deduction was created (UTC).
CreatedBy	String	No	Client ID or User ID of the person who created the deduction.
ExternalId	String	No	The reference id the deduction was created with, or `null` when none was supplied.

Example Response

{
  "Id": "22d34b6d-7403-4003-b8ea-e028cd36e7d7",
  "Type": "Deduction",
  "GroupId": "344571de-57b4-4163-a0cc-d7981fa65994",
  "Description": "DOT Drug Test Fee",
  "Category": "Drug Test",
  "Amount": {
    "Amount": -55,
    "Currency": 840
  },
  "DriverId": "DR2517534557938191",
  "OwnerOperatorId": "DR25165000003445290",
  "Date": "2025-10-07",
  "IsPaid": false,
  "CreatedAt": "2025-10-09T08:30:54.873Z",
  "CreatedBy": "MhAeSgpRH6REdgfrthgfUdTdXOMgVSGyp",
  "ExternalId": null
}

Versioning

The version parameter in the URL path specifies which version of the API you are using. Including the version number ensures that your integration remains stable as the API evolves. For more details, refer to the Versioning page.

Rate Limits

All endpoints are subject to standard rate limits to ensure consistent API performance. For details, see the Rate Limits section.

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

Date

string<date-time>

required

Amount

number<double>

required

Response

Created

string

required

Type

string

required

GroupId

string

required

Description

string

required

Category

string

required

Amount

object

required

Show child attributes

Date

string<date-time>

required

IsPaid

boolean

required

CreatedAt

string<date-time>

required

DriverId

string | null

TruckId

string | null

OwnerOperatorId

string | null

CreatedBy

string | null

ExternalId

string | null

The ExternalId stored with this record, or null when none was supplied. On a driver credit (Type "Credit") this is the idempotency key from POST /credits/driver. On a deduction, it is a plain caller-supplied reference id with no uniqueness enforcement. Also carries an internal asset-maintenance:-prefixed value for deductions generated from asset maintenance records.

⌘I

Create one-time deduction

curl --request POST \
  --url https://integrations.alvys.com/api/p/v{version}/deductions/once \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json-patch+json' \
  --data '
{
  "Date": "2023-11-07T05:31:56Z",
  "Amount": 123,
  "Category": "<string>",
  "Description": "<string>",
  "DriverId": "<string>",
  "TruckId": "<string>",
  "OwnerOperatorId": "<string>",
  "ExternalId": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json-patch+json'},
  body: JSON.stringify({
    Date: '2023-11-07T05:31:56Z',
    Amount: 123,
    Category: '<string>',
    Description: '<string>',
    DriverId: '<string>',
    TruckId: '<string>',
    OwnerOperatorId: '<string>',
    ExternalId: '<string>'
  })
};

fetch('https://integrations.alvys.com/api/p/v{version}/deductions/once', 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}/deductions/once"

payload = {
    "Date": "2023-11-07T05:31:56Z",
    "Amount": 123,
    "Category": "<string>",
    "Description": "<string>",
    "DriverId": "<string>",
    "TruckId": "<string>",
    "OwnerOperatorId": "<string>",
    "ExternalId": "<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}/deductions/once",
  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([
    'Date' => '2023-11-07T05:31:56Z',
    'Amount' => 123,
    'Category' => '<string>',
    'Description' => '<string>',
    'DriverId' => '<string>',
    'TruckId' => '<string>',
    'OwnerOperatorId' => '<string>',
    'ExternalId' => '<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}/deductions/once"

	payload := strings.NewReader("{\n  \"Date\": \"2023-11-07T05:31:56Z\",\n  \"Amount\": 123,\n  \"Category\": \"<string>\",\n  \"Description\": \"<string>\",\n  \"DriverId\": \"<string>\",\n  \"TruckId\": \"<string>\",\n  \"OwnerOperatorId\": \"<string>\",\n  \"ExternalId\": \"<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}/deductions/once")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json-patch+json")
  .body("{\n  \"Date\": \"2023-11-07T05:31:56Z\",\n  \"Amount\": 123,\n  \"Category\": \"<string>\",\n  \"Description\": \"<string>\",\n  \"DriverId\": \"<string>\",\n  \"TruckId\": \"<string>\",\n  \"OwnerOperatorId\": \"<string>\",\n  \"ExternalId\": \"<string>\"\n}")
  .asString();

{
  "Id": "<string>",
  "Type": "<string>",
  "GroupId": "<string>",
  "Description": "<string>",
  "Category": "<string>",
  "Amount": {
    "Amount": 123,
    "Currency": 123
  },
  "Date": "2023-11-07T05:31:56Z",
  "IsPaid": true,
  "CreatedAt": "2023-11-07T05:31:56Z",
  "DriverId": "<string>",
  "TruckId": "<string>",
  "OwnerOperatorId": "<string>",
  "CreatedBy": "<string>",
  "ExternalId": "<string>"
}

{
  "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>"
}

​Key Rules:

​Permissions Required

​Request Body Parameters

​Example CURL Request

​Response Body Parameters

​Example Response

​Versioning

​Rate Limits

Authorizations

Path Parameters

Body

Response

Key Rules:

Permissions Required

Request Body Parameters

Example CURL Request

Response Body Parameters

Example Response

Versioning

Rate Limits