Skip to main content
API docs by Redocly

Fincome API (v1)

Download OpenAPI specification:Download

Introduction

Welcome to Fincome's API documentation! This API allows you to import and manage the data of your Fincome account.

Authentication

First, go to your account settings, tab "Developers", and click on "Create a secret key".

Base API URL

The base API URL is https://api2.fincome.co/product.

Customers

Retrieve a customer by id

Use this endpoint to retrieve a customer by providing its id.

Authorizations:
APIKey
path Parameters
id
required
string (Id)

The id of the customer to retrieve

Responses

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "root_parent_id": "string",
  • "name": "string",
  • "email": "string",
  • "country": "string",
  • "zip_code": "string",
  • "custom_properties": { }
}

Update a customer by id

Use this endpoint to update a customer by id. Partial updates are supported: only the fields specified in the request body will be updated. Custom properties are supported and can be set in the custom_properties (dictionary) inside the request body.

Authorizations:
APIKey
path Parameters
id
required
string (Id)

The id of the customer to update

Request Body schema: application/json
required
Id (string) or Id (null) (Id)

Unique identifier for the customer.

Root Parent Id (string) or Root Parent Id (null) (Root Parent Id)

Id of the parent (if any)

Name (string) or Name (null) (Name)

Name of the customer

Email (string) or Email (null) (Email)

Email of the customer

Country (string) or Country (null) (Country)

Country of the customer

Zip Code (string) or Zip Code (null) (Zip Code)

Zip code of the customer

Custom Properties (object) or Custom Properties (null) (Custom Properties)
Default: {}

Custom properties

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "root_parent_id": "string",
  • "name": "string",
  • "email": "string",
  • "country": "string",
  • "zip_code": "string",
  • "custom_properties": { }
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "root_parent_id": "string",
  • "name": "string",
  • "email": "string",
  • "country": "string",
  • "zip_code": "string",
  • "custom_properties": { }
}

Delete a customer by id

Use this endpoint to delete a customer by providing its id.

Authorizations:
APIKey
path Parameters
id
required
string (Id)

The id of the customer to delete

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Create a new customer

Use this endpoint to create a new customer. Custom properties are supported and can be set in the custom_properties (dictionary) inside the request body.

Authorizations:
APIKey
Request Body schema: application/json
required
id
required
string (Id)

Unique identifier for the customer.

Root Parent Id (string) or Root Parent Id (null) (Root Parent Id)

Id of the parent (if any)

Name (string) or Name (null) (Name)

Name of the customer

Email (string) or Email (null) (Email)

Email of the customer

Country (string) or Country (null) (Country)

Country of the customer

Zip Code (string) or Zip Code (null) (Zip Code)

Zip code of the customer

Custom Properties (object) or Custom Properties (null) (Custom Properties)
Default: {}

Custom properties

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "root_parent_id": "string",
  • "name": "string",
  • "email": "string",
  • "country": "string",
  • "zip_code": "string",
  • "custom_properties": { }
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "root_parent_id": "string",
  • "name": "string",
  • "email": "string",
  • "country": "string",
  • "zip_code": "string",
  • "custom_properties": { }
}

Products

Retrieve a product by id

Use this endpoint to retrieve a product by providing its id.

Authorizations:
APIKey
path Parameters
id
required
string (Id)

The id of the product to retrieve

Responses

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "name": "string",
  • "custom_properties": { }
}

Update a product by id

Use this endpoint to update a product by id. Partial updates are supported: only the fields specified in the request body will be updated. Custom properties are supported and can be set in the custom_properties (dictionary) inside the request body.

Authorizations:
APIKey
path Parameters
id
required
string (Id)

The id of the product to update

Request Body schema: application/json
required
Id (string) or Id (null) (Id)

Unique identifier for the product.

Name (string) or Name (null) (Name)

Name of the product

Custom Properties (object) or Custom Properties (null) (Custom Properties)
Default: {}

Custom properties

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "custom_properties": { }
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "name": "string",
  • "custom_properties": { }
}

Delete a product by id

Use this endpoint to delete a product by providing its id.

Authorizations:
APIKey
path Parameters
id
required
string (Id)

The id of the product to delete

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Create a new product

Use this endpoint to create a new product. Custom properties are supported and can be set in the custom_properties (dictionary) inside the request body.

Authorizations:
APIKey
Request Body schema: application/json
required
id
required
string (Id)

Unique identifier for the product.

Name (string) or Name (null) (Name)

Name of the product

Custom Properties (object) or Custom Properties (null) (Custom Properties)
Default: {}

Custom properties

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "custom_properties": { }
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "name": "string",
  • "custom_properties": { }
}

Prices

Retrieve a price by id

Use this endpoint to retrieve a price by providing its id.

Authorizations:
APIKey
path Parameters
id
required
string (Id)

The id of the price to retrieve

Responses

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "name": "string",
  • "period_unit": "string",
  • "period_length": 0,
  • "product_id": "string",
  • "type": "string",
  • "amount": 0,
  • "currency_code": "string",
  • "custom_properties": { }
}

Update a price by id

Use this endpoint to update a price by id. Partial updates are supported: only the fields specified in the request body will be updated. Custom properties are supported and can be set in the custom_properties (dictionary) inside the request body.

Authorizations:
APIKey
path Parameters
id
required
string (Id)

The id of the price to update

Request Body schema: application/json
required
Id (string) or Id (null) (Id)

Unique identifier for the price.

Name (string) or Name (null) (Name)

Name of the price item

Period Unit (string) or Period Unit (null) (Period Unit)

Time unit of the billing frequency (only for subscription type). Possible values: day, week, month, year

Period Length (integer) or Period Length (null) (Period Length)

Number of units of the billing frequency (only for subscription type).

Product Id (string) or Product Id (null) (Product Id)

Identifier of the product related to this price item

Type (string) or Type (null) (Type)

Type of the price item. Possible values: one_off, subscription

Amount (number) or Amount (null) (Amount)

Amount of the price item

Currency Code (string) or Currency Code (null) (Currency Code)

Currency code

Custom Properties (object) or Custom Properties (null) (Custom Properties)
Default: {}

Custom properties

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "period_unit": "string",
  • "period_length": 0,
  • "product_id": "string",
  • "type": "string",
  • "amount": 0,
  • "currency_code": "string",
  • "custom_properties": { }
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "name": "string",
  • "period_unit": "string",
  • "period_length": 0,
  • "product_id": "string",
  • "type": "string",
  • "amount": 0,
  • "currency_code": "string",
  • "custom_properties": { }
}

Delete a price by id

Use this endpoint to delete a price by providing its id.

Authorizations:
APIKey
path Parameters
id
required
string (Id)

The id of the price to delete

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Create a new price

Use this endpoint to create a new price. Custom properties are supported and can be set in the custom_properties (dictionary) inside the request body.

Authorizations:
APIKey
Request Body schema: application/json
required
id
required
string (Id)

Unique identifier for the price.

Name (string) or Name (null) (Name)

Name of the price item

Period Unit (string) or Period Unit (null) (Period Unit)

Time unit of the billing frequency (only for subscription type). Possible values: day, week, month, year

Period Length (integer) or Period Length (null) (Period Length)

Number of units of the billing frequency (only for subscription type).

Product Id (string) or Product Id (null) (Product Id)

Identifier of the product related to this price item

Type (string) or Type (null) (Type)

Type of the price item. Possible values: one_off, subscription

Amount (number) or Amount (null) (Amount)

Amount of the price item

Currency Code (string) or Currency Code (null) (Currency Code)

Currency code

Custom Properties (object) or Custom Properties (null) (Custom Properties)
Default: {}

Custom properties

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "period_unit": "string",
  • "period_length": 0,
  • "product_id": "string",
  • "type": "string",
  • "amount": 0,
  • "currency_code": "string",
  • "custom_properties": { }
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "name": "string",
  • "period_unit": "string",
  • "period_length": 0,
  • "product_id": "string",
  • "type": "string",
  • "amount": 0,
  • "currency_code": "string",
  • "custom_properties": { }
}

Invoices

Retrieve an invoice by id

Use this endpoint to retrieve an invoice by providing its id.

Authorizations:
APIKey
path Parameters
id
required
string (Id)

The id of the invoice to retrieve

Responses

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "customer_id": "string",
  • "invoice_number": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "status": "string",
  • "is_renew": "string",
  • "custom_properties": { },
  • "invoice_line_items": [ ]
}

Update an invoice by id

Use this endpoint to update an invoice by id. Partial updates are supported: only the fields specified in the request body will be updated. Custom properties are supported and can be set in the custom_properties (dictionary) inside the request body.

Authorizations:
APIKey
path Parameters
id
required
string (Id)

The id of the invoice to update

Request Body schema: application/json
required
Id (string) or Id (null) (Id)

Unique identifier for the invoice.

Customer Id (string) or Customer Id (null) (Customer Id)

Identifier of the customer to whom the invoice belongs

Invoice Number (string) or Invoice Number (null) (Invoice Number)

Invoice number

Date (string) or Date (null) (Date)

Issue date of the invoice

Status (string) or Status (null) (Status)

Status of the invoice. Possible values: open, pending, paid, unpaid, void

Is Renew (string) or Is Renew (null) (Is Renew)

Flag indicating if the invoice is originated from the renewal of a subscription

Custom Properties (object) or Custom Properties (null) (Custom Properties)
Default: {}

Custom properties

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "customer_id": "string",
  • "invoice_number": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "status": "string",
  • "is_renew": "string",
  • "custom_properties": { }
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "customer_id": "string",
  • "invoice_number": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "status": "string",
  • "is_renew": "string",
  • "custom_properties": { },
  • "invoice_line_items": [ ]
}

Delete an invoice by id

Use this endpoint to delete an invoice by providing its id.

Authorizations:
APIKey
path Parameters
id
required
string (Id)

The id of the invoice to delete

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Create a new invoice

Use this endpoint to create a new invoice. Custom properties are supported and can be set in the custom_properties (dictionary) inside the request body.

Authorizations:
APIKey
Request Body schema: application/json
required
id
required
string (Id)

Unique identifier for the invoice.

customer_id
required
string (Customer Id)

Identifier of the customer to whom the invoice belongs

Invoice Number (string) or Invoice Number (null) (Invoice Number)

Invoice number

date
required
string <date-time> (Date)

Issue date of the invoice

status
required
string (Status)

Status of the invoice. Possible values: open, pending, paid, unpaid, void

Is Renew (string) or Is Renew (null) (Is Renew)

Flag indicating if the invoice is originated from the renewal of a subscription

Custom Properties (object) or Custom Properties (null) (Custom Properties)
Default: {}

Custom properties

Array of Invoice Line Items (objects) or Invoice Line Items (null) (Invoice Line Items)
Default: []

List of invoice line items belonging to this invoice

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "customer_id": "string",
  • "invoice_number": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "status": "string",
  • "is_renew": "string",
  • "custom_properties": { },
  • "invoice_line_items": [ ]
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "customer_id": "string",
  • "invoice_number": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "status": "string",
  • "is_renew": "string",
  • "custom_properties": { },
  • "invoice_line_items": [ ]
}

Credit Notes

Retrieve a credit note by id

Use this endpoint to retrieve a credit note by providing its id.

Authorizations:
APIKey
path Parameters
id
required
string (Id)

The id of the credit note to retrieve

Responses

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "invoice_id": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "status": "string",
  • "custom_properties": { },
  • "credit_note_line_items": [ ]
}

Update a credit note by id

Use this endpoint to update a credit note by id. Partial updates are supported: only the fields specified in the request body will be updated. Custom properties are supported and can be set in the custom_properties (dictionary) inside the request body.

Authorizations:
APIKey
path Parameters
id
required
string (Id)

The id of the credit note to update

Request Body schema: application/json
required
Id (string) or Id (null) (Id)

Unique identifier for the credit note.

Invoice Id (string) or Invoice Id (null) (Invoice Id)

Identifier of the invoice to which this credit note is attached

Date (string) or Date (null) (Date)

Issue date of the credit note

Status (string) or Status (null) (Status)

Status of the invoice. Possible values: refunded, refund_due

Custom Properties (object) or Custom Properties (null) (Custom Properties)
Default: {}

Custom properties

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "invoice_id": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "status": "string",
  • "custom_properties": { }
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "invoice_id": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "status": "string",
  • "custom_properties": { },
  • "credit_note_line_items": [ ]
}

Delete a credit note by id

Use this endpoint to delete a credit note by providing its id.

Authorizations:
APIKey
path Parameters
id
required
string (Id)

The id of the credit note to delete

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Create a new credit note

Use this endpoint to create a new credit note. Custom properties are supported and can be set in the custom_properties (dictionary) inside the request body.

Authorizations:
APIKey
Request Body schema: application/json
required
id
required
string (Id)

Unique identifier for the credit note.

invoice_id
required
string (Invoice Id)

Identifier of the invoice to which this credit note is attached

Date (string) or Date (null) (Date)

Issue date of the credit note

Status (string) or Status (null) (Status)

Status of the invoice. Possible values: refunded, refund_due

Custom Properties (object) or Custom Properties (null) (Custom Properties)
Default: {}

Custom properties

Array of Credit Note Line Items (objects) or Credit Note Line Items (null) (Credit Note Line Items)
Default: []

List of credit note line items belonging to this credit note

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "invoice_id": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "status": "string",
  • "custom_properties": { },
  • "credit_note_line_items": [ ]
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "invoice_id": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "status": "string",
  • "custom_properties": { },
  • "credit_note_line_items": [ ]
}

Subscriptions

Retrieve a subscription by id

Use this endpoint to retrieve a subscription by providing its id.

Authorizations:
APIKey
path Parameters
id
required
string (Id)

The id of the subscription to retrieve

Responses

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "customer_id": "string",
  • "status": "string",
  • "subscription_set_id": "string",
  • "trial_start": "2019-08-24T14:15:22Z",
  • "trial_end": "2019-08-24T14:15:22Z",
  • "canceled_at": "2019-08-24T14:15:22Z",
  • "effective_cancellation_date": "2019-08-24T14:15:22Z",
  • "subscription_start_date": "2019-08-24T14:15:22Z",
  • "deal_closed_date": "2019-08-24T14:15:22Z",
  • "contractual_commitment_end_date": "2019-08-24T14:15:22Z",
  • "monthly_value": 0,
  • "currency_code": "string",
  • "price_id": "string",
  • "custom_properties": { }
}

Update a subscription by id

Use this endpoint to update a subscription by id. Partial updates are supported: only the fields specified in the request body will be updated. Custom properties are supported and can be set in the custom_properties (dictionary) inside the request body.

Authorizations:
APIKey
path Parameters
id
required
string (Id)

The id of the subscription to update

Request Body schema: application/json
required
Id (string) or Id (null) (Id)

Unique identifier for the subscription.

Customer Id (string) or Customer Id (null) (Customer Id)

Identifier of the customer to which this subscription belongs

Status (string) or Status (null) (Status)

Status of the subscription. One of trialing, active, paused, canceled, unpaid

Subscription Set Id (string) or Subscription Set Id (null) (Subscription Set Id)

Identifier of the subscription set to which this subscription belongs

Trial Start (string) or Trial Start (null) (Trial Start)

Start date (UTC) of the trial period (if any)

Trial End (string) or Trial End (null) (Trial End)

End date (UTC) of the trial period (if any)

Canceled At (string) or Canceled At (null) (Canceled At)

If the subscription was cancelled, the cancellation date (UTC)

Effective Cancellation Date (string) or Effective Cancellation Date (null) (Effective Cancellation Date)

If the subscription was cancelled, the date date at which this cancellation was (or will be) effective

Subscription Start Date (string) or Subscription Start Date (null) (Subscription Start Date)

The date (UTC) when the subscription started or will start in the future. Corresponds to the start date of the first invoice and the beginning of the service period.

Deal Closed Date (string) or Deal Closed Date (null) (Deal Closed Date)

The date (UTC) on which the subscription deal was finalized, marking its official confirmation. This date can be set earlier than the subscription_start_date. The subscription amount will contribute to the Committed Monthly Recurring Revenue (CMRR) from the deal_closed_date, while it will count towards Monthly Recurring Revenue (MRR) starting from the subscription_start_date, which denotes the beginning of the first billing period.

Contractual Commitment End Date (string) or Contractual Commitment End Date (null) (Contractual Commitment End Date)

If the subscription is in a contractual commitment, the end date (UTC) of the commitment

Monthly Value (number) or Monthly Value (null) (Monthly Value)

Monthly value of the subscription

Currency Code (string) or Currency Code (null) (Currency Code)

Currency code of the monthly value of the subscription

Price Id (string) or Price Id (null) (Price Id)

Identifier of the price object (a plan) to which this subscription belongs

Custom Properties (object) or Custom Properties (null) (Custom Properties)
Default: {}

Custom properties

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "customer_id": "string",
  • "status": "string",
  • "subscription_set_id": "string",
  • "trial_start": "2019-08-24T14:15:22Z",
  • "trial_end": "2019-08-24T14:15:22Z",
  • "canceled_at": "2019-08-24T14:15:22Z",
  • "effective_cancellation_date": "2019-08-24T14:15:22Z",
  • "subscription_start_date": "2019-08-24T14:15:22Z",
  • "deal_closed_date": "2019-08-24T14:15:22Z",
  • "contractual_commitment_end_date": "2019-08-24T14:15:22Z",
  • "monthly_value": 0,
  • "currency_code": "string",
  • "price_id": "string",
  • "custom_properties": { }
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "customer_id": "string",
  • "status": "string",
  • "subscription_set_id": "string",
  • "trial_start": "2019-08-24T14:15:22Z",
  • "trial_end": "2019-08-24T14:15:22Z",
  • "canceled_at": "2019-08-24T14:15:22Z",
  • "effective_cancellation_date": "2019-08-24T14:15:22Z",
  • "subscription_start_date": "2019-08-24T14:15:22Z",
  • "deal_closed_date": "2019-08-24T14:15:22Z",
  • "contractual_commitment_end_date": "2019-08-24T14:15:22Z",
  • "monthly_value": 0,
  • "currency_code": "string",
  • "price_id": "string",
  • "custom_properties": { }
}

Delete a subscription by id

Use this endpoint to delete a subscription by providing its id.

Authorizations:
APIKey
path Parameters
id
required
string (Id)

The id of the subscription to delete

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Create a new subscription

Use this endpoint to create a new subscription. Custom properties are supported and can be set in the custom_properties (dictionary) inside the request body.

Authorizations:
APIKey
Request Body schema: application/json
required
id
required
string (Id)

Unique identifier for the subscription.

Customer Id (string) or Customer Id (null) (Customer Id)

Identifier of the customer to which this subscription belongs

Status (string) or Status (null) (Status)

Status of the subscription. One of trialing, active, paused, canceled, unpaid

Subscription Set Id (string) or Subscription Set Id (null) (Subscription Set Id)

Identifier of the subscription set to which this subscription belongs

Trial Start (string) or Trial Start (null) (Trial Start)

Start date (UTC) of the trial period (if any)

Trial End (string) or Trial End (null) (Trial End)

End date (UTC) of the trial period (if any)

Canceled At (string) or Canceled At (null) (Canceled At)

If the subscription was cancelled, the cancellation date (UTC)

Effective Cancellation Date (string) or Effective Cancellation Date (null) (Effective Cancellation Date)

If the subscription was cancelled, the date date at which this cancellation was (or will be) effective

Subscription Start Date (string) or Subscription Start Date (null) (Subscription Start Date)

The date (UTC) when the subscription started or will start in the future. Corresponds to the start date of the first invoice and the beginning of the service period.

Deal Closed Date (string) or Deal Closed Date (null) (Deal Closed Date)

The date (UTC) on which the subscription deal was finalized, marking its official confirmation. This date can be set earlier than the subscription_start_date. The subscription amount will contribute to the Committed Monthly Recurring Revenue (CMRR) from the deal_closed_date, while it will count towards Monthly Recurring Revenue (MRR) starting from the subscription_start_date, which denotes the beginning of the first billing period.

Contractual Commitment End Date (string) or Contractual Commitment End Date (null) (Contractual Commitment End Date)

If the subscription is in a contractual commitment, the end date (UTC) of the commitment

Monthly Value (number) or Monthly Value (null) (Monthly Value)

Monthly value of the subscription

Currency Code (string) or Currency Code (null) (Currency Code)

Currency code of the monthly value of the subscription

Price Id (string) or Price Id (null) (Price Id)

Identifier of the price object (a plan) to which this subscription belongs

Custom Properties (object) or Custom Properties (null) (Custom Properties)
Default: {}

Custom properties

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "customer_id": "string",
  • "status": "string",
  • "subscription_set_id": "string",
  • "trial_start": "2019-08-24T14:15:22Z",
  • "trial_end": "2019-08-24T14:15:22Z",
  • "canceled_at": "2019-08-24T14:15:22Z",
  • "effective_cancellation_date": "2019-08-24T14:15:22Z",
  • "subscription_start_date": "2019-08-24T14:15:22Z",
  • "deal_closed_date": "2019-08-24T14:15:22Z",
  • "contractual_commitment_end_date": "2019-08-24T14:15:22Z",
  • "monthly_value": 0,
  • "currency_code": "string",
  • "price_id": "string",
  • "custom_properties": { }
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "customer_id": "string",
  • "status": "string",
  • "subscription_set_id": "string",
  • "trial_start": "2019-08-24T14:15:22Z",
  • "trial_end": "2019-08-24T14:15:22Z",
  • "canceled_at": "2019-08-24T14:15:22Z",
  • "effective_cancellation_date": "2019-08-24T14:15:22Z",
  • "subscription_start_date": "2019-08-24T14:15:22Z",
  • "deal_closed_date": "2019-08-24T14:15:22Z",
  • "contractual_commitment_end_date": "2019-08-24T14:15:22Z",
  • "monthly_value": 0,
  • "currency_code": "string",
  • "price_id": "string",
  • "custom_properties": { }
}

Invoice Line Items

Retrieve an invoice line item by id

Use this endpoint to retrieve an invoice line item by providing its id.

Authorizations:
APIKey
path Parameters
id
required
string (Id)

The id of the invoice line item to retrieve

Responses

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "invoice_id": "string",
  • "subscription_id": "string",
  • "price_id": "string",
  • "type": "string",
  • "amount_excluding_tax_after_discount": 0,
  • "tax_amount": 0,
  • "discount_amount": 0,
  • "temporary_discount_amount": 0,
  • "currency_code": "string",
  • "quantity": 0,
  • "description": "string",
  • "period_start": "2019-08-24T14:15:22Z",
  • "period_end": "2019-08-24T14:15:22Z",
  • "proration_target_line_item_id": "string",
  • "custom_properties": { }
}

Update an invoice line item by id

Use this endpoint to update an invoice line item by id. Partial updates are supported: only the fields specified in the request body will be updated. Custom properties are supported and can be set in the custom_properties (dictionary) inside the request body.

Authorizations:
APIKey
path Parameters
id
required
string (Id)

The id of the invoice line item to update

Request Body schema: application/json
required
Id (string) or Id (null) (Id)

Unique identifier for the invoice line item.

Invoice Id (string) or Invoice Id (null) (Invoice Id)

Identifier of the invoice to which this line item belongs

Subscription Id (string) or Subscription Id (null) (Subscription Id)

Identifier of the subscription to which this line item is related

Price Id (string) or Price Id (null) (Price Id)

Identifier of the price to which this line item is related

Type (string) or Type (null) (Type)

Type of the invoice line item. Possible values: subscription, one_off

Amount Excluding Tax After Discount (number) or Amount Excluding Tax After Discount (null) (Amount Excluding Tax After Discount)

Amount of the invoice line item (excluding tax and after discount)

Tax Amount (number) or Tax Amount (null) (Tax Amount)

Tax amount

Discount Amount (number) or Discount Amount (null) (Discount Amount)
Default: 0

Permanent discount amount

Temporary Discount Amount (number) or Temporary Discount Amount (null) (Temporary Discount Amount)
Default: 0

Temporary discount_amount

Currency Code (string) or Currency Code (null) (Currency Code)

Currency code of the invoice line item

Quantity (integer) or Quantity (null) (Quantity)

Quantity of bought items

Description (string) or Description (null) (Description)

Description of the invoice line item

Period Start (string) or Period Start (null) (Period Start)

Start date (UTC) of the subscription period billed by this line item (only for subscription type)

Period End (string) or Period End (null) (Period End)

End date (UTC) of the subscription period billed by this line item (only for subscription type)

Proration Target Line Item Id (string) or Proration Target Line Item Id (null) (Proration Target Line Item Id)

In case this line item is a proration line item, the identifier of the original (positive) line item it applies on

Custom Properties (object) or Custom Properties (null) (Custom Properties)
Default: {}

Custom properties

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "invoice_id": "string",
  • "subscription_id": "string",
  • "price_id": "string",
  • "type": "string",
  • "amount_excluding_tax_after_discount": 0,
  • "tax_amount": 0,
  • "discount_amount": 0,
  • "temporary_discount_amount": 0,
  • "currency_code": "string",
  • "quantity": 0,
  • "description": "string",
  • "period_start": "2019-08-24T14:15:22Z",
  • "period_end": "2019-08-24T14:15:22Z",
  • "proration_target_line_item_id": "string",
  • "custom_properties": { }
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "invoice_id": "string",
  • "subscription_id": "string",
  • "price_id": "string",
  • "type": "string",
  • "amount_excluding_tax_after_discount": 0,
  • "tax_amount": 0,
  • "discount_amount": 0,
  • "temporary_discount_amount": 0,
  • "currency_code": "string",
  • "quantity": 0,
  • "description": "string",
  • "period_start": "2019-08-24T14:15:22Z",
  • "period_end": "2019-08-24T14:15:22Z",
  • "proration_target_line_item_id": "string",
  • "custom_properties": { }
}

Delete an invoice line item by id

Use this endpoint to delete an invoice line item by providing its id.

Authorizations:
APIKey
path Parameters
id
required
string (Id)

The id of the invoice line item to delete

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Create a new invoice line item

Use this endpoint to create a new invoice line item. Custom properties are supported and can be set in the custom_properties (dictionary) inside the request body.

Authorizations:
APIKey
Request Body schema: application/json
required
id
required
string (Id)

Unique identifier for the invoice line item.

invoice_id
required
string (Invoice Id)

Identifier of the invoice to which this line item belongs

Subscription Id (string) or Subscription Id (null) (Subscription Id)

Identifier of the subscription to which this line item is related

Price Id (string) or Price Id (null) (Price Id)

Identifier of the price to which this line item is related

type
required
string (Type)

Type of the invoice line item. Possible values: subscription, one_off

amount_excluding_tax_after_discount
required
number (Amount Excluding Tax After Discount)

Amount of the invoice line item (excluding tax and after discount)

tax_amount
required
number (Tax Amount)

Tax amount

Discount Amount (number) or Discount Amount (null) (Discount Amount)
Default: 0

Permanent discount amount

Temporary Discount Amount (number) or Temporary Discount Amount (null) (Temporary Discount Amount)
Default: 0

Temporary discount_amount

currency_code
required
string (Currency Code)

Currency code of the invoice line item

Quantity (integer) or Quantity (null) (Quantity)

Quantity of bought items

Description (string) or Description (null) (Description)

Description of the invoice line item

Period Start (string) or Period Start (null) (Period Start)

Start date (UTC) of the subscription period billed by this line item (only for subscription type)

Period End (string) or Period End (null) (Period End)

End date (UTC) of the subscription period billed by this line item (only for subscription type)

Proration Target Line Item Id (string) or Proration Target Line Item Id (null) (Proration Target Line Item Id)

In case this line item is a proration line item, the identifier of the original (positive) line item it applies on

Custom Properties (object) or Custom Properties (null) (Custom Properties)
Default: {}

Custom properties

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "invoice_id": "string",
  • "subscription_id": "string",
  • "price_id": "string",
  • "type": "string",
  • "amount_excluding_tax_after_discount": 0,
  • "tax_amount": 0,
  • "discount_amount": 0,
  • "temporary_discount_amount": 0,
  • "currency_code": "string",
  • "quantity": 0,
  • "description": "string",
  • "period_start": "2019-08-24T14:15:22Z",
  • "period_end": "2019-08-24T14:15:22Z",
  • "proration_target_line_item_id": "string",
  • "custom_properties": { }
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "invoice_id": "string",
  • "subscription_id": "string",
  • "price_id": "string",
  • "type": "string",
  • "amount_excluding_tax_after_discount": 0,
  • "tax_amount": 0,
  • "discount_amount": 0,
  • "temporary_discount_amount": 0,
  • "currency_code": "string",
  • "quantity": 0,
  • "description": "string",
  • "period_start": "2019-08-24T14:15:22Z",
  • "period_end": "2019-08-24T14:15:22Z",
  • "proration_target_line_item_id": "string",
  • "custom_properties": { }
}

Credit Note Line Items

Retrieve a credit note line item by id

Use this endpoint to retrieve a credit note line item by providing its id.

Authorizations:
APIKey
path Parameters
id
required
string (Id)

The id of the credit note line item to retrieve

Responses

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "credit_note_id": "string",
  • "invoice_line_item_id": "string",
  • "amount": 0,
  • "discount_amount": 0,
  • "temporary_discount_amount": 0,
  • "currency_code": "string",
  • "description": "string",
  • "custom_properties": { }
}

Update a credit note line item by id

Use this endpoint to update a credit note line item by id. Partial updates are supported: only the fields specified in the request body will be updated. Custom properties are supported and can be set in the custom_properties (dictionary) inside the request body.

Authorizations:
APIKey
path Parameters
id
required
string (Id)

The id of the credit note line item to update

Request Body schema: application/json
required
Id (string) or Id (null) (Id)

Unique identifier for the credit note line item.

Credit Note Id (string) or Credit Note Id (null) (Credit Note Id)

Identifier of the credit note to which the credit note line item belongs

Invoice Line Item Id (string) or Invoice Line Item Id (null) (Invoice Line Item Id)

Identifier of the invoice line item to which the credit note line item is attached

Amount (number) or Amount (null) (Amount)

Amount of the credit note line item

Discount Amount (number) or Discount Amount (null) (Discount Amount)
Default: 0

Permanent discount amount of the credit note line item

Temporary Discount Amount (number) or Temporary Discount Amount (null) (Temporary Discount Amount)
Default: 0

Temporary discount amount of the credit note line item

Currency Code (string) or Currency Code (null) (Currency Code)

Currency code of the credit note line item

Description (string) or Description (null) (Description)

Description of the credit note line item

Custom Properties (object) or Custom Properties (null) (Custom Properties)
Default: {}

Custom properties

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "credit_note_id": "string",
  • "invoice_line_item_id": "string",
  • "amount": 0,
  • "discount_amount": 0,
  • "temporary_discount_amount": 0,
  • "currency_code": "string",
  • "description": "string",
  • "custom_properties": { }
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "credit_note_id": "string",
  • "invoice_line_item_id": "string",
  • "amount": 0,
  • "discount_amount": 0,
  • "temporary_discount_amount": 0,
  • "currency_code": "string",
  • "description": "string",
  • "custom_properties": { }
}

Delete a credit note line item by id

Use this endpoint to delete a credit note line item by providing its id.

Authorizations:
APIKey
path Parameters
id
required
string (Id)

The id of the credit note line item to delete

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Create a new credit note line item

Use this endpoint to create a new credit note line item. Custom properties are supported and can be set in the custom_properties (dictionary) inside the request body.

Authorizations:
APIKey
Request Body schema: application/json
required
id
required
string (Id)

Unique identifier for the credit note line item.

credit_note_id
required
string (Credit Note Id)

Identifier of the credit note to which the credit note line item belongs

Invoice Line Item Id (string) or Invoice Line Item Id (null) (Invoice Line Item Id)

Identifier of the invoice line item to which the credit note line item is attached

amount
required
number (Amount)

Amount of the credit note line item

Discount Amount (number) or Discount Amount (null) (Discount Amount)
Default: 0

Permanent discount amount of the credit note line item

Temporary Discount Amount (number) or Temporary Discount Amount (null) (Temporary Discount Amount)
Default: 0

Temporary discount amount of the credit note line item

currency_code
required
string (Currency Code)

Currency code of the credit note line item

Description (string) or Description (null) (Description)

Description of the credit note line item

Custom Properties (object) or Custom Properties (null) (Custom Properties)
Default: {}

Custom properties

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "credit_note_id": "string",
  • "invoice_line_item_id": "string",
  • "amount": 0,
  • "discount_amount": 0,
  • "temporary_discount_amount": 0,
  • "currency_code": "string",
  • "description": "string",
  • "custom_properties": { }
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "credit_note_id": "string",
  • "invoice_line_item_id": "string",
  • "amount": 0,
  • "discount_amount": 0,
  • "temporary_discount_amount": 0,
  • "currency_code": "string",
  • "description": "string",
  • "custom_properties": { }
}

Export API

List available metrics

List the metrics available to your company, grouped into report families (one-level hierarchy). Address an individual metric by its slug.

Authorizations:
APIKey

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a metric series

Compute a single metric for the caller's company over an inclusive period range at the given grain. A date selects the whole period it falls in; the result spans every period from the one containing date_start through the one containing date_end (e.g. monthly 2024-05-01→2024-05-31 = May; 2024-05-01→2024-06-01 = May and June). Returns a UI-free MetricResult (kind, series, per-point period_start/period_end/as_of).

Authorizations:
APIKey
path Parameters
slug
required
string (Slug)
query Parameters
Date Start (string) or Date Start (null) (Date Start)

ISO date (YYYY-MM-DD). Selects the period it falls in (inclusive). Defaults to one year before date_end.

Date End (string) or Date End (null) (Date End)

ISO date (YYYY-MM-DD). Selects the period it falls in (inclusive — end within a month to exclude the next one). Defaults to the company freshness date (current period included).

date_step
string (Date Step)
Default: "month"

Time grain. One of: month, quarter, year.

Dimension (string) or Dimension (null) (Dimension)

Break the result into one series per dimension value. Either a dimension id from GET /metrics/{slug}/dimensions (e.g. product) or its human name (e.g. a custom axis's Vertical). The mrr-growth metrics advertise mrr_movement_type as their natural breakdown — each period's net change split by movement type (new, expansion, contraction, lost, reactivated). With no dimension the result is the flat total per period; pass mrr_movement_type for the split, or another dimension for the net variation broken down by that axis. The movement-type components are computed within each period, so they are grain-dependent: a finer date_step (month) reports more gross movement than a coarser one (year) because intra-period reversals (expand-then-contract, churn-then-reactivate) net out at the coarser grain. The net always reconciles to the metric's delta at every grain; the components do not sum across grains.

Filters (string) or Filters (null) (Filters)

JSON array of {field, op, value} narrowing the data (op ∈ eq, neq, in, not_in, gt, gte, lt, lte, contains, between). The comparison ops (neq/gt/gte/lt/lte/between) are numeric — use in/not_in to match or exclude text values. field must be an available dimension. Example: [{"field": "invoice/status", "op": "in", "value": ["paid"]}]. For the mrr-growth metrics, filtering mrr_movement_type to one value focuses that single movement (e.g. net-new MRR), optionally combined with a breakdown dimension (net-new MRR by that axis).

Responses

Response samples

Content type
application/json
{
  • "slug": "string",
  • "label": "string",
  • "unit": "string",
  • "currency": "string",
  • "kind": "point_in_time",
  • "timegrain": "string",
  • "dimensions": [
    ],
  • "series": [
    ],
  • "meta": {
    }
}

List a metric's dimensions

List the breakdown/filter dimensions available for this metric on your company (incl. your custom axes). filter_only dimensions may be used in filters but not as a breakdown dimension.

Authorizations:
APIKey
path Parameters
slug
required
string (Slug)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List available views

List the row-level views available to your company. Columns are returned by the describe endpoint, not here.

Authorizations:
APIKey

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Describe a view

Describe a view — its label and columns (name + type) — without reading any rows. The metadata counterpart to the query endpoint.

Authorizations:
APIKey
path Parameters
slug
required
string (Slug)

Responses

Response samples

Content type
application/json
{
  • "slug": "string",
  • "label": "string",
  • "columns": [
    ],
  • "time": {
    }
}

Query a view

Read rows from a view for your company. Supports structured filters ({field, op, value}; no raw SQL), order_by/order_dir, and bounded pagination (limit ≤ 1000, offset).

Authorizations:
APIKey
path Parameters
slug
required
string (Slug)
query Parameters
Filters (string) or Filters (null) (Filters)

JSON array of {field, op, value} (op ∈ eq, neq, in, not_in, gt, gte, lt, lte, contains, between). field is a view column. contains is a case-insensitive substring match where SQL LIKE wildcards in the value are honored — % matches any run of characters and _ any single character (e.g. ab% is a prefix match).

Order By (string) or Order By (null) (Order By)

Column to sort by. Defaults to the view's sort.

order_dir
string (Order Dir)
Default: "asc"

Sort direction: asc or desc.

Limit (integer) or Limit (null) (Limit)

Page size (default 100, max 1000).

offset
integer (Offset) >= 0
Default: 0

Row offset for pagination.

date_step
string (Date Step)
Default: "month"

Grain. One of: month, quarter, year.

Date Start (string) or Date Start (null) (Date Start)

Filter by time (ISO YYYY-MM-DD): inclusive start of the period window. Selects whole periods like the metrics API — a date picks the period it falls in. Filter time with these, not the output period_start/period_end/as_of_date columns.

Date End (string) or Date End (null) (Date End)

Filter by time (ISO YYYY-MM-DD): inclusive end of the period window.

Responses

Response samples

Content type
application/json
{
  • "slug": "string",
  • "columns": [
    ],
  • "rows": [
    ],
  • "page": {
    },
  • "time": {
    }
}

Refresh dashboard

Force the dashboard to refresh

Launches a process to refresh the dashboard. Once the refresh is done, the dashboard will be updated with the new data. A notification will be sent to the user's email.

Authorizations:
APIKey

Responses

Response samples

Content type
application/json
null