# 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