Get an invoice
sales:invoices.readhttps://api.holded.com/api/v2/invoices/{invoiceId}Retrieves the full details of a single invoice by its unique identifier. The response includes line items, payment status and breakdown, custom fields, pipeline stage, and the source document if the invoice was converted from an estimate or sales order. A signed-in user with limited access to invoices only reaches the invoices assigned to them or created by them; any other is reported as not found. API keys still need the scope of this endpoint.
Parameters
Path parameters
stringrequiredInvoice ID (24-char hex ObjectId)
Request
import requests
url = "https://api.holded.com/api/v2/invoices/{invoiceId}"
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",
"currency_change": "1.25",
"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",
"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"
},
"payment_method_id": "string",
"payments_total": "0",
"payments_pending": "121.00",
"payments_refunds": "0",
"payments_detail": [
{
"id": "string",
"amount": "100.00",
"date": "2024-01-15",
"bank_id": "string"
}
],
"body": "string",
"multiple_due_dates": [
{
"date": "2024-01-15",
"amount": "string"
}
],
"forecast_date": "2024-01-15",
"from": {
"id": "string",
"doc_type": "string"
}
}Success responses
200Invoice foundapplication/jsonUnique identifier of the document
Sequential number assigned to the document
Identifier of the contact associated with this document
Name of the contact associated with this document
Free-text description of the document
Issue date of the document in ISO 8601 format
Payment due date in ISO 8601 format
Sum of all line amounts before tax and discounts, as a decimal string
Total discount applied to the document, as a decimal string
Final amount including taxes and discounts, as a decimal string
Total tax amount, as a decimal string
ISO 4217 currency code
Exchange rate between the document currency and the account currency. The amounts are written in the document currency: divide one by this rate to get it in the account currency. 1 when both are the same or no rate was stored
Current status of the document
failedcompletedpendingpartialcancelledList of tags attached to the document
Line items included in the document
Unique identifier of the line item
Name or title of the line item
Detailed description of the line item
Unit price as a numeric string
Quantity of units as a numeric string
Discount percentage applied to this line as a numeric string
Primary tax percentage applied to this line as a numeric string
List of tax identifiers applied to this line
Tags attached to this line item
Identifier of the linked product, if any
Identifier of the product variant, if any
Identifier of the linked service, if any
Stock Keeping Unit code of the product
Weight of the item in the account default unit as a numeric string
Cost price as a numeric string, or null when the line has no stored cost
Accounting account code assigned to this line
Identifier of the project linked to this line
Retention percentage applied to this line as a numeric string
Unit of measure for this line item (e.g. kg, units, liters)
Whether this line is a supply expense (suplido) paid on behalf of the client. Excluded from the tax base and posted to account 555.
Internal notes visible only to your team
ISO 639-1 language code used for the document
Date used for accounting purposes, if different from the issue date
Timestamp when the document was approved
Whether the document is still a draft
User-defined custom fields attached to the document
Custom field identifier
Value stored in the custom field
Breakdown of the document subtotal by project, across all its lines
Identifier of the project
Subtotal amount allocated to this project, as a decimal string
Identifier of the pipeline stage assigned to this document
Identifier of the warehouse associated with this document
DEPRECATED, use shipping_address.type. Shipping display mode: billing, hidden or manual, or the id of an address saved on the contact.
DEPRECATED, use shipping_address. Single-line shipping address text.
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.
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)
billinghiddenmanualcontactName of the shipping recipient (the given name when family_name is also sent)
Family name of the shipping recipient
Company or organization of the shipping recipient
Primary address line
Secondary address line
City or locality
Postal or ZIP code
State, province, or region
Country name
ISO 3166-1 alpha-2 country code
Contact email for shipping
Contact phone number for shipping
Mobile number for shipping
Identifier of an address saved on the contact (shipping_id in the contact shipping_addresses). Required when type is contact
The shipping address as a single line of text
Identifier of the default payment method for this document
Total amount already paid, as a decimal string
Remaining amount to be paid, as a decimal string
Total refunded amount, as a decimal string
Breakdown of individual payments recorded against this document
Unique identifier of the payment
Payment amount as a decimal string
Payment date in ISO 8601 format
Identifier of the treasury account used for this payment
Rich-text body content printed on the invoice
Split payment schedule with individual due dates and amounts
Due date for this instalment in ISO 8601 format
Amount due for this instalment as a decimal string
Expected collection date used for cash-flow forecasting
Source document this invoice was created from
Identifier of the source document
Type of the source document
Error responses
401Invalid or missing API keyapplication/json403Insufficient permissionsapplication/json404Invoice not foundapplication/json429Rate limit exceededapplication/json