# Platform Overview

Received is a B2B Billing & Revenue management platform, made for B2B finance teams managing custom contracts and complex pricing models, looking to automate their operations and gear up for growth.

## Complex B2B Billing, Solved. 

Got 2 minutes? Check out a video overview of our platform:

{% embed url="<https://www.youtube.com/watch?v=bNIp0bCYUSM>" %}
Received - B2B Billing, Solved.&#x20;
{% endembed %}

***

> ## Received makes it easy for B2B finance teams to operate in this ever-changing market. <a href="#w-node-_99429bac-7aa4-f1ab-433a-b20cc4c95e79-0f04bc83" id="w-node-_99429bac-7aa4-f1ab-433a-b20cc4c95e79-0f04bc83"></a>
>
> As B2B go-to-market motions and pricing models evolve and become increasingly complex, B2B finance teams need a flexible solution that will allow them to remain agile in their business operations.
>
> By providing full commercial flexibility, removing business barriers and letting automation handle the heavy lifting, finance teams can eliminate time-consuming manual tasks and focus on creating real value.

## **Received - Full B2B Revenue Stack for Modern Finance Teams**

* Made for B2B finance teams managing custom contracts and complex pricing models, looking to streamline their processes and gear up for growth.
* A next generation integrated financial system that combines all revenue streams into one central hub to manage cash flow and revenue.
* A plug & play platform transforming payments and business revenues to open up new revenue streams, prevent revenue leakage, and unlock the full potential of every enterprise.

<figure><img src="/files/W11fvhQlN87yACEal0yU" alt=""><figcaption><p>Received's Stack</p></figcaption></figure>

***

## Benefits of Received 💸

### Operational Efficiency <a href="#operational_efficiency" id="operational_efficiency"></a>

#### Turn manual tangled processes into a smooth automated workflow to save work time, money and resources.

<table data-view="cards" data-full-width="true"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><p><strong>Prevent Revenue Leakage</strong> <br></p><p>Let the machine calculate and keep track of every single event to ensure nothing slips through the cracks and your revenue is always kept in check.</p></td><td></td><td></td><td><a href="/files/d7l7jFCDXXvvODBY4a4c">/files/d7l7jFCDXXvvODBY4a4c</a></td></tr><tr><td><strong>Reduce Month Close Time</strong></td><td><br>Reduce month close time from days to hours and free up your team to focus on excellence , and less repetitive work.</td><td></td><td><a href="/files/AdL3RwB7JJlsUXzXou8p">/files/AdL3RwB7JJlsUXzXou8p</a></td></tr><tr><td><strong>Reduce DSO</strong></td><td><br>Send bills way faster, and reduce sales to cash timeline. Build an efficient invoicing and collections process and keep a healthy cash flow.</td><td></td><td><a href="/files/COBrBMrXBxhhjJiGbYsE">/files/COBrBMrXBxhhjJiGbYsE</a></td></tr></tbody></table>

### Flexible Scalability

**Remove capacity barriers and gain flexible scalability for rapid growth.**

<table data-view="cards" data-full-width="true"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><p><strong>Flexible Scalability</strong><br></p><p><br>Remove capacity barriers and gain flexible scalability for rapid growth.</p></td><td></td><td></td><td><a href="/files/QrW5rYiThYG0rz9u87LZ">/files/QrW5rYiThYG0rz9u87LZ</a></td></tr><tr><td><p><strong>Open Up New Revenue Streams</strong> </p><p><br>Don’t let systems be your business model bottleneck - we enable any revenue stream - self-serve, sales-led and partners - in one system.</p></td><td></td><td></td><td><a href="/files/3dFYYXWvFF9YYvdaXJx4">/files/3dFYYXWvFF9YYvdaXJx4</a></td></tr><tr><td><p><strong>All Systems Sing in Harmony</strong> <br></p><p>Stop worrying about data inputs into different systems, and seamlessly sync with your CRM, ERP, PSP and Tax systems for smooth data flow.</p></td><td></td><td></td><td><a href="/files/wn6BXTnQdMQ4yB1dfpyP">/files/wn6BXTnQdMQ4yB1dfpyP</a></td></tr></tbody></table>

### Data Control

**Take control of your financial data, regain trust in the numbers, and improve decision-making.**

<table data-view="cards" data-full-width="true"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><strong>Single Source of Truth</strong> <br><br><br>Replace messy, error-prone data with a single source of truth for clean and accurate financial data.</td><td></td><td></td><td><a href="/files/QFaGG7qBYRtYpfoSCwaV">/files/QFaGG7qBYRtYpfoSCwaV</a></td></tr><tr><td><strong>Better Decision Making</strong> <br><br><br>Utilize reliable and comprehensive data to make better cross-functional strategic decisions and accelerate growth.</td><td></td><td></td><td><a href="/files/q08q4Mgv5OoxROflbo58">/files/q08q4Mgv5OoxROflbo58</a></td></tr><tr><td><strong>Access B2B Insights at Every Level</strong> <br><br>Utilize analytics dashboards at the company, customer, or contract level to deep dive into billing, revenue, and usage analytics.</td><td></td><td></td><td><a href="/files/GIGscUG194AC7LCDcJOY">/files/GIGscUG194AC7LCDcJOY</a></td></tr></tbody></table>


# Our Features

Whether you're managing Enterprise Contracts, Self-Serve Subscriptions, or Channel Partners - Received's robust platform enables you to customize and automate every step of the way.

## Pricing Configuration

* **Any pricing model** - complete pricing flexibility for growth and experimentation.
* **B2B Pricing** - pricing configuration built for B2B companies. Usage pricing, recurring licenses and services built for B2B complexity.
* **‘Spreadsheet-in-a-System’** - power or a spreadsheet, within a system, giving you the brain you need, in a format you love.

![](/files/g8Vt63iloNtge1JRcCHD)

## Contract Management

* **Bespoke B2B Logic** - create complex B2B contracts with various products and services in minutes.
* **One Contract Hub** - manage all contract metrics from one place. Cashflow, Revenue, Renewal and more.
* **CRM Automation** - sync with your CRM to automate customer and contract creation.

![](/files/OwYYLpkR3vZbcOnwX1Ox)

## Invoice Automation

* **Contract-based-Billing** - turn complicated contracts into accurate invoices created automatically, delivered right on time.
* **Invoice Configuration** - define your own bespoke invoice formats and select which data and line items will be shown for each customer.
* **Accounting Compatibility** -All the Invoice and revenue data synced with your accounting system.

<figure><img src="/files/B3tKH8BzuiBALNaywd5F" alt=""><figcaption></figcaption></figure>

## Usage Tracking

* **Automate Usage Billing -** fully automate your usage tracking using API, or upload usage data manually or in bulk using a CSV file.
* **Usage for B2B** - manage usage scenarios, such as sub-activity, formula manipulation (running average, aggregation), and debit/credit relationships.
* **Usage Reporting -** keep track of usage product performance, analyze performance by product or cash flow over time.

<figure><img src="/files/9YuFZelTfFk1ZzlFbMep" alt=""><figcaption></figcaption></figure>

## Payment Collection

* **Invoice-Native-Checkout** - allow customers to make instant payments straight from the invoice.
* **Auto-Charge** - automatically charge customers according to their selected plan.
* **Automatic Reconciliation** - automatically match incoming payments with outstanding invoices.
* **No Extra Fees** - manage data and payment activities from your payment provider account.

<figure><img src="/files/SQxfsagbYj2ny30vY4Cy" alt=""><figcaption></figcaption></figure>

## Revenue Recognition

* **Contract-Native -** define each B2B contract its own revenue recognition logic.&#x20;
* **Built for ASC 606 and IFRS 15** - configure and automate revenue recognition for ASC-606 and IFRS 15 compliance.
* **Contract Financial Hub** - track cash flow, revenue recognition, invoices, usage and more.
* **Company Revenue Recognition -** manage company level metrics: revenue recognized, deferred revenue, cash collection, and more.&#x20;

<figure><img src="/files/fBxGswS9rIOyr54fzu2O" alt=""><figcaption></figcaption></figure>


# System Integrations

No-Code integrations with your CRM, ERP and Tax and Payments software. Unlock speed and insights with data consistency across teams and systems.

## **CRM Integration**

* **Two-Way Integration** - connect and sync your billing system activity directly to your CRM account.
* **Data Integrity** - enhance billing automation with complete data integrity between the Sales and Finance functions.

<div align="left"><figure><img src="/files/inwYUrOWgKGED6Pj4niU" alt="" width="188"><figcaption></figcaption></figure> <figure><img src="/files/3tK9vWneWJ3fOMXojeN2" alt="" width="188"><figcaption></figcaption></figure></div>

## **ERP/ Accounting Integration**

* **Two-Way Integration** - connect and sync your billing system activity directly to your ERP/Accounting account.
* **Automatic Data Validation** - eliminate manual data verification and field corrections.

<div><figure><img src="/files/SlyaS1BQAbCRbIBZqcPt" alt="" width="188"><figcaption></figcaption></figure> <figure><img src="/files/l2QJiGY7vq0M6QXYTa08" alt="" width="563"><figcaption></figcaption></figure> <figure><img src="/files/di77XblpkqRTM4c5vecv" alt="" width="375"><figcaption></figcaption></figure></div>

## **Payment Service Provider Integration**

* **Invoice-Native-Checkout** - allow customers to make  instant payments straight from the invoice.
* **Automatic Reconciliation** -automatically match incoming payments with outstanding invoices.
* **No extra fees** - manage data and payment activities from your payment provider account.

<div align="left"><figure><img src="/files/92VkassKtXize9LWa1FZ" alt="" width="188"><figcaption></figcaption></figure></div>

## **Tax Compliance Integration**

* **Automate Tax Compliance** - automatically apply tax rates and keep up with the latest location-based tax rates and obligations.
* **Tax-to-ERP Sync** - integrate with your ERP/Accounting system for a single source of truth.

<div align="left"><figure><img src="/files/ImX8zGHV7pOpz0pkcvjA" alt="" width="188"><figcaption></figcaption></figure></div>


# B2B Revenue Streams

Manage all All B2B revenue streams in one place.

**Received's platform is specifically designed to fit all B2B use cases:** self-serve customers, sales-led contracts, and partners.&#x20;

### Automate Sales-Led Contracts

Manage sales-led customers and automate contract-based billing for bespoke multi-year contracts with various products and pricing models.

<figure><img src="/files/UIAUvK3QbwPqaEmfuXHg" alt=""><figcaption></figcaption></figure>

### Automate Self-Serve Subscriptions

Embed Received into your website to manage self-serve customers and auto-charge self-serve contracts.

<figure><img src="/files/EBGjwXSnyrepr4urHjAC" alt=""><figcaption></figcaption></figure>

### Automate Partner Management

Manage referral and reseller billing, automate partner fees and sales commissions, and monitor partner activity.

<figure><img src="/files/20mndAtheXsMBVf979m1" alt=""><figcaption></figcaption></figure>


# Overview

Automate contract-based Billing with Received.

<figure><img src="/files/4JTNfrI510DGv0eXpVz2" alt=""><figcaption></figcaption></figure>

### **Use Received to manage bespoke enterprise contracts and automate contract-based billing:**

1. Build your products and define pricing.
2. Create and customize B2B contracts.
3. Track usage for usage-based products.
4. Automatically send invoices.
5. Collect payments.
6. Automatically reconcile payments.
7. Automatically recognize revenue.

![](/files/mLhyFYWfjhLOApZfXuNR)


# Key Features

Configure complex B2B pricing, manage bespoke enterprise contracts and automate contract-based invoicing. You set the logic, let the system do the rest.

### Automate Billing for Enterprise Contracts

* **Contract-based-Billing** - turn complicated contracts into accurate invoices created automatically, delivered right on time.
* **Invoice Configuration** - define your own bespoke invoice formats and select which data and line items will be shown for each customer.
* **Accounting Compatibility** -All the Invoice and revenue data synced with your accounting system.

<figure><img src="/files/MyBqgRnp8ZtOvkhUc7Qa" alt=""><figcaption></figcaption></figure>

### **Configure Any B2B Pricing Model**

* **Any pricing model** - complete pricing flexibility for growth and experimentation.
* **B2B Pricing** - pricing configuration built for B2B companies. Usage pricing, recurring licenses and services built for B2B complexity.
* **‘Spreadsheet-in-a-System’** - power or a spreadsheet, within a system, giving you the brain you need, in a format you love.

<figure><img src="/files/coPktiEGoChyJaHtp1xJ" alt=""><figcaption></figcaption></figure>

### **Manage Bespoke B2B Contracts**

* **Bespoke B2B Logic** - create complex B2B contracts with various products and services in minutes.
* **One Contract Hub** - manage all contract metrics from one place. Cashflow, Revenue, Renewal and more.
* **CRM Automation** - sync with your CRM to automate customer and contract creation.

<figure><img src="/files/ptqO2ajTa5PtVFxzJHLk" alt=""><figcaption></figcaption></figure>

### **Automate Payment Collection**

* **Invoice-Native-Checkout** - allow customers to make  instant payments straight from the invoice.
* **Automatic Reconciliation** - automatically match incoming payments with outstanding invoices.
* **No Extra Fees** -manage data and payment activities from your payment provider account.

<figure><img src="/files/mYddJijYW9N4bDX7A5Fi" alt=""><figcaption></figcaption></figure>


# The Enterprise Contract Billing Process

Follow our step-by-step guide to see how to set up Enterprise Contract billing automation.

<figure><img src="/files/SsvTLQW2m1XX6bX23lQc" alt=""><figcaption></figcaption></figure>

<table data-column-title-hidden data-view="cards" data-full-width="true"><thead><tr><th data-card-target data-type="content-ref"></th><th data-hidden></th><th data-hidden></th><th data-hidden></th></tr></thead><tbody><tr><td><a href="/pages/y6P5ClsaLCteKRnfRoht">/pages/y6P5ClsaLCteKRnfRoht</a></td><td></td><td></td><td></td></tr><tr><td><a href="/pages/qvLG7lvFCCijbTOY11g6">/pages/qvLG7lvFCCijbTOY11g6</a></td><td></td><td></td><td></td></tr><tr><td><a href="/pages/xu7l8lqiSp4FT3cMeH0B">/pages/xu7l8lqiSp4FT3cMeH0B</a></td><td></td><td></td><td></td></tr></tbody></table>


# Set Up Enterprise Contracts

## Step 1: Create Products and Define Pricing

Navigate to the **Pricing Tab** to create products and define their pricing models. Use **ready-made templates** or start from scratch to create your model.

<figure><img src="/files/ZNhk4chT1bWHtUNqViqF" alt=""><figcaption></figcaption></figure>

Click **'Use this Pricing'** and use our **‘Spreadsheet-in-a-System’** to edit your pricing. Edit line items, change prices and ranges, connect usage products, define billing logic and more. Once you're done, click on **'Publish'** to save the product and add it to your products catalog.&#x20;

<figure><img src="/files/qqWEEAfbSaUcxI69qlno" alt=""><figcaption></figcaption></figure>

## Step 2: Create a Customer

Navigate to the Customers tab and click on **'New Customer'** to create a customer in the system. Fill in the details and click **'Save'** to add the customer to your customers list.

<figure><img src="/files/okVcIAlTMVJEcnw1Tt7z" alt=""><figcaption></figcaption></figure>

## Step 3: Create a Contract

Navigate to the **'Customers Tab'** and click on **'Create a Contract'.** Click on **'Search'** to add the relevant customer to the contract. \
\
To add products to the contract, either **select an existing product** from the product catalog, or create a new one from scratch. You can add **multiple products** with **varying pricing models** to the same contract.&#x20;

<figure><img src="/files/xJgqursRqUafs3jj90fw" alt=""><figcaption></figcaption></figure>

Now it's time to edit and customize the contract. Set **Billing & Revenue Recognition logic**, and use the **‘Spreadsheet-in-a-System’** to customize the pricing for each product. Edit line items, change prices and ranges, connect usage products, and more.&#x20;

<figure><img src="/files/hsZepoWtcSKVigh6v9RQ" alt=""><figcaption></figcaption></figure>

Finally, select the **payment method** (you can add multiple payment methods per product), and add **taxes and discounts** where relevant.

<figure><img src="/files/PkRnBJn0DSDHCJdWA75s" alt=""><figcaption></figcaption></figure>

Once you finish editing the contract, click on **'Publish Contract'** to activate it.&#x20;

<figure><img src="/files/pw4gBdZp9D67KiW62MHr" alt=""><figcaption></figcaption></figure>

Use the '**Overview Tab'** to get an overview of your contract. View your **cash inflows, revenue recognition schedule**, and more.  &#x20;

<figure><img src="/files/hEW2lXn2DsesFJYWRG4Y" alt=""><figcaption></figcaption></figure>


# Automate Invoicing

## Step 1: Track Usage (for usage-based products)

In the event that a contract includes a **usage-based product**, Received's **usage API** automatically **tracks and calculates usage rates** for each customer per billing cycle.

This API is provided by Received, and **embedded into your software**, enabling automatic usage tracking.\
\
Our embeddable API looks like this:

```
usage_event = {
  "timestamp": "2024-02-05T08:55:32.160Z",
  "customer_ref": "4096966d-5c1c-4e18-8b47-6a365e3c16ea",
  "customer_name": "ACME",
  "usage_product_ref": "bb50da07-c686-4688-8550-66305e17aab0",
  "usage_product_name": "Units",
  "quantity": 10,
  "additional_report_data": {
    "note": "User-specific note"
  },
  "validations": {
    "currency": "USD",
    "entity_ref": "55899733-32a0-4912-9d2e-a5b0f04dcdb6"
  }
}

event_report_resp = requests.post('https://api.received.ai/api/usage/event', headers=headers, data=json.dumps(usage_event))
```

Once this API is embedded, usage is tracked and collected by Received. When it's time to invoice customers, Received's **internal API collects the relevant data** and calculates the total due for each specific product in the contract.

Our API looks like this:

```
// POST/api/usage/event
```

#### Request Body

Example Value

```
{
  "timestamp": "2024-02-05T09:02:27.279Z",
  "customer_ref": "b4fe1e43-321f-479c-aee7-c11d73616ff2",
  "customer_name": "ACME",
  "usage_product_ref": "9db3fbc3-5e77-43c8-828f-bc2b69cbc9f3",
  "usage_product_name": "Units",
  "quantity": 10,
  "additional_report_data": {
    "note": "User-specific note"
  },
  "validations": {
    "currency": "USD",
    "entity_ref": "d78bf43b-e76a-4a70-8f56-d3dfcea0dffe"
  }
}
```

#### Responses

Example Value

```
{
  "timestamp": "2024-02-05T09:02:27.279Z",
  "customer_ref": "b4fe1e43-321f-479c-aee7-c11d73616ff2",
  "customer_name": "ACME",
  "usage_product_ref": "9db3fbc3-5e77-43c8-828f-bc2b69cbc9f3",
  "usage_product_name": "Units",
  "quantity": 10,
  "additional_report_data": {
    "note": "User-specific note"
  },
  "validations": {
    "currency": "USD",
    "entity_ref": "d78bf43b-e76a-4a70-8f56-d3dfcea0dffe"
  }
}
```

## Step 2: Automatic Invoicing&#x20;

When the issue date is reached, Received's system **calculates the total amount due** for each product in the contract and **sends out invoices** to customers. Depending on each contract's settings, invoices can be sent **separately for each product**, or as one **collective invoice** for the entire contract.

<figure><img src="/files/8CxTWPGuQCdaKrOD6Y10" alt=""><figcaption></figcaption></figure>

## Step 3: Payment Collection

Customers can pay their invoices by credit card (via Stripe), wire transfer, or crypto wallet.&#x20;

Upon payment, Received's system automatically matches incoming payments with outstanding invoices for **seamless reconciliation** and automatically **recognizes revenue** according to **ASC-606 and IFRS-15** compliance.<br>

<figure><img src="/files/XiIi5apatPfxcdTNRh5a" alt=""><figcaption></figcaption></figure>


# Track Billing Data

## Step 1: Track Billing and Revenue Data

Navigate to the **'Dashboard Tab'** to get an overview of your **billing and revenue data**, including your collection status, Cash inflow forecast, Product Allocation, ARR, MRR and more.&#x20;

<figure><img src="/files/1qSfTs0sfA003medNmfz" alt=""><figcaption></figcaption></figure>

## Step 2: Track Usage Data&#x20;

Navigate to the **'Usage Tab'** to track all **usage data**, including Usage and Cash breakdown, Usage activities, and more.&#x20;

<figure><img src="/files/9YuFZelTfFk1ZzlFbMep" alt=""><figcaption></figcaption></figure>

## Step 3: Track Invoicing Data&#x20;

Navigate to the **'Invoices Tab'** to see an overview of your invoicing status over time. This includes sent invoices, late invoices, paid invoices, and invoices under review.

<figure><img src="/files/yvanMCiI86CHkCQjarFP" alt=""><figcaption></figcaption></figure>

## Step 4: Track Enterprise Customer's Data

Navigate to **Customers>Enterprise** to view the status of all **enterprise customers**, including an overview of your active contracts, total contracts value, and more.&#x20;

<figure><img src="/files/dQVYSgWWshMnVo3pI1AP" alt=""><figcaption></figcaption></figure>


# Overview

Automate Subscription Billing with Received.

<figure><img src="/files/beNo90L1V3QtaJnIPdGs" alt=""><figcaption></figcaption></figure>

### **Use Received's API to automate subscription billing for customers signing up on your website:**

1. Add custom subscription plans to your website.
2. Add a Stripe checkout link to collect payment info.
3. Automatically create a new customer and subscription in Received's Platform.
4. Auto-charge customers according to their selected plan and send payment confirmations.
5. Automatically reconcile payments.
6. Automatically recognize revenue.<br>

![](/files/gLhF64mo2YRuIdFPOea8)


# Key Features

Automate billing for self-serve customers from sign-up-to-cash. Set up in minutes, no engineering required.

## Embedded Checkout Links

Integrate Received with your website to offer self-serve customers a smooth onboarding experience.

* **Custom Plans** - use custom plans for a seamless sign-up experience.
* **Checkout Link** - provide customers with a Stripe checkout link to enter their credit card information for all future charges.
* **Easy Set-Up** - copy and paste Received's URL into your website for an easy, coding-free set-up.

<figure><img src="/files/VorP1nvpyM8vyHApnDtV" alt=""><figcaption></figcaption></figure>

## Hybrid Pricing Plans

Make self-serve more than a subscription. Connect Received to your website to offer unlimited pricing complexity at scale.

* **Automate Self-Serve Complex Pricing** - offer subscription-based, usage-based, and hybrid plans on your website to maximize ACV.
* **Self-Serve for Any Billing Cycle** - bill self-serve customers with any billing cycle you see fit - monthly, yearly, quarterly, per-usage, and more.&#x20;

<figure><img src="/files/MFvlBngvpiLLLWobtwkH" alt=""><figcaption></figcaption></figure>

## **Payment Collection**

Automatically charge and send payment confirmations to active subscription customers.

* **Auto-Charge** - automatically charge customers according to their selected plan.
* **Automatic Reconciliation** - automatically match auto-charged payments with outstanding balances.
* **Automatic Revenue Recognition** - define revenue recognition per subscription plan to automatically recognize revenue.

<figure><img src="/files/DTMmRtpIgtyAYfXSqaBW" alt=""><figcaption></figcaption></figure>

## **Error Handling**

&#x20;Automatically detect and resolve payment errors.

* **Error detection** - automatically detect payment errors and flag them for easy tracking.
* **Re-Charge** - automatically re-charge customers following a failed payment.
* **Automatic Error Handling** - automatically send customers with failed payments a new checkout link to update their card information.&#x20;

<figure><img src="/files/0Frxato3OtEZtrGGbzP2" alt=""><figcaption></figcaption></figure>


# The Subscription Billing Process

Follow our step-by-step guide to see how to set up subscription billing automation.

<div align="left"><figure><img src="/files/WNrfpU0eK5I5qbMBAiaF" alt=""><figcaption></figcaption></figure></div>

<table data-column-title-hidden data-view="cards" data-full-width="true"><thead><tr><th data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><a href="/pages/bvNLZfpPZaUC3MhBRByi">/pages/bvNLZfpPZaUC3MhBRByi</a></td></tr><tr><td><a href="/pages/vEtUkPDCDkYf8x1mLBDy">/pages/vEtUkPDCDkYf8x1mLBDy</a></td></tr><tr><td><a href="/pages/NY0vJ4B82RdoneeTAkNF">/pages/NY0vJ4B82RdoneeTAkNF</a></td></tr></tbody></table>


# Set Up Subscriptions

Create products, define pricing & build subscription plans to embed in your website.

## Step 1: Create Products and Define Pricing

Navigate to the **Pricing Tab** to create products and define their pricing models. Use **ready-made templates** or start from scratch to create your model.

<figure><img src="/files/46LWCh3euTViz99QkRpB" alt=""><figcaption></figcaption></figure>

Click **'Use this Pricing'** and use our **‘Spreadsheet-in-a-System’** to edit your pricing. Edit line items, change prices and ranges, connect usage products, define billing logic and more. Once you're done, click on **'Publish'** to save the product and add it to your products catalog. <br>

<figure><img src="/files/ieD4ExxAtyq3yCKhFcfL" alt=""><figcaption></figcaption></figure>

## Step 2: Create a Subscription

Navigate to **Pricing > Subscriptions** to create your subscription plans. You can add multiple products with varying pricing models to each plan. Once you're done, click on **'Update Subscription'.** \
\
Once you update a subscription plan, the platform automatically generates an **embeddable URL** for your website. This URL must be embedded in the specific plan's CTA, to ensure accurate billing.&#x20;

<figure><img src="/files/U7yBVAuOeO5ZViZZ5fXr" alt=""><figcaption></figcaption></figure>

## Step 3: Embed Subscription URLs into Your Website

Now that you have a specific URL for each plan, you can **embed the appropriate link** in the right call-to-action button **on your website**.  \
\
Once customers sign up for a subscription, they will be directed to a **specific checkout page** where they will enter their payment information. The information collected will be used to **automatically charge customers** based on their specific plan and billing logic.

<figure><img src="/files/VorP1nvpyM8vyHApnDtV" alt=""><figcaption></figcaption></figure>


# Sync & Track Subscriptions

Automatically sync new customers and subscriptions to Received.

## Step 1: Automatically Sync Customers and Subscriptions

Once you have embedded the custom URLs into your website, Received's platform is ready to **automatically 'catch' user information** and create new customers and subscriptions. \
\
Using APIs, we can access the subscription data from your website to create the following:&#x20;

1. **New Customer**\
   \
   Using a specific API, a new customer is automatically created in **Customers > Subscriptions**.\
   Our API looks like this:&#x20;

```
// POST/api/customers
```

#### **Request body**

Example Value &#x20;

```json
{
  "name": "Received",
  "legal_name": "Received ltd.",
  "email": "admin1@company.com, admin2@company.com",
  "ein": "12-3456789",
  "phone": {
    "countryCode": "1",
    "phone": "2121234567"
  },
  "country": "United States",
  "city": "New York",
  "zip_code": "string",
  "billing_address": "643 Mundy St, Watertown, New York(NY), 13601",
  "shipping_address": "643 Mundy St, Watertown, New York(NY), 13601",
  "country_state": "NY",
  "currency": "USD",
  "tax": 17,
  "entity_ref": "693122c3-54e0-4acd-aeb8-7de4686cea3e",
  "entity_name": "Acme Inc",
  "net_terms": 30,
  "settings": {
    "attach_usage_logs_csv": false,
    "attach_usage_logs_pdf": true
  },
  "icon_data": "string"
}
```

#### Responses

Example Value

```
{
  "customer_ref": "dcaff9c0-4a9c-4d01-b2dc-0da7efcc616c"
}
```

2. **New Subscription** \
   \
   Using a specific API, a new subscription is automatically created in **Contracts > Subscriptions**.\
   Our API looks like this:&#x20;

```
// POST/api/contracts/subscriptions
```

#### **Request body**

Example Value

```json
{
  "customer_ref": "19ed1ce4-082b-4cea-8dfb-c7e673f88224",
  "entity_ref": "cec40f99-a2e1-4bd7-805d-9c1a3c2e69a1",
  "po_number": "string",
  "billing_start_date": "2024-02-01T12:05:23.613Z",
  "billing_end_date": "2024-02-01T12:05:23.613Z",
  "issue_day": "2023-07-13",
  "payment_time": "AFTER_USE",
  "tax": 17,
  "discount": 0,
  "net_terms": "DUE_UPON_RECEIPT",
  "note": "string",
  "billing_online_payment_details": {
    "auto_charge": true,
    "payment_gateway_id": "string",
    "payment_gateway_card_id": "string"
  },
  "products": [
    {
      "product_pricing_ref": "string",
      "line_items": [
        {
          "line_item_id": "string"
        }
      ]
    }
  ]
}
```

#### Responses

Example Value

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

## Step 2: Track Subscriptions Data&#x20;

Navigate to **Customers>Subscribers** to see all subscriptions data.\
On this screen you can view the number of subscribers, subscriptions ARR and MRR, payment status, churn rate and more.\
\
Received offers an error handling mechanism, which quickly identifies failed payments and automatically sends a new payment link to the customer.

<figure><img src="/files/9npVx7bPPDqVv5j4T3R0" alt=""><figcaption></figcaption></figure>


# Auto-Charge Payments

Automatically track usage, charge subscription fees, reconcile payments and recognize revenue.

## Step 1: Track Usage (for usage-based products)

In the event that a subscription plan includes a **usage-based product**, Received's **usage API** automatically **tracks and calculates usage rates** for each subscriber per billing cycle.

This API is provided by Received, and **embedded into your software**, enabling automatic usage tracking.\
\
Our embeddable API looks like this:

<pre><code><strong>usage_event = {
</strong>  "timestamp": "2024-02-05T08:55:32.160Z",
  "customer_ref": "4096966d-5c1c-4e18-8b47-6a365e3c16ea",
  "customer_name": "ACME",
  "usage_product_ref": "bb50da07-c686-4688-8550-66305e17aab0",
  "usage_product_name": "Units",
  "quantity": 10,
  "additional_report_data": {
    "note": "User-specific note"
  },
  "validations": {
    "currency": "USD",
    "entity_ref": "55899733-32a0-4912-9d2e-a5b0f04dcdb6"
  }
}

event_report_resp = requests.post('https://api.received.ai/api/usage/event', headers=headers, data=json.dumps(usage_event))
</code></pre>

Once this API is embedded, usage is tracked and collected by Received. When it's time to charge customers, Received's **internal API collects the relevant data** and calculates the total due for each specific subscription.

Our API looks like this:

```
// POST/api/usage/event
```

#### Request Body

Example Value

```
{
  "timestamp": "2024-02-05T09:02:27.279Z",
  "customer_ref": "b4fe1e43-321f-479c-aee7-c11d73616ff2",
  "customer_name": "ACME",
  "usage_product_ref": "9db3fbc3-5e77-43c8-828f-bc2b69cbc9f3",
  "usage_product_name": "Units",
  "quantity": 10,
  "additional_report_data": {
    "note": "User-specific note"
  },
  "validations": {
    "currency": "USD",
    "entity_ref": "d78bf43b-e76a-4a70-8f56-d3dfcea0dffe"
  }
}
```

#### Responses

Example Value

```
{
  "event_ref": "d1d3416c-0b33-479e-a42f-dbb74effd290",
  "related_document_ref": "fffb529d-e5ad-4d87-b1e5-fa5085a675b5",
  "related_document_numbers": "US-INV-1234",
  "related_parent_document_ref": "cb88774f-fbdd-42ef-b9eb-822e6c581ee1",
  "related_parent_document_numbers": "US-INV-12345"
}
```

## Step 2: Auto-Charge Customers&#x20;

Received **automatically charges active subscription customers** according to their selected plan and usage rates (where applicable), and sends **payment confirmations.**\
\
Upon payment, Received's system automatically matches auto-charged payments with outstanding balances for **seamless reconciliation** and automatically **recognizes revenue** according to **ASC-606 and IFRS-15** compliance.

<figure><img src="/files/S6XiKD5UYmnXPLhnPij9" alt=""><figcaption></figcaption></figure>


# Overview

Manage Partner Contracts and Automate Partner Billing with Received.

<figure><img src="/files/wQp7cEEkVrf0wivdef4x" alt=""><figcaption></figcaption></figure>

### Use Received to manage Referral and Reseller partner contracts and automate billing and partner fees:

1. Create a Partner: Referral or Reseller.
2. Create and customize partner contracts.
3. Define partner fees (when applicable).
4. Track usage for usage-based products.
5. Automatically send invoices.
6. Collect payments.
7. Automatically reconcile payments.
8. Automatically recognize revenue.

## Reseller

![](/files/O4s1litMlp4MNdAf3XsT)

## Referral

<figure><img src="/files/BdCUHyJYvy4JVJiluXSf" alt=""><figcaption></figcaption></figure>


# Key Features

Manage referral and reseller billing, automate partner fees and sales commissions, and monitor partner activity.

### Manage Referral Partners

Manage referral partners and automate referral fees for a seamless end-to-end referral program.

* **Manage Referral Contracts** - automate Referral Partner contracts of any complexity, and link referral partners to their referred customers and contracts.
* **Automate Referral Fees** - define custom Referral partner fee types and rates, and automate those at scale.
* **Automatic Reconciliation** - automate fee reconciliation for any type, including Usage and non-linear fees.

<figure><img src="/files/9aa3vBdpR64YWRmIsJZN" alt=""><figcaption></figcaption></figure>

### Manage Reseller Partners

Manage reseller partners and automate reseller fees to streamline reseller partnerships and foster revenue growth.

* **Manage Reseller Contract** - automate Reseller Partner contracts of any complexity, and link reseller partners to their customers and contracts.
* **Automate Reseller Fees**- define multiple billing hierarchies, for different types of reseller billing, including optionality of ‘pass-through’ billing, and automate those at scale.
* **Automatic Reconciliation** - automate fee reconciliation for any type, including Usage and non-linear fees.

<figure><img src="/files/wRXAAPOJXX12j2Y2C55Q" alt=""><figcaption></figcaption></figure>

### Track Partner Analytics

Track and analyze all partnership data in one place to optimize partnerships and accelerate growth.

* **Partner Analytics** - monitor your partner analytics to identify your top performing partners, including bookings, customers, partner fees, gross income, active contracts, and churn rates.
* **Partner Fees** - monitor partner fees and commissions to see paid and unpaid fees, and analyze partner success.
* **Products Breakdown** - track your products’ Cash Inflow to identify your highest performing products and pricing models.

<figure><img src="/files/ccppEuZyZXsPJfdz7he6" alt=""><figcaption></figcaption></figure>


# The Referral Billing Process

Follow our step-by-step guide to see how to set up referral billing automation.

<figure><img src="/files/m2TwBJtwj1uHH7H1Gn7E" alt=""><figcaption></figcaption></figure>

<table data-view="cards" data-full-width="true"><thead><tr><th data-card-target data-type="content-ref"></th><th data-hidden></th><th data-hidden></th><th data-hidden></th></tr></thead><tbody><tr><td><a href="/pages/PIFIDgBkw0Qs9Gs6ykyp">/pages/PIFIDgBkw0Qs9Gs6ykyp</a></td><td></td><td></td><td></td></tr><tr><td><a href="/pages/15VcrPJIdIAvvkkvfPfU">/pages/15VcrPJIdIAvvkkvfPfU</a></td><td></td><td></td><td></td></tr></tbody></table>


# Set Up Referrals

## Step 1: Create a Partner&#x20;

Navigate to the **'Customers Tab'** and click on **'New Customer'**. Fill in the partner information and turn on the **'Partner'** toggle to mark it as a partner.&#x20;

<figure><img src="/files/0rqNChYID2sJX9wjmODA" alt="" width="375"><figcaption></figcaption></figure>

## Step 2: Create a Customer Contract, Attach Partner, and Define Referral Fees&#x20;

Navigate to the **'Customers Tab'** and click on **'Create a Contract'.** Click on **'Search'** to add the relevant customer to the contract. Continue to add products and customize the contract (see the full contract creation process [here](/enterprise-contract-billing/the-enterprise-contract-billing-process/set-up-enterprise-contracts)). \
\
Once the customer contract is complete, **attach the relevant referral partner**.&#x20;

<figure><img src="/files/CshIrMUDTPNnFnAxBsEs" alt=""><figcaption></figcaption></figure>

Once you attach a partner, a new tab will appear - **'Partners'.**  Use the partners tab to define your partner fees. You can define one fee **for the whole contract**, or define separate fees for **each product** in the contract.&#x20;

<figure><img src="/files/S1ZxrKDm01lRPXfn83om" alt=""><figcaption></figcaption></figure>

##


# Automate Invoicing & Fees, and Track Referral Data

## Step 1: Automate Customer Invoicing & Payment Collection

Your referred customers will be automatically invoiced like any Enterprise customer.\
**See the full invoicing process** [**here**](/enterprise-contract-billing/the-enterprise-contract-billing-process/automate-invoicing)**.**&#x20;

<figure><img src="/files/O8Yk6OmtvZZdlbVLyy80" alt=""><figcaption></figcaption></figure>

Customers can pay their invoices by credit card (via Stripe), wire transfer, or crypto wallet.&#x20;

Upon payment, Received's system automatically matches incoming payments with outstanding invoices for **seamless reconciliation** and automatically **recognizes revenue** according to **ASC-606 and IFRS-15** compliance.

<figure><img src="/files/XiIi5apatPfxcdTNRh5a" alt="" width="378"><figcaption></figcaption></figure>

## Step 2: Automate Referral Fee Allocation

Once the referred customer's contract is activated, **referral fees will be calculated automatically** and allocated according to the **terms defined in the contract.** \
\
To see the referral fees for a specific partner, navigate to **Customers>Partners>Referrals** and  click on the referral partner you wish to vie&#x77;**.** Click on the **'Fees Tab'** to view your partner fee allocation and status (paid, unpaid, sent, failed).

<figure><img src="/files/ATdXsFGaQBsQNdGN3gfl" alt=""><figcaption></figcaption></figure>

## **Step 3: Track Referral Data**

Navigate to **Customers>Partners>Referrals** to get an overview of your referral data. View all **referral partners**, along with the customers they have referred, and a breakdown of **contract value, products, churn rate, referral fees**, and more.

<figure><img src="/files/5aMSVoxweGYmO1IZ4qOD" alt=""><figcaption></figcaption></figure>

Navigate to **Customers>Partners>Referrals** and **click on the referral partner you wish to view.** \
Use the **'Overview Tab'** to view of the partner bookings, referred customers, fees, churn rate, and more.&#x20;

<figure><img src="/files/daiHgvBO1JA5GBbMTWLd" alt=""><figcaption></figcaption></figure>

Click on the **'Contracts Tab'** to view all contracts with customers referred by this referral partner. See the total contract value and partner fees per customer, product breakdowns, and more.

<figure><img src="/files/iOtjpyJsPdu7dtf1QmLM" alt=""><figcaption></figcaption></figure>


# The Reseller Billing Process

Follow our step-by-step guide to see how to set up reseller billing automation.

<figure><img src="/files/K8irA1WPqQxMoBIqn5bu" alt=""><figcaption></figcaption></figure>

<table data-view="cards" data-full-width="true"><thead><tr><th data-card-target data-type="content-ref"></th><th data-hidden></th><th data-hidden></th><th data-hidden></th></tr></thead><tbody><tr><td><a href="/pages/96ztie0ymRYCFu4fSuyz">/pages/96ztie0ymRYCFu4fSuyz</a></td><td></td><td></td><td></td></tr><tr><td><a href="/pages/DJGMXd9QOsy01EZUvPTf">/pages/DJGMXd9QOsy01EZUvPTf</a></td><td></td><td></td><td></td></tr></tbody></table>


# Set Up Resellers

## Step 1: Create a Partner&#x20;

Navigate to the **'Customers Tab'** and click on **'New Customer'**. Fill in the partner information and turn on the **'Partner'** toggle to mark it as a partner.&#x20;

<figure><img src="/files/NIUfFnmETTqHwgDgvH9l" alt="" width="375"><figcaption></figcaption></figure>

## Step 2: Create a Bespoke Reseller Price&#x20;

Navigate to the **'Pricing Tab'** to create bespoke pricing for your resellers. You can **duplicate existing products** and change pricing, or **create new products** from scratch.\
\
**See the full product and pricing creation process** [**here**](/enterprise-contract-billing/the-enterprise-contract-billing-process/set-up-enterprise-contracts)**.**

<figure><img src="/files/n63DIlgt0aplKMkIvNU4" alt=""><figcaption></figcaption></figure>

## Step 3: Create a Reseller Contract

Once the reseller has made a sale, a reseller contract needs to be created. Navigate to the **'Customers Tab'** and click on **'Create a Contract'**. Click on **'Search'** to add the relevant reseller to the contract. Continue to add the relevant products with the **reseller price** and customize the contract **(see the full contract creation process** [**here**](/enterprise-contract-billing/the-enterprise-contract-billing-process/set-up-enterprise-contracts)**).**\
\
\*Note that in a reseller contract, **the customer is the partner,** not the end user.

<figure><img src="/files/0lmkMHOX1krB3QwB0zPo" alt=""><figcaption></figcaption></figure>


# Automate Invoicing & Track Reseller Dats

## Step 1: Automate Invoicing & Payment Collection

Your resellers will be automatically invoiced like any Enterprise customer.\
**See the full invoicing process** [**here**](/enterprise-contract-billing/the-enterprise-contract-billing-process/automate-invoicing)**.**&#x20;

<figure><img src="/files/O8Yk6OmtvZZdlbVLyy80" alt=""><figcaption></figcaption></figure>

Resellers can pay their invoices by credit card (via Stripe), wire transfer, or crypto wallet.&#x20;

Upon payment, Received's system automatically matches incoming payments with outstanding invoices for **seamless reconciliation** and automatically **recognizes revenue** according to **ASC-606 and IFRS-15** compliance.

<figure><img src="/files/XiIi5apatPfxcdTNRh5a" alt="" width="378"><figcaption></figcaption></figure>

## Step 2: Track Reseller Data

Navigate to **Customers>Partners>Resellers** to view your **reseller data**. In this tab, you will find all reseller partners, contracts status and value, invoicing status, payment collection status, and more.

<figure><img src="/files/IFtu50EPs2JEjqcZ3uZf" alt=""><figcaption></figcaption></figure>


# Received APIs Intro

Received's API operates on a REST architecture, featuring resource-oriented URLs for easy navigation. It accepts form-encoded request bodies and delivers JSON-encoded responses. Standard HTTP response codes, authentication methods, and verbs are utilized throughout.

#### API Headers

{% hint style="info" %}
API calls, except for Authentications, must include the next headers

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

#### Current version

{% code lineNumbers="true" %}

```javascript
{"Version": "V0"}
```

{% endcode %}

#### **Start using with Swagger UI:**

{% hint style="info" %}
<https://api.received.ai/swagger/>
{% endhint %}


# Authentication

Automatically authenticate user information.

Received's APIs use a **Bearer token** in the Authorization header for each request. This token is obtained after a successful login or registration process and must be securely stored by the client. Ensure the header format is "Authorization: Bearer \<your\_token\_here>", where "\<your\_token\_here>" is replaced with your actual token.

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

```javascript
POST https://api.received.ai/auth/login
POST https://api.received.ai/auth/logout
POST https://api.received.ai/auth/keys/generate
GET https://api.received.ai/auth/keys/list
DELETE https://api.received.ai/auth/user/<api_key
```

{% endcode %}

## Authenticate API user

Authenticate user and return JWT token for future requests. The JWT token is used to authenticate the user in the API Gateway.

### API Login

{% code lineNumbers="true" %}

```javascript
POST https://api.received.ai/auth/login
```

{% endcode %}

{% code lineNumbers="true" %}

```javascript
{
  "api_key": "{{api_key}}",
  "password": "{{api_password}}"
}
```

{% endcode %}

#### Responses

JWT token for future requests.

{% code title="Example:" overflow="wrap" lineNumbers="true" %}

```javascript
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZIjoiSm9obiBEb2UiLCJpYXQiOjE1MTYyMzkwMjJ9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
```

{% endcode %}

#### Schema

<table><thead><tr><th width="172">Term</th><th width="127">Type</th><th width="204">Description</th><th>Example</th></tr></thead><tbody><tr><td><code>username</code><mark style="color:red;">*</mark></td><td><mark style="color:purple;">String</mark></td><td>API Key</td><td><pre class="language-json"><code class="lang-json">46SQZ49LT100U2QWQ3SI
</code></pre></td></tr><tr><td><code>password</code><mark style="color:red;">*</mark></td><td><mark style="color:purple;">String</mark></td><td>API Password</td><td>************</td></tr></tbody></table>

## API Key Generation

API keys serve as unique identifiers to authenticate API clients, ensuring that the client is authorized to access the requested resources. Upon successful login, the API issues a JWT (JSON Web Token) to the client, which encapsulates the user's identity and permissions in a secure format. This JWT can then be used for subsequent API calls, streamlining the authentication process and enhancing security by limiting exposure of sensitive credentials.

### Admin Login

{% code lineNumbers="true" %}

```javascript
POST https://api.received.ai/auth/login
```

{% endcode %}

{% code lineNumbers="true" %}

```javascript
{
  "email": "{{admin_email}}",
  "password": "{{admin_password}}"
}
```

{% endcode %}

#### Response

Cookie session for further requests with Admin permissions&#x20;

### Generating API key

{% code lineNumbers="true" %}

```javascript
POST https://api.received.ai/auth/keys/generate
```

{% endcode %}

#### Response

API keys are critical for securing access to web services, acting as unique identifiers for each user or application. To keep them safe, it's essential to store them securely, avoid sharing them publicly, and use environment variables or encrypted secrets management services to manage them in applications.

{% code lineNumbers="true" %}

```javascript
{
  "api_key": "{{api_key}}",
  "password": "{{api_password}}"
}
```

{% endcode %}

## Explore More APIs

Delves into additional authentication methods and initial setup instructions, broadening your integration capabilities and enhancing secure access

### Admin Logout

{% code lineNumbers="true" %}

```javascript
POST https://api.received.ai/auth/logout
```

{% endcode %}

### List API Keys

{% code lineNumbers="true" %}

```javascript
GET https://api.received.ai/auth/keys/list
```

{% endcode %}

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

```javascript
[
    {
        "api_key_ref": "{{api_key_ref}}",
        "api_key": "{{api_key}}"
    }
]
```

{% endcode %}

### Delete API key

{% code lineNumbers="true" %}

```javascript
DELETE https://api.received.ai/auth/user/<api_key_ref>
```

{% endcode %}


# Products

Fetch product and their pricing

Received Products' APIs allow our users to manage their products and pricing models. The APIs support operations such as creating new products and pricing models, updating existing products, and fetching products to use in customer contracts and subscriptions.

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

```javascript
GET https://api.received.ai/api/products
```

{% endcode %}

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

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

## Getting Products and Pricing

Fetching products and pricing provides detailed listings of available offerings and their associated costs. This information is crucial to build a contract, tailor their purchase orders, and negotiate contracts effectively.

### Get Products

{% code lineNumbers="true" %}

```javascript
GET https://api.received.ai/api/products
```

{% endcode %}

#### Response

{% code lineNumbers="true" %}

```javascript
[
    {
      "pricing_ref": "35bfdd59-6462-4ec6-bd7b-b3e654d85774",
      "product_name": "Subscriptions",
      "pricing_name": "Plans",
      "line_items": [
        {
          "line_item_ref": "e72dd70c-cc65-4804-af2f-2fe6dab5f689"
          "item": "Starter",
          "price": 3000,
          "quantity": 1,
          "amount": 3000
        },
        {
          "line_item_ref": "e72dd70c-cc65-4804-af2f-2fe6dab5f680"
          "item": "Professional",
          "price": 6000,
          "quantity": 1,
          "amount": 6000
        },
        {
          "line_item_ref": "e72dd70c-cc65-4804-af2f-2fe6dab5f681"
          "item": "Organization",
          "price": 9000,
          "quantity": 1,
          "amount": 9000
        }
      ]
    },
    {
      "pricing_ref": "946ba17b-6f16-491e-bfa3-d189e827a9a3",
      "product_name": "Pay-as-you-go",
      "pricing_name": "Tiered",
      "line_items": [
        {
          "line_item_ref": "e72dd70c-cc65-4804-af2f-2fe6dab5f682"
          "item": "Starter",
          "price": 10,
          "quantity": 0,
          "amount": 0
        },
        {
          "line_item_ref": "e72dd70c-cc65-4804-af2f-2fe6dab5f683"
          "item": "Professional",
          "price": 9,
          "quantity": 0,
          "amount": 0
        },
        {
          "line_item_ref": "e72dd70c-cc65-4804-af2f-2fe6dab5f684"
          "item": "Organization",
          "price": 8,
          "quantity": 0,
          "amount": 0
        }
      ]
    }
]
```

{% endcode %}

#### Response Schema

Return list of pricing model with a product as a property. Those pricing and their lineitems can be used to build a contract (see [Contract page](/api-docs/contracts))

**Pricing Schema**

<table><thead><tr><th width="201">Term</th><th width="99">Type</th><th width="330">Description </th><th width="378">Example</th></tr></thead><tbody><tr><td><code>pricing_ref</code></td><td><mark style="color:purple;">String</mark></td><td>The ID of the related product pricing</td><td>35bfdd59-6462-4ec6-bd7b-b3e654d85774</td></tr><tr><td><code>product_name</code></td><td><mark style="color:purple;">String</mark></td><td>The pricing's related product</td><td>Subscription</td></tr><tr><td><code>pricing_name</code></td><td><mark style="color:purple;">String</mark></td><td>Name of the pricing</td><td>Plans</td></tr><tr><td><code>line_items</code></td><td><mark style="color:purple;">Array</mark></td><td>List of pricing related lineitems</td><td></td></tr></tbody></table>

**Lineitem Schema**

<table><thead><tr><th width="350">Term</th><th width="99">Type</th><th width="330">Description </th><th width="378">Example</th></tr></thead><tbody><tr><td><code>line_item_ref</code></td><td><mark style="color:purple;">String</mark></td><td>The ID of the related lineitem</td><td>e72dd70c-cc65-4804-af2f-2fe6dab5f689</td></tr><tr><td><code>item</code></td><td><mark style="color:purple;">String</mark></td><td>Item name</td><td>Starter</td></tr><tr><td><code>price</code></td><td><mark style="color:purple;">String</mark></td><td>Item price</td><td>30000</td></tr><tr><td><code>quantity</code></td><td><mark style="color:purple;">String</mark></td><td>Item quantity</td><td>1</td></tr><tr><td><code>amount</code></td><td><mark style="color:purple;">Array</mark></td><td>Total amount of the item</td><td>3000</td></tr></tbody></table>


# Customers

Create, update and fetch contracts information.

Received's Customers' APIs allow our users to manage their customers and subscribers. The APIs support operations such as creating a new customer, updating existing customers and fetching customers' related data. &#x20;

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

```javascript
POST https://api.received.ai/api/customers
GET https://api.received.ai/api/entities/<entity_ref>
GET https://api.received.ai/api/customers/names
GET https://api.received.ai/api/entities/names
```

{% endcode %}

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

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

## Adding Customer For Debit Entity

Adding a new customer for the receiving entity involves registering their details and payment information, enhancing the entity's client base and opening avenues for increased revenue streams.

### Add Customer

{% code lineNumbers="true" %}

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

{% endcode %}

{% code title="Mandatory request " lineNumbers="true" %}

```javascript
{
  "name": "Acme",
  "email": "admin1@acme.com, admin2@acme.com",
}
```

{% endcode %}

<pre class="language-javascript" data-title="Extensive request" data-line-numbers><code class="lang-javascript"><strong>{
</strong>  "name": "Acme",
  "legal_name": "Acme Inc.",
  "email": "admin1@acme.com, admin2@acme.com",
  "ein": "12-3456789",
  "phone": {
    "countryCode": "1",
    "phone": "2121234567"
  },
  "country": "United States",
  "country_state": "NY",
  "city": "New York",
  "zip_code": "13601",
  "billing_address": "643 Mundy St, Watertown",
  "shipping_address": "643 Mundy St, Watertown",
  "currency": "USD",
  "tax": 17,
  "entity_ref": "9f9f6a42-fba0-4fb5-ac7a-e83ac2c045a9",
  "net_terms": 30,
  "billing_bank_transfer_details": {
    "billing_account_id": "12345678-1234-1234-1234-1234567890ab"
  },
  "billing_online_payment_details": {
    "auto_charge": true,
    "payment_gateway_id": "87654321-4321-4321-4321-0987654321ba",
    "payment_gateway_card_id": "card_abcdef1234567890"
  },
  "billing_crypto_details": {
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "tokens": ["BTC", "ETH"]
  },
  "settings": {
    "attach_usage_logs_csv": false,
    "attach_usage_logs_pdf": true
  }
}
</code></pre>

#### Responses

{% code lineNumbers="true" %}

```javascript
{
  "customer_ref": {{customer_ref}}
}
```

{% endcode %}

#### Request Schema

<table><thead><tr><th width="350">Term</th><th width="99">Type</th><th width="330">Description </th><th width="378">Example</th></tr></thead><tbody><tr><td><code>name</code><mark style="color:red;">*</mark></td><td><mark style="color:purple;">String</mark></td><td>Company name</td><td>Acme</td></tr><tr><td><code>email</code><mark style="color:red;">*</mark></td><td><mark style="color:purple;">String</mark></td><td>Company's email addresses comma separated</td><td>admin1@acme.com, admin2@acme.com</td></tr><tr><td><code>legal_name</code></td><td><mark style="color:purple;">String</mark></td><td>Company's legal name - documents use</td><td>Acme Inc.</td></tr><tr><td><code>ein</code></td><td><mark style="color:purple;">Number</mark></td><td>Employer identification number</td><td>12-3456789</td></tr><tr><td><code>phone</code></td><td><mark style="color:purple;">Number</mark></td><td>Company's phone number in international format (7-20 digits)</td><td>2121234567</td></tr><tr><td><code>country_code</code></td><td><mark style="color:purple;">Number</mark></td><td>Country code (1-4 digits)</td><td>123</td></tr><tr><td><code>country</code>*</td><td><mark style="color:purple;">String</mark></td><td>Company's country of operation</td><td>United States</td></tr><tr><td><code>country_state</code></td><td><mark style="color:purple;">String</mark></td><td>Company's state of operation</td><td>NY</td></tr><tr><td><code>city</code></td><td><mark style="color:purple;">String</mark></td><td>Company's city of operation</td><td>New York</td></tr><tr><td><code>zip-code</code></td><td><mark style="color:purple;">Number</mark></td><td>Company's zip code</td><td>10001</td></tr><tr><td><code>billing_address</code></td><td><mark style="color:purple;">String</mark></td><td>Company's billing address</td><td>643 Mundy St, Watertown, New York(NY), 13601</td></tr><tr><td><code>shipping_address</code></td><td><mark style="color:purple;">String</mark></td><td>Company's shipping address</td><td>643 Mundy St, Watertown, New York(NY), 13601</td></tr><tr><td><code>currency</code></td><td><mark style="color:purple;">String</mark></td><td>The default currency that is used for this company</td><td>USD</td></tr><tr><td><code>tax</code></td><td><mark style="color:purple;">Number</mark></td><td>Value Added Tax - in percentage</td><td>17</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>fae8fc36-d321-473f-9890-a9cb16deb4dd</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>30</td></tr><tr><td><code>billing_bank_transfer_details</code><br><br>  <code>billing_account_id</code></td><td><mark style="color:purple;">Object</mark><br><br><mark style="color:purple;">String</mark></td><td>Bank account details<br><br>The ID of the bank account</td><td><pre class="language-javascript"><code class="lang-javascript"><strong>{
</strong>  "billing_account_id": "3a7b0f7d-fdf6-4f54-90f4-2307b73ae85f"
}
</code></pre></td></tr><tr><td><code>billing_online_payment_details</code><br><br>  <code>auto_charge</code><br><br>  <code>payment_gateway_id</code><br>  <code>payment_gateway_card_id</code><br><br></td><td><mark style="color:purple;">Object</mark><br><br><mark style="color:purple;">Boolean</mark><br><br><mark style="color:purple;">String</mark><br><mark style="color:purple;">String</mark><br><br></td><td>Online payment details<br><br>Indicates whether the charging should be automatic or not<br>The ID of the payment gateway<br>The ID of a specific card defined in the payment gateway account, such as Stripe card id</td><td><pre class="language-javascript"><code class="lang-javascript"><strong>{
</strong>  "auto_charge": true,
  "payment_gateway_id": "3a7b0f7d-fdf6-4f54-90f4-2307b73ae85f",
  "payment_gateway_card_id": "card_abcdef1234567890"
}
</code></pre></td></tr><tr><td><p><code>billing_crypto_details</code><br>  <code>address</code><br>  <code>tokens</code></p><p></p></td><td><mark style="color:purple;">Object</mark><br><mark style="color:purple;">String</mark><br><mark style="color:purple;">Array</mark><br></td><td>The details of the crypto wallet<br>The address of the crypto wallet<br>The crypto tokens that supported by the wallet </td><td><pre class="language-javascript"><code class="lang-javascript"><strong>{
</strong>  "address": "1Lbcfr7sAHTD9CgdQo3HTMTkV8LK4ZnX71",
  "tokens": ["BTC", "ETH"]
}
</code></pre></td></tr><tr><td><code>settings</code><br>  <code>attach_useage_logs_csv</code><br>  <code>attach_useage_logs_pdf</code></td><td><mark style="color:purple;">String</mark><br><mark style="color:purple;">Boolean</mark><br><mark style="color:purple;">Boolean</mark></td><td><p>Set usage reports for Invoice email: </p><p>Attach logs csv to invoice email<br>Attach logs appendix to invoice PDF</p></td><td><pre class="language-javascript"><code class="lang-javascript">{
  "attach_usage_logs_csv": false,
  "attach_usage_logs_pdf": true
}
</code></pre></td></tr></tbody></table>

#### Response Schema

<table><thead><tr><th width="187">Term</th><th width="88">Type</th><th>Description</th><th>Exmaple</th></tr></thead><tbody><tr><td><code>customer_ref</code></td><td><mark style="color:purple;">String</mark></td><td>Customer reference</td><td>dcaff9c0-4a9c-4d01-b2dc-0da7efcc616c </td></tr></tbody></table>

### Get Debit Entity

{% code lineNumbers="true" %}

```javascript
GET https://api.received.ai/api/entities/<entity_ref>
```

{% endcode %}

#### Responses

{% code lineNumbers="true" %}

```javascript
{
  "entity_ref": "db93868d-01f6-40dc-8609-0a314969d03b",
  "name": "ACME",
  "legal_name": "ACME Ltd.",
  "email": "admin1@acme.com, admin2@acme.com",
  "registration_number": "12-3456789",

  "billing_details": {
    "billing_accounts": [
      {
        "billing_account_id": "0c013466-84f4-48a4-a91b-5cc9808fc3f5",
        "bank_name": "Bank Of America",
        "bank_code": "123",
        "branch": "123",
        "account": "123123",
        "account_name": "US BOA Account",
        "iban": "IL62 0108 0000 0009 9999 999",
        "swift": "BOFAUS3N",
        "routing": "071904779",
        "address": "643 Mundy St, Watertown, New York(NY), 13601",
      }
    ],
    "payment_gateways": [
      {
        "payment_gateway_id": "b59ec2d9-379a-46cf-b69c-fdb5fa47787d",
        "provider": "STRIPE",
        "payment_gateway_card_id": "acct_1OPTJWKoIU7lFy9r",
        "account_name": "US Account"
      }
    ]
  },
  
  "country": "United States",  
  "country_state": "NY",
  "city": "New York",
  "address": "643 Mundy St, Watertown",
  "phone": {
    "countryCode": "1",
    "phone": "2121234567"
  },
  "zip_code": "13601",
}
```

{% endcode %}

## Explore More APIs

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

### List All Customers

{% code title="All Customers" lineNumbers="true" %}

```javascript
GET https://api.received.ai/api/customers/names
```

{% endcode %}

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

```javascript
{
    "customers": [
        {
            "customer_ref": {{customer_ref}},
            "customer_name": {{customer_name}},
            "customer_legal_name": {{customer_legal_name}}
        }
    ]
}
```

{% endcode %}

### Filter List Of Customers

{% code title="Filter list of customers" overflow="wrap" lineNumbers="true" %}

```javascript
GET https://api.received.ai/api/customers/names/filter?customer_name={{customer_name}}&orderBy=name&order=ASC
```

{% endcode %}

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

```javascript
{
    "customers": [
        {
            "customer_ref": {{customer_ref}},
            "customer_name": {{customer_name}},
            "customer_legal_name": {{customer_legal_name}}
        }
    ],
    "count": 1,
    "total": 1
}
```

{% endcode %}

### Customer Invoices

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

### List All Debit Entities

{% code lineNumbers="true" %}

```javascript
GET https://api.received.ai/api/entities/names
```

{% endcode %}

#### Response

<pre class="language-javascript" data-line-numbers><code class="lang-javascript">{
    "entities": [
        {
            "entity_ref": {{entity_ref}},
            "entity_name": {{entity_name}},
            "entity_legal_name": {{entity_legal_name}}
        }
    ]
<strong>}
</strong></code></pre>

#### Response Schema

<table><thead><tr><th width="187">Term</th><th width="88">Type</th><th width="297">Description</th><th width="359">Exmaple</th></tr></thead><tbody><tr><td>entity_ref</td><td><mark style="color:purple;">String</mark></td><td>The ID of the supplier entity</td><td>dcaff9c0-4a9c-4d01-b2dc-0da7efcc616c </td></tr><tr><td>entity_name</td><td><mark style="color:purple;">String</mark></td><td>The name of the supplier entity</td><td>Acme</td></tr><tr><td>entity_legal_name</td><td><mark style="color:purple;">String</mark></td><td>The legal name of the supplier entity - used of documents</td><td>Acme Ltd.</td></tr></tbody></table>


# 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.  &#x20;

{% 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) and [Product](/api-docs/products) 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)


# Invoices

Fetch and update invoices information.

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. &#x20;

{% 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


# Usage Reports

Automatically collect usage information.

Received's usage API collects **usage data** from customer software.&#x20;

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

```javascript
POST https://api.received.ai/api/usage/event
POST https://api.received.ai/api/usage/event/formatted
POST https://api.received.ai/api/usage/event/update
POST https://api.received.ai/api/usage/event/formatted/update
DELETE https://api.received.ai/api/usage/event/<event_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 %}

## Reporting Customer Usage

The usage API is built out of a **main API** (Default) and an **API add-on** (Formatted):

1. **Default Usage API -** This is the main API used to collect usage data. When a user **does not have** a customized usage format, this API will be used with no add-ons. In this scenario, the usage data will be formatted according to Received's default format.
2. **Formatted Usage API -** This API is used as an add-on when the user has created a customized usage format in the system. In this scenario, the data will be formatted according to the user's bespoke format.

### Report Default Usage

{% code lineNumbers="true" %}

```javascript
POST https://api.received.ai/api/usage/event
```

{% endcode %}

{% code lineNumbers="true" %}

```javascript
{
  "timestamp": "2024-02-06T11:37:38.872Z",
  "customer_ref": "eaa65954-9eb7-4246-a96c-7f6bc3aac42f",
  "usage_product_ref": "94434ff8-8537-4f72-a5df-a45cca271544",
  "quantity": 10,
  "additional_report_data": {
    "note": "User-specific note"
  },
  "validations": {
    "currency": "USD",
    "entity_ref": "27db2a0c-a11f-4b2e-bfab-8032d0a5a7a1"
  }
}
```

{% endcode %}

#### Response

{% code lineNumbers="true" %}

```javascript
{
  "event_ref": "d1d3416c-0b33-479e-a42f-dbb74effd290",
  "related_document_ref": "fffb529d-e5ad-4d87-b1e5-fa5085a675b5",
  "related_document_numbers": "US-INV-1234"
}
```

{% endcode %}

#### Schema

<table><thead><tr><th width="278">Term</th><th width="108">Type </th><th width="344">Description</th><th width="380">Example</th></tr></thead><tbody><tr><td><code>timestamp</code><mark style="color:red;">*</mark></td><td><mark style="color:purple;">String</mark></td><td>Date and time.<br>Standard time format "ISO 8601"</td><td>2024-02-05T19:03:39.784Z</td></tr><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>eaa65954-9eb7-4246-a96c-7f6bc3aac42f</td></tr><tr><td><code>usage_product_ref</code><mark style="color:red;">*</mark></td><td><mark style="color:purple;">String</mark></td><td>The ID of the related usage product </td><td>94434ff8-8537-4f72-a5df-a45cca271544</td></tr><tr><td><code>quantity</code><mark style="color:red;">*</mark></td><td><mark style="color:purple;">String</mark></td><td>Usage quantity</td><td>10</td></tr><tr><td><code>additional_report_data</code></td><td><mark style="color:purple;">String</mark></td><td>Key-value set for the usage report use. <br>Will added as a new column in the report.</td><td><pre><code>{
    "note": "User-specific note"
}
</code></pre></td></tr><tr><td><code>validations</code></td><td><mark style="color:purple;">String</mark></td><td>Validate the usage event match the related document properties: Currency, <br> Entity reference</td><td>USD <br><br>27db2a0c-a11f-4b2e-bfab-8032d0a5a7a1 </td></tr></tbody></table>

#### Response Schema

<table><thead><tr><th width="272">Term</th><th width="97">Type</th><th width="273">Description</th><th width="344">Example</th></tr></thead><tbody><tr><td>event_ref</td><td><mark style="color:purple;">String</mark></td><td>Event reference</td><td>d1d3416c-0b33-479e-a42f-dbb74effd290</td></tr><tr><td>related_document_ref</td><td><mark style="color:purple;">String</mark></td><td>The ID of the related document (Invoice, Credit, Debit)</td><td>fffb529d-e5ad-4d87-b1e5-fa5085a675b5</td></tr><tr><td>related_document_numbers</td><td><mark style="color:purple;">String</mark></td><td>Related document numbers</td><td>US-INV-1234</td></tr></tbody></table>

### **Report Formatted Usage**

<pre class="language-javascript" data-line-numbers><code class="lang-javascript"><strong>POST https://api.received.ai/api/usage/event/formatted
</strong></code></pre>

{% code lineNumbers="true" %}

```javascript
{
  "format_name": "Default Format",
  "event": {}
}
```

{% endcode %}

#### Response

{% code lineNumbers="true" %}

```javascript
{
  "event_ref": "d1d3416c-0b33-479e-a42f-dbb74effd290",
  "related_document_ref": "fffb529d-e5ad-4d87-b1e5-fa5085a675b5",
  "related_document_numbers": "US-INV-1234",
  "related_parent_document_ref": "cb88774f-fbdd-42ef-b9eb-822e6c581ee1",
  "related_parent_document_numbers": "US-INV-12345",
  "timestamp": "2024-02-06T11:55:00.037Z",
  "customer_ref": "eaa65954-9eb7-4246-a96c-7f6bc3aac42f",
  "customer_name": "ACME",
  "usage_product_ref": "94434ff8-8537-4f72-a5df-a45cca271544",
  "usage_product_name": "Units",
  "quantity": 10,
  "additional_report_data": {
    "note": "User-specific note"
  }
}
```

{% endcode %}

#### Request Schema

| Term                                           | Type                                      | Description                                             | Example        |
| ---------------------------------------------- | ----------------------------------------- | ------------------------------------------------------- | -------------- |
| format\_name<mark style="color:red;">\*</mark> | <mark style="color:purple;">String</mark> | Look for the relevant format if ref is undefined        | Default Format |
| event<mark style="color:red;">\*</mark>        | <mark style="color:purple;">String</mark> | Any key value pair that will be processed by the format |                |

#### Response Schema

<table><thead><tr><th width="357">Term</th><th>Type </th><th width="365">Description</th><th width="363">Example</th></tr></thead><tbody><tr><td><code>event_ref</code></td><td><mark style="color:purple;">String</mark></td><td>Event reference</td><td>d1d3416c-0b33-479e-a42f-dbb74effd290</td></tr><tr><td><code>related_document_ref</code></td><td><mark style="color:purple;">String</mark></td><td>Related document reference </td><td>fffb529d-e5ad-4d87-b1e5-fa5085a675b5</td></tr><tr><td><code>related_document_numbers</code></td><td><mark style="color:purple;">String</mark></td><td>Related document numbers </td><td>US-INV-1234</td></tr><tr><td><code>related_parent_document_ref</code></td><td><mark style="color:purple;">String</mark></td><td>Related parent document reference ( In case of 'Due upon usage' return also the parent invoice)</td><td>cb88774f-fbdd-42ef-b9eb-822e6c581ee1</td></tr><tr><td><code>related_parent_document_numbers</code></td><td><mark style="color:purple;">String</mark></td><td>Related parent document numbers<br>( In case of 'Due upon usage' return also the parent invoice)</td><td>US-INV-12345</td></tr><tr><td><code>timestamp</code></td><td><mark style="color:purple;">String</mark></td><td>Date and time</td><td>($date-time)</td></tr><tr><td><code>customer_ref</code></td><td><mark style="color:purple;">String</mark></td><td>Customer reference</td><td>eaa65954-9eb7-4246-a96c-7f6bc3aac42f</td></tr><tr><td><code>customer_name</code></td><td><mark style="color:purple;">String</mark></td><td>Customer name</td><td>Acme</td></tr><tr><td><code>usage_product_ref</code></td><td><mark style="color:purple;">String</mark></td><td>Usage product reference</td><td>94434ff8-8537-4f72-a5df-a45cca271544</td></tr><tr><td><code>usage_product_name</code></td><td><mark style="color:purple;">String</mark></td><td>Usage product type<br> (Look for the relevant usage product if ref is undefined</td><td>Units</td></tr><tr><td><code>quantity</code></td><td><mark style="color:purple;">Number</mark></td><td>Quantity </td><td>10</td></tr><tr><td><code>additional_report_data</code></td><td><mark style="color:purple;">String</mark></td><td>Additional data<br>(User-specific note)</td><td>OrderedMap</td></tr></tbody></table>

## Explore More APIs

### Edit Usage Event

Updating usage events via API by specifying date, quantity, or additional information allows for real-time adjustments to consumption records, ensuring accurate billing and a transparent overview of service utilization for both providers and clients.

{% code lineNumbers="true" %}

```javascript
POST https://api.received.ai/api/usage/event/update
```

{% endcode %}

{% code lineNumbers="true" %}

```javascript
{
  "event_ref": "ccd65954-0eb7-5246-a96c-7f6kc3atc42g"
  "timestamp": "2024-02-06T11:37:38.872Z",
  "quantity": 10,
  "additional_report_data": {
    "note": "User-specific note"
  }
}
```

{% endcode %}

#### Response

Updated usage event

### Edit Formatted Usage Event

Applying changes to usage events via API according to some format, by adjusting attributes like date, quantity, or ancillary data, enables dynamic updates to loosely defined entities, fostering flexibility in managing and reflecting real-world variations in service or product usage.

{% code lineNumbers="true" %}

```javascript
POST https://api.received.ai/api/usage/event/formatted/update
```

{% endcode %}

{% code lineNumbers="true" %}

```javascript
{
  "event_ref": "ccd65954-0eb7-5246-a96c-7f6kc3atc42g",
  "format_name": "Default Format",
  "event": {}
}
```

{% endcode %}

#### Response

Updated usage event

### Delete Usage Event

```javascript
DELETE https://api.received.ai/api/usage/event/<event_ref>
```


# FAQ

Find answers to the most frequently asked questions.

<details>

<summary><strong>Is Received the right fit for my company?</strong></summary>

Received is the perfect fit for **modern B2B Software companies** managing complex billing processes and looking to **(a)** automate the billing process to reduce time and errors; **(b)** gain scalability and stay agile in the market as they grow and add new pricing models and revenue streams; and **(c)** gain visibility and a single source of truth for financial data.

</details>

<details>

<summary><strong>Can Received support my pricing model?</strong></summary>

Received offers a comprehensive solution that supports **all pricing models**, including **subscriptions**, **usage-based** pricing, and **hybrid** pricing. The platform comes with pre-built templates for the most common pricing models in each pricing category and also offers the option to create custom pricing from scratch. All pricing models can be **fully customized** at any stage and for any purpose.

</details>

<details>

<summary><strong>What revenue streams are supported?</strong></summary>

Received is the only billing platform that **supports all B2B revenue streams**: self-serve subscriptions, sales-led contracts, and referral and reseller partners.

</details>

<details>

<summary><strong>Can Received integrate with existing business software and workflows?</strong></summary>

Received has **built-in integrations** with your **CRM, ERP, Accounting, Payments, and Tax** Compliance software, ensuring that all contract-to-cash data is consolidated into a single source of truth.

</details>

<details>

<summary><strong>Can my usage data be connected to Received?</strong></summary>

Received's usage API enables **full usage tracking automation** with a single line of code.\
In addition, usage can be uploaded manually or in bulk using CSV files of any format.

</details>