Invoices

Fetch and update invoices information.

Received's Invoices APIs allow our users to manage their invoices and contracts. The APIs support operations such as fetching an invoice, reconciliation of an invoice, fetching customers' related data.

Endpoint on this page

GET https://api.received.ai/api/invoices/<invoice_ref>
GET https://api.received.ai/api/invoices/reconcile

Don't forget! APIs must include:

1. Bearer Token - return from the login call

2. API version - {"Version": "V0"}

Fetching Invoices

Fetching invoices involves retrieving specific billing documents either by their unique invoice ID or through a contract ID, which allows access to both current and upcoming invoices, ensuring timely financial management and client servicing

Get Invoice

GET https://api.received.ai/api/invoices/<invoice_ref>

Response

{
    "invoice_ref": "3a7b0f7d-fdf6-4f54-90f4-2307b73ae85f",
    "document_number": "INV-2023-001",
    "customer": {
      "customer_ref": "32c320bb-431b-488f-bcd4-729e495a33ad",
      "customer_name": "Acme Corporation",
      "customer_legal_name": "Acme Corp Ltd"
    },
    "state": "PAID",    
    "created_at": "2023-08-01T00:00:00Z",
    "issue_date": "2023-08-01",
    "due_date": "2023-09-01",
    "submission_date": "2023-08-02T00:00:00Z",
    "paid_date": "2023-08-01T00:00:00Z",
    "is_partial_period": false,
    "accounting_event_type": "INVOICE",
    "currency": "USD",
    "net_terms": 30,
    "sub_total": 1000.00,
    "total_discount": 50.00,
    "total_tax": 100.00,
    "credits_amount": 0.00,
    "total": 1050.00,
    "products": [
      {
        "product_name": "Product Name",
        "minimum_fee": 0.00,
        "sub_total": 800.00,
        "total": 1000.00
      }
    ],
    "contract": {
      "contract_ref": "32c320bb-431b-488f-bcd4-729e495a33ad",
      "contract_number": 123
    },
    "number_in_contract": 1,
    "total_in_contract": 1050.00,
    "billing_bank_transfer_details": {
      "billing_account_id": "32c320bb-431b-488f-bcd4-729e495a33ad"
    },
    "billing_online_payment_details": {
      "auto_charge": true,
      "payment_gateway_id": "32c320bb-431b-488f-bcd4-729e495a33ad",
      "payment_gateway_card_id": "card_abcdef1234567890"
    },
    "billing_crypto_details": {
      "address": "0x1234567890abcdef1234567890abcdef12345678",
      "tokens": ["BTC", "ETH"]
    },
    "entity": {
      "entity_ref": "32c320bb-431b-488f-bcd4-729e495a33ad",
      "entity_name": "Supplier Name",
      "entity_legal_name": "Supplier legal Name",
    }
  }

Response Schema

Field Name	Type	Description	Example
invoice_ref	String	The ID of the related invoice	3a7b0f7d-fdf6-4f54-90f4-2307b73ae85f
document_number	String	Invoice number	PO-2024-12345
customer	Object	The related customer
customer_ref	String	The ID of the related customer	fae8fc36-d321-473f-9890-a9cb16deb4dd
customer_name	String	The name of the related customer	Acme
customer_legal_name	String	The legal name of the related customer	Acme Inc.
state	String	The current state of the invoice	PAID
created_at	String	The date of invoice creation. Standard time format "ISO 8601"	2023-08-01T00:00:00Z
issue_date	String	The date that the invoice should be issued. Standard date format "ISO 8601"	2024-02-05
due_date	String	The max date that the invoice should be paid. Standard date format "ISO 8601"	2024-02-05
submission_date	String	The date on which the invoice was submitted to a customer. Standard time format "ISO 8601"	2023-08-01T00:00:00Z
paid_date	String	The date that the invoice was paid. Standard date format "ISO 8601"	2024-02-05
is_partial_period	Boolean	Is the period of the invoice is a prtial period	false
accounting_event_type	String	The type of the accounting event of the document	INVOICE
currency	String	The currency of the invoice	USD
net_terms	Number	The default net terms used for this company, It must be a positive number or a payment term: "DUE_UPON_RECEIPT", "DUE_UPON_USAGE"	DUE_UPON_RECEIPT
sub_total	Number	The subtotal of the invoice	1000.00
total_discount	Number	The total discount applied on the invoice	100.00
total_tax	Number	The total tax applied on the invoice	50.00
credits_amount	Number	The amount of credit applied on the invoice	0.00
total	Number	The total amount of the invoice	950.00
contract	Object	The related contract
contract_ref	String	The ID of the related contract	3a7b0f7d-fdf6-4f54-90f4-2307b73ae85f
contract_number	Number	The number of the related contract	335
number_in_contract	Number	The serial number of the invoice inside the contract	1
total_in_contract	Number	The total amount if the contract	1050.00
products	Array	A list of the products associated with the contract
product_name	String	The name of the product	Smartwatch
minimum_fee	number	The minimum fee of the product	0.00
sub_total	Number	The subtotal of the product	800.00
total	Number	The total amount of the product	1000.00
billing_bank_transfer_details	Object	Bank account details
billing_account_id	String	The ID of the bank account	3a7b0f7d-fdf6-4f54-90f4-2307b73ae85f
billing_online_payment_details	Object	Online payment details
auto_charge	Boolean	Indicates whether the charging should be automatic or not	true
payment_gateway_id	String	The ID of the payment gateway	3a7b0f7d-fdf6-4f54-90f4-2307b73ae85f
payment_gateway_card_id	String	The ID of a specific card defined in the payment gateway account	card_abcdef1234567890
billing_crypto_details	Object	The details of the crypto wallet
address	String	The address of the crypto wallet	1Lbcfr7sAHTD9CgdQo3HTMTkV8LK4ZnX71
tokens	Array	The crypto tokens that supported by the wallet	["BTC", "ETH"]
entity	Object	The related entity
entity_ref	String	The ID of the related supplier entity	7f90df6e-b833-4bfa-b6d8-ac6cbe347bc6
entity_name	String	The name of the related entity	US Entity
entity_legal_name	String	The legal name of the related entity	US Entity Ltd

Get Customer / Contract Invoices

GET https://api.received.ai/api/documents/filter

URL Params

Field Name		Description	Example
customer_refs	List<String>	The IDs of the customers
contract_refs	List<String>	The IDs of the contracts
limit*	Number	Page size	50
page*	Number	Page number	0

Response

// List of invoices

Explore More APIs

Delves into additional invoices methods, broadening your integration capabilities and enhancing secure access

Reconcile Invoice / Mark Paid Invoice

The Reconcile Invoice API facilitates the comparison and adjustment of invoice records with actual transactions, ensuring that payment details align with billed services, thereby streamlining the accounting process and enhancing financial accuracy

GET https://api.received.ai/api/invoices/reconcile

{
  "invoice_ref": "3a7b0f7d-fdf6-4f54-90f4-2307b73ae85f",
  "paid_date": "2024-04-02T14:36:36.630Z"
}

Response

Updated invoice object