Skip to main content
GET

Get an invoice

Scope:sales:invoices.read
https://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

invoiceIdstringrequired

Invoice ID (24-char hex ObjectId)

Request

python
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

json
{
  "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/json
object
idstring

Unique identifier of the document

document_numberstring | null

Sequential number assigned to the document

contact_idstring | null

Identifier of the contact associated with this document

contact_namestring | null

Name of the contact associated with this document

descriptionstring | null

Free-text description of the document

datestring<date> | null

Issue date of the document in ISO 8601 format

due_datestring<date> | null

Payment due date in ISO 8601 format

subtotalstring

Sum of all line amounts before tax and discounts, as a decimal string

discountstring

Total discount applied to the document, as a decimal string

totalstring

Final amount including taxes and discounts, as a decimal string

taxstring

Total tax amount, as a decimal string

currencystring

ISO 4217 currency code

currency_changestring

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

statusstring

Current status of the document

Enum:failedcompletedpendingpartialcancelled
tags[]string[]

List of tags attached to the document

lines[]object[]

Line items included in the document

line_idstring | null

Unique identifier of the line item

namestring

Name or title of the line item

descriptionstring

Detailed description of the line item

pricestring

Unit price as a numeric string

unitsstring

Quantity of units as a numeric string

discountstring

Discount percentage applied to this line as a numeric string

taxstring

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_idstring | null

Identifier of the linked product, if any

variant_idstring | null

Identifier of the product variant, if any

service_idstring | null

Identifier of the linked service, if any

skustring | null

Stock Keeping Unit code of the product

weightstring

Weight of the item in the account default unit as a numeric string

cost_pricestring | null

Cost price as a numeric string, or null when the line has no stored cost

accountstring | null

Accounting account code assigned to this line

project_idstring | null

Identifier of the project linked to this line

retentionstring

Retention percentage applied to this line as a numeric string

unit_typestring | null

Unit of measure for this line item (e.g. kg, units, liters)

suppliedboolean

Whether this line is a supply expense (suplido) paid on behalf of the client. Excluded from the tax base and posted to account 555.

notesstring | null

Internal notes visible only to your team

languagestring | null

ISO 639-1 language code used for the document

accounting_datestring<date> | null

Date used for accounting purposes, if different from the issue date

approved_atstring | null

Timestamp when the document was approved

draftboolean | null

Whether the document is still a draft

custom_fields[]object[]

User-defined custom fields attached to the document

fieldstring

Custom field identifier

valuestring

Value stored in the custom field

projects_summary[]object[]

Breakdown of the document subtotal by project, across all its lines

project_idstring

Identifier of the project

amountstring

Subtotal amount allocated to this project, as a decimal string

pipeline_idstring | null

Identifier of the pipeline stage assigned to this document

warehouse_idstring | null

Identifier of the warehouse associated with this document

shippingstring | null

DEPRECATED, use shipping_address.type. Shipping display mode: billing, hidden or manual, or the id of an address saved on the contact.

shipping_datastring | null

DEPRECATED, use shipping_address. Single-line shipping address text.

shipping_addressobject | 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.

typestringrequired

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:billinghiddenmanualcontact
namestring | nulloptional

Name of the shipping recipient (the given name when family_name is also sent)

family_namestring | nulloptional

Family name of the shipping recipient

organizationstring | nulloptional

Company or organization of the shipping recipient

address_line_1string | nulloptional

Primary address line

address_line_2string | nulloptional

Secondary address line

citystring | nulloptional

City or locality

postal_codestring | nulloptional

Postal or ZIP code

provincestring | nulloptional

State, province, or region

countrystring | nulloptional

Country name

country_codestring | nulloptional

ISO 3166-1 alpha-2 country code

emailstring | nulloptional

Contact email for shipping

phonestring | nulloptional

Contact phone number for shipping

mobilestring | nulloptional

Mobile number for shipping

contact_address_idstring | nulloptional

Identifier of an address saved on the contact (shipping_id in the contact shipping_addresses). Required when type is contact

full_addressstring | nulloptional

The shipping address as a single line of text

payment_method_idstring | null

Identifier of the default payment method for this document

payments_totalstring

Total amount already paid, as a decimal string

payments_pendingstring

Remaining amount to be paid, as a decimal string

payments_refundsstring

Total refunded amount, as a decimal string

payments_detail[]object[]

Breakdown of individual payments recorded against this document

idstring

Unique identifier of the payment

amountstring

Payment amount as a decimal string

datestring<date> | null

Payment date in ISO 8601 format

bank_idstring

Identifier of the treasury account used for this payment

bodystring | null

Rich-text body content printed on the invoice

multiple_due_dates[]object[] | null

Split payment schedule with individual due dates and amounts

datestring<date>

Due date for this instalment in ISO 8601 format

amountstring

Amount due for this instalment as a decimal string

forecast_datestring<date> | null

Expected collection date used for cash-flow forecasting

fromobject | null

Source document this invoice was created from

idstring

Identifier of the source document

doc_typestring

Type of the source document

Error responses

401Invalid or missing API keyapplication/json
403Insufficient permissionsapplication/json
404Invoice not foundapplication/json
429Rate limit exceededapplication/json