# Invoices

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.  

{% code title="Endpoint on this page" lineNumbers="true" %}

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

{% endcode %}

{% hint style="info" %}
Don't forget! APIs must include:

1. **Bearer Token** - return from the login call
2. **API version** - {"Version": "V0"}
   {% endhint %}

## 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

{% code lineNumbers="true" %}

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

{% endcode %}

#### Response

<pre class="language-javascript" data-line-numbers><code class="lang-javascript">{
    "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",
    }
  }
<strong>
</strong></code></pre>

#### Response Schema

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

### Get Customer / Contract Invoices

{% code lineNumbers="true" %}

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

{% endcode %}

**URL Params**

<table><thead><tr><th width="238">Field Name</th><th width="129"></th><th width="339">Description</th><th width="341">Example</th></tr></thead><tbody><tr><td><code>customer_refs</code></td><td><mark style="color:purple;">List&#x3C;String></mark></td><td>The IDs of the customers </td><td></td></tr><tr><td><code>contract_refs</code></td><td><mark style="color:purple;">List&#x3C;String></mark></td><td>The IDs of the contracts </td><td></td></tr><tr><td><code>limit</code><mark style="color:red;">*</mark></td><td><mark style="color:purple;">Number</mark></td><td>Page size </td><td>50</td></tr><tr><td><code>page</code><mark style="color:red;">*</mark></td><td><mark style="color:purple;">Number</mark></td><td>Page number</td><td>0</td></tr></tbody></table>

#### **Response**

{% code lineNumbers="true" %}

```javascript
// List of invoices
```

{% endcode %}

## 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

{% code lineNumbers="true" %}

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

{% endcode %}

{% code lineNumbers="true" %}

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

{% endcode %}

#### Response

Updated invoice object


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.received.ai/api-docs/invoices.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.