> For the complete documentation index, see [llms.txt](https://docs.received.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.received.ai/api-docs/contracts.md).

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