Get a waybill
Scope: inventory:shipments.read https://api.alladdin.com/api/v2/waybills/{waybillId}
Retrieves the full details of a single waybill by its unique identifier.
The response includes line items, shipping tracking information, custom fields, and pipeline stage.
Parameters
Path parameters
waybillId string required
Waybill ID (24-char hex ObjectId)
Request
import requests
url = "https://api.alladdin.com/api/v2/waybills/{waybillId}"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Accept": "application/json",
}
response = requests.get(url, headers=headers)
print(response.json())Responses
Response
{
"id": "507f1f77bcf86cd799439011",
"document_number": "INV-0001",
"contact_id": "507f1f77bcf86cd799439011",
"contact_name": "Acme Corp",
"description": "string",
"date": "2024-01-15",
"due_date": "2024-02-15",
"subtotal": "100.00",
"discount": "0",
"total": "121.00",
"tax": "21.00",
"currency": "EUR",
"status": "pending",
"tags": [
"string"
],
"lines": [
{
"line_id": "string",
"name": "string",
"description": "string",
"price": "100.00",
"units": "1",
"discount": "0",
"tax": "21",
"taxes": [
"string"
],
"tags": [
"string"
],
"product_id": "string",
"variant_id": "string",
"service_id": "string",
"sku": "string",
"weight": "string",
"cost_price": "string",
"account": "string",
"project_id": "string",
"retention": "string",
"unit_type": "kg",
"supplied": false
}
],
"notes": "string",
"language": "es",
"currency_change": "1.00",
"accounting_date": "2024-01-15",
"approved_at": "2024-01-15T13:00:00",
"draft": false,
"custom_fields": [
{
"field": "string",
"value": "string"
}
],
"projects_summary": [
{
"project_id": "string",
"amount": "string"
}
],
"pipeline_id": "string",
"warehouse_id": "string",
"shipping": "string",
"shipping_data": "string",
"shipping_address": {
"type": "manual",
"name": "string",
"family_name": "string",
"organization": "string",
"address_line_1": "string",
"address_line_2": "string",
"city": "string",
"postal_code": "string",
"province": "string",
"country": "string",
"country_code": "ES",
"email": "string",
"phone": "string",
"mobile": "string",
"contact_address_id": "string",
"full_address": "string"
},
"tracking_key": "string",
"tracking_name": "string",
"tracking_number": "string",
"pickup_date": "2024-01-15",
"delivery_date": "2024-01-20",
"internal_notes": "string",
"from": {
"id": "string",
"doc_type": "string"
},
"is_valued": false
}Success responses
200 Waybill found application/json object id string
Unique identifier of the document
document_number string | null
Sequential number assigned to the document
contact_id string | null
Identifier of the contact associated with this document
contact_name string | null
Name of the contact associated with this document
description string | null
Free-text description of the document
date string<date> | null
Issue date of the document in ISO 8601 format
due_date string<date> | null
Payment due date in ISO 8601 format
subtotal string
Sum of all line amounts before tax and discounts, as a decimal string
discount string
Total discount applied to the document, as a decimal string
total string
Final amount including taxes and discounts, as a decimal string
tax string
Total tax amount, as a decimal string
currency string
ISO 4217 currency code
status string
Current status of the document
Enum: failed completed pending partial cancelled tags[] string[]
List of tags attached to the document
lines[] object[]
Line items included in the document
line_id string | null
Unique identifier of the line item
name string
Name or title of the line item
description string
Detailed description of the line item
price string
Unit price as a numeric string
units string
Quantity of units as a numeric string
discount string
Discount percentage applied to this line as a numeric string
tax string
Primary tax percentage applied to this line as a numeric string
taxes[] string[]
List of tax identifiers applied to this line
tags[] string[]
Tags attached to this line item
product_id string | null
Identifier of the linked product, if any
variant_id string | null
Identifier of the product variant, if any
service_id string | null
Identifier of the linked service, if any
sku string | null
Stock Keeping Unit code of the product
weight string
Weight of the item in the account default unit as a numeric string
cost_price string
Cost price as a numeric string
account string | null
Accounting account code assigned to this line
project_id string | null
Identifier of the project linked to this line
retention string
Retention percentage applied to this line as a numeric string
unit_type string | null
Unit of measure for this line item (e.g. kg, units, liters)
supplied boolean
Whether this line is a supply expense (suplido) paid on behalf of the client. Excluded from the tax base and posted to account 555.
notes string | null
Internal notes visible only to your team
language string | null
ISO 639-1 language code used for the document
currency_change string
Exchange rate applied when the document currency differs from the account currency
accounting_date string<date> | null
Date used for accounting purposes, if different from the issue date
approved_at string | null
Timestamp when the document was approved
draft boolean | null
Whether the document is still a draft
custom_fields[] object[]
User-defined custom fields attached to the document
field string
Custom field identifier
value string
Value stored in the custom field
projects_summary[] object[]
Breakdown of the document subtotal by project, across all its lines
project_id string
Identifier of the project
amount string
Subtotal amount allocated to this project, as a decimal string
pipeline_id string | null
Identifier of the pipeline stage assigned to this document
warehouse_id string | null
Identifier of the warehouse associated with this document
shipping string | null
DEPRECATED, use shipping_address.type. Shipping display mode: billing, hidden or manual, or the id of an address saved on the contact.
shipping_data string | null
DEPRECATED, use shipping_address. Single-line shipping address text.
shipping_address object | null
Structured shipping address for this document. For type billing and contact the address fields come back empty because the data lives on the contact: read it with GET /api/v2/contacts/{contact_id} (bill_address for billing, or the entry of shipping_addresses whose shipping_id equals contact_address_id for contact). full_address is the address as a single line of text.
type string required
Address mode: manual (uses the address fields), billing (the billing address of the contact), hidden (no address displayed) or contact (an address saved on the contact, see contact_address_id)
Enum: billing hidden manual contact name string | null optional
Name of the shipping recipient (the given name when family_name is also sent)
family_name string | null optional
Family name of the shipping recipient
organization string | null optional
Company or organization of the shipping recipient
address_line_1 string | null optional
Primary address line
address_line_2 string | null optional
Secondary address line
city string | null optional
City or locality
postal_code string | null optional
Postal or ZIP code
province string | null optional
State, province, or region
country string | null optional
Country name
country_code string | null optional
ISO 3166-1 alpha-2 country code
email string | null optional
Contact email for shipping
phone string | null optional
Contact phone number for shipping
mobile string | null optional
Mobile number for shipping
contact_address_id string | null optional
Identifier of an address saved on the contact (shipping_id in the contact shipping_addresses). Required when type is contact
full_address string | null optional
The shipping address as a single line of text
tracking_key string | null
Carrier-specific tracking key or code
tracking_name string | null
Name of the shipping carrier
tracking_number string | null
Shipment tracking number provided by the carrier
pickup_date string<date> | null
Scheduled pickup date in ISO 8601 format
delivery_date string<date> | null
Expected delivery date in ISO 8601 format
internal_notes string | null
Internal notes about the shipment, not visible to the recipient
from object | null
Source document this waybill was created from
id string
Identifier of the source document
doc_type string
Type of the source document
is_valued boolean
Whether the PDF shows line prices and totals
Error responses
401 Invalid or missing API key application/json 403 Insufficient permissions application/json 404 Waybill not found application/json 429 Rate limit exceeded application/json