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