# Contracts

Received's Contract APIs allow users to manage their contracts. The APIs support operations such as creating a new contract, manipulating existing contracts, cancelling active contracts and fetching contracts' related data.   

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

```javascript
POST https://api.received.ai/api/contracts/
POST https://api.received.ai/api/contracts/cancel/<contract_ref>
POST https://api.received.ai/api/contracts/edit/<contract_ref>
GET https://api.received.ai/api/contracts/<contract_ref>
GET https://api.received.ai/api/contracts/filter
GET https://api.received.ai/api/contracts/invoices/current/<contract_ref>
GET https://api.received.ai/api/contracts/invoices/next/<contract_ref>
```

{% endcode %}

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

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

## Mange customer contracts

### Customers & Products

Please refer to [Customer](/api-docs/customers.md) and [Product](/api-docs/products.md) APIs pages

### Create Contract

{% code lineNumbers="true" %}

```javascript
POST https://api.received.ai/api/contracts/
```

{% endcode %}

<pre class="language-javascript" data-title="Request" data-line-numbers><code class="lang-javascript"><strong>{
</strong>  "customer_ref": "e0b8d5f5-6c4c-4ce9-bf21-1e52c2c4770a",
  "po_number": "PO123456",
  "products": [
    {
      "product_pricing_ref": "a3c4e5f6-7b8d-9e0f-1234-5a6b7c8d9e0f",
      "billing_start_date": "2023-01-01",
      "billing_end_date": "2023-12-31",
      "line_items": [
        {
          "line_item_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
        }
      ]
    }
  ]
}
</code></pre>

<pre class="language-javascript" data-title="Extensive request " data-line-numbers><code class="lang-javascript">{
  "customer_ref": "e0b8d5f5-6c4c-4ce9-bf21-1e52c2c4770a",
  "po_number": "PO123456",
  "products": [
    {
      "product_pricing_ref": "a3c4e5f6-7b8d-9e0f-1234-5a6b7c8d9e0f",
      "billing_start_date": "2023-01-01",
      "billing_end_date": "2023-12-31",
      "line_items": [
        {
          "line_item_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
        }
      ],
      "entity_ref": "a3c4e5f6-7b8d-9e0f-1234-5a6b7c8d9e0f",
      "billing_cycle": {
          "unit": "MONTHLY",
          "cycle": 1
      },
      "issue_day": {{first-invoice-day yyyy-mm-dd}},
      "payment_time": {{BEFORE_USE/DURING_USE/AFTER_USE}},
      "tax": {{tax-percentage}},
      "discount": {{discount-percentage}},
      "net_terms": {{days-number/DUE_UPON_RECEIPT}},
      "note": {{note}},
      "billing_bank_transfer_details": {
          "billing_account_id": {{billing_account_id}}
      },
      "billing_online_payment_details": {
          "auto_charge": {{bool}},
          "payment_gateway_id": {{payment_gateway_id}},
          "payment_gateway_card_id": {{payment_gateway_card_id}}
      },
      "billing_crypto_details": {
          "address": {{address-wolet}},
          "tokens": [{{USDC/USDT}}]
      }
    }
  ]
<strong>}
</strong></code></pre>

#### **Response**

{% code lineNumbers="true" %}

```javascript
{
  "contract_ref": "32c320bb-431b-488f-bcd4-729e495a33ad"
}
```

{% endcode %}

#### **Request Schema**

**Contract scheme**

<table><thead><tr><th width="183">Field Name</th><th>Type</th><th width="282">Description </th><th width="365">Example</th></tr></thead><tbody><tr><td><code>customer_ref</code><mark style="color:red;">*</mark></td><td><mark style="color:purple;">String</mark></td><td>The ID of the related customer </td><td>3a7b0f7d-fdf6-4f54-90f4-2307b73ae85f</td></tr><tr><td><code>po_number</code></td><td><mark style="color:purple;">String</mark></td><td>Purchase order number</td><td>PO-2024-12345</td></tr><tr><td><code>products</code></td><td><mark style="color:purple;">Array&#x3C;Product></mark></td><td>A list of the products associated with the contract</td><td></td></tr></tbody></table>

**Product schema**

<table><thead><tr><th width="348">Field Name</th><th width="105">Type</th><th width="475">Description </th><th width="348">Example</th></tr></thead><tbody><tr><td><code>product_pricing_ref</code><mark style="color:red;">*</mark></td><td><mark style="color:purple;">String</mark></td><td>The ID of the related pricing model </td><td>3a7b0f7d-fdf6-4f54-90f4-2307b73ae85f</td></tr><tr><td><code>billing_start_date</code><mark style="color:red;">*</mark></td><td><mark style="color:purple;">String</mark></td><td>Billing start date</td><td>2024-01-01</td></tr><tr><td><code>billing_end_date</code><mark style="color:red;">*</mark></td><td><mark style="color:purple;">String</mark></td><td>Billing end date</td><td>2025-12-31</td></tr><tr><td><code>line_items</code></td><td><mark style="color:purple;">Array</mark></td><td><p>Selected lineitems from the pricing. </p><p>If not set,  all lineitems in the pricing will be added.<br>Empty list will add pricing with no lineitems.</p></td><td></td></tr><tr><td>    <code>line_item_id</code></td><td><mark style="color:purple;">String</mark></td><td>The ID of the related lineitem in the pricing model </td><td>3a7b0f7d-fdf6-4f54-90f4-2307b73ae85f</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>billing_cycle</code></td><td><mark style="color:purple;">Object</mark></td><td>The interval of time during which invoices are prepared</td><td></td></tr><tr><td>    <code>unit</code></td><td><mark style="color:purple;">String</mark></td><td><p>The time unit of the interval. Options</p><pre class="language-postman_json"><code class="lang-postman_json">ONE_TIME/MONTHLY/YEARLY/QUARTERLY
</code></pre></td><td>MONTHLY</td></tr><tr><td>    <code>cycle</code></td><td><mark style="color:purple;">Number</mark></td><td>The number of time units between the intervals</td><td>1</td></tr><tr><td><code>issue_day</code></td><td><mark style="color:purple;">String</mark></td><td>The date when the first invoice should be issued.<br>Standard date format "ISO 8601".<br>If not defined, will be set s.t. last invoice will not be partial.</td><td>2024-02-10</td></tr><tr><td><code>payment_time</code></td><td><mark style="color:purple;">String</mark></td><td><p>Determines the timing of the payment relative to the billing period. Options </p><pre class="language-postman_json"><code class="lang-postman_json">BEFORE_USE/DURING_USE/AFTER_USE
</code></pre></td><td>BEFORE_PERIOD</td></tr><tr><td><code>tax</code></td><td><mark style="color:purple;">Number</mark></td><td>The percentage of tax to apply on the invoices</td><td>17</td></tr><tr><td><code>discount</code></td><td><mark style="color:purple;">Number</mark></td><td>The percentage of discount to apply on the invoices</td><td>10</td></tr><tr><td><code>note</code></td><td><mark style="color:purple;">String</mark></td><td>An free-form text field related to the contract</td><td>"Special offer"</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>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"</td><td>DUE_UPON_RECEIPT</td></tr></tbody></table>

#### **Response Schema**

<table><thead><tr><th width="229">Term</th><th width="93">Type</th><th width="193">Description</th><th width="357">Example</th></tr></thead><tbody><tr><td><code>contract_ref</code></td><td><mark style="color:purple;">String</mark></td><td>Contract reference</td><td>32c320bb-431b-488f-bcd4-729e495a33ad</td></tr></tbody></table>

### Cancel Contract

<pre class="language-javascript" data-line-numbers><code class="lang-javascript"><strong>POST https://api.received.ai/api/contracts/cancel/&#x3C;contract_ref>
</strong></code></pre>

{% code lineNumbers="true" %}

```javascript
{
  "include_current_invoice": false
}
```

{% endcode %}

#### **Response**

{% code lineNumbers="true" %}

```javascript
{
  "contract_ref": "32c320bb-431b-488f-bcd4-729e495a33ad",
  // Contract scheme
}
```

{% endcode %}

#### Request Schema

<table><thead><tr><th width="229">Term</th><th>Type</th><th width="182">Description</th><th width="359">Example</th></tr></thead><tbody><tr><td><code>contract_ref</code><mark style="color:red;">*</mark></td><td><mark style="color:purple;">String</mark></td><td>Contract reference</td><td>32c320bb-431b-488f-bcd4-729e495a33ad</td></tr></tbody></table>

### Edit Contract

{% code lineNumbers="true" %}

```javascript
POST https://api.received.ai/api/contracts/edit/<contract_ref>
```

{% endcode %}

<pre class="language-javascript" data-title="Request" data-line-numbers><code class="lang-javascript"><strong>{
</strong>  "include_current_invoice": false,
  
  "customer_ref": "e0b8d5f5-6c4c-4ce9-bf21-1e52c2c4770a",
  "po_number": "PO123456",
  "products": [
    {
      "product_pricing_ref": "a3c4e5f6-7b8d-9e0f-1234-5a6b7c8d9e0f",
      "billing_start_date": "2023-01-01",
      "billing_end_date": "2023-12-31",
      "line_items": [
        {
          "line_item_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
        }
      ]
    }
  ]
}
</code></pre>

#### **Response**

{% code lineNumbers="true" %}

```javascript
{
  "contract_ref": "32c320bb-431b-488f-bcd4-729e495a33ad"
  // Contract scheme
}
```

{% endcode %}

#### Request Schema

In addition to the **contract schema** (see Create Contract above):

<table><thead><tr><th width="285">Field Name</th><th width="119"></th><th width="339">Description</th><th width="341">Example</th></tr></thead><tbody><tr><td><code>contract_ref</code><mark style="color:red;">*</mark></td><td><mark style="color:purple;">String</mark></td><td>The ID of the edited contract </td><td>3a7b0f7d-fdf6-4f54-90f4-2307b73ae85f</td></tr><tr><td><code>include_current_invoice</code></td><td><mark style="color:purple;">Boolean</mark></td><td>Should the change be applied on the current invoice or start from the next one. The default value is "false"</td><td>false</td></tr></tbody></table>

## Explore More APIs

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

### Get Contract

{% code lineNumbers="true" %}

```javascript
GET https://api.received.ai/api/contracts/<contract_ref>
```

{% endcode %}

#### **Response**

{% code lineNumbers="true" %}

```javascript
// Contract scheme
```

{% endcode %}

### Get Customer Contracts

{% code lineNumbers="true" %}

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

{% endcode %}

**URL Params**

<table><thead><tr><th width="285">Field Name</th><th width="119"></th><th width="339">Description</th><th width="341">Example</th></tr></thead><tbody><tr><td><code>customer_ref</code><mark style="color:red;">*</mark></td><td><mark style="color:purple;">String</mark></td><td>The ID of the customer </td><td></td></tr><tr><td><code>pageSize</code><mark style="color:red;">*</mark></td><td><mark style="color:purple;">Number</mark></td><td>Page size </td><td>20</td></tr><tr><td><code>pageNumber</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>

{% code title="Example" lineNumbers="true" %}

```javascript
GET https://api.received.ai/api/contracts/filter?pageSize=20&pageNumber=0&customer_ref=1c577d64-ced0-4fce-a40f-9da39032d8c4
```

{% endcode %}

#### **Response**

```javascript
[
  {
    "contract_ref": "f9ab37b9-b96a-488c-b04e-604c7cb374fa",
    "customer_ref": "string",
    "po_number": "string",
    "products": []
  }
]
```

### Contract invoices

See [invoices API](https://docs.received.ai/api-docs/invoices#get-customer-contract-invoices)

### Get Current Invoices

Returns the invoices for the ongoing billing period of the contract.

{% code overflow="wrap" lineNumbers="true" %}

```javascript
GET https://api.received.ai/api/contracts/invoices/current/<contract_ref>
```

{% endcode %}

#### **Response**

{% code lineNumbers="true" %}

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

{% endcode %}

Invoices schema can be found in [invoices page](https://docs.received.ai/api-docs/invoices#response-schema)

### Get Next Invoices

Returns the invoices for the next billing period of the contract.

{% code overflow="wrap" lineNumbers="true" %}

```javascript
GET https://api.received.ai/api/contracts/invoices/next/<contract_ref>
```

{% endcode %}

#### **Response**

{% code lineNumbers="true" %}

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

{% endcode %}

Invoices schema can be found in [invoices page](https://docs.received.ai/api-docs/invoices#response-schema)


---

# 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/contracts.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.