Contracts

Create, update and fetch contracts information.

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.

Endpoint on this page
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>

Don't forget! APIs must include:

  1. Bearer Token - return from the login call

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

Mange customer contracts

Customers & Products

Please refer to Customer and Product APIs pages

Create Contract

POST https://api.received.ai/api/contracts/
Request
{
  "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",
        }
      ]
    }
  ]
}
Extensive request 
{
  "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}}]
      }
    }
  ]
}

Response

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

Request Schema

Contract scheme

Field Name
Type
Description
Example

customer_ref*

String

The ID of the related customer

3a7b0f7d-fdf6-4f54-90f4-2307b73ae85f

po_number

String

Purchase order number

PO-2024-12345

products

Array<Product>

A list of the products associated with the contract

Product schema

Field Name
Type
Description
Example

product_pricing_ref*

String

The ID of the related pricing model

3a7b0f7d-fdf6-4f54-90f4-2307b73ae85f

billing_start_date*

String

Billing start date

2024-01-01

billing_end_date*

String

Billing end date

2025-12-31

line_items

Array

Selected lineitems from the pricing.

If not set, all lineitems in the pricing will be added. Empty list will add pricing with no lineitems.

line_item_id

String

The ID of the related lineitem in the pricing model

3a7b0f7d-fdf6-4f54-90f4-2307b73ae85f

entity_ref

String

The ID of the related supplier entity

7f90df6e-b833-4bfa-b6d8-ac6cbe347bc6

billing_cycle

Object

The interval of time during which invoices are prepared

unit

String

The time unit of the interval. Options

ONE_TIME/MONTHLY/YEARLY/QUARTERLY

MONTHLY

cycle

Number

The number of time units between the intervals

1

issue_day

String

The date when the first invoice should be issued. Standard date format "ISO 8601". If not defined, will be set s.t. last invoice will not be partial.

2024-02-10

payment_time

String

Determines the timing of the payment relative to the billing period. Options 

BEFORE_USE/DURING_USE/AFTER_USE

BEFORE_PERIOD

tax

Number

The percentage of tax to apply on the invoices

17

discount

Number

The percentage of discount to apply on the invoices

10

note

String

An free-form text field related to the contract

"Special offer"

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"]

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_RECEIPT

Response Schema

Term
Type
Description
Example

contract_ref

String

Contract reference

32c320bb-431b-488f-bcd4-729e495a33ad

Cancel Contract

POST https://api.received.ai/api/contracts/cancel/<contract_ref>
{
  "include_current_invoice": false
}

Response

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

Request Schema

Term
Type
Description
Example

contract_ref*

String

Contract reference

32c320bb-431b-488f-bcd4-729e495a33ad

Edit Contract

POST https://api.received.ai/api/contracts/edit/<contract_ref>
Request
{
  "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",
        }
      ]
    }
  ]
}

Response

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

Request Schema

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

Field Name
Description
Example

contract_ref*

String

The ID of the edited contract

3a7b0f7d-fdf6-4f54-90f4-2307b73ae85f

include_current_invoice

Boolean

Should the change be applied on the current invoice or start from the next one. The default value is "false"

false

Explore More APIs

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

Get Contract

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

Response

// Contract scheme

Get Customer Contracts

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

URL Params

Field Name
Description
Example

customer_ref*

String

The ID of the customer

pageSize*

Number

Page size

20

pageNumber*

Number

Page number

0

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

Response

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

Contract invoices

See invoices API

Get Current Invoices

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

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

Response

// List of invoices

Invoices schema can be found in invoices page

Get Next Invoices

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

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

Response

// List of invoices

Invoices schema can be found in invoices page

PreviousCustomersNextInvoices

Last updated

Logo

All Rights Reserved