Developers
Developers
Invoice
Invoices are normally generated automatically in Planhat when a license is created or renewed, invoices can include multiple line items. Planhat will not prepare invoices that you actually can send to your customers though. They're rather meant to help anyone working with your customers to know the status of current and past invoicing.
Invoices default date fields format should be days format integer. (Days since January 1, 1970, Unix epoch)
Property | Required | Type | Description |
|---|---|---|---|
_id | objectId | Planhat identifier. | |
currency | Yes | string | The currency code, for example "USD". There is a "soft" mapping to the id’s in your list of currencies. Technically we accept any string but we recommend using standard currency codes as Ids. Since the mapping is soft you can add sales with a currency code not yet available in your list of currencies. |
product | string | Name of the sales product. Not required but highly recommended. Even if you only have one product we suggest adding it as "Advanced Onboarding". | |
cId | Yes | objectId | Related company id (planhat identifier). |
cName | string | Company name. (Autogenerated). | |
extId | string | The invoice id in your own system. | |
sourceId | string | The invoice id from an integration (Salesforce, Hubspot, etc). | |
invoiceDate | integer | Date when invoice was created should be in days format integer. | |
lastUpdated | string | ISO date when invoice was updated. (Autogenerated). | |
invoiceNo | integer | Invoice number. (Autogenerated). | |
dueDate | integer | Date when invoice expires in days format integer. | |
paidDate | integer | Date when invoice is paid should be in days format integer. | |
amountTotal | number | Invoice amount. | |
status | string | Status of invoice could be pending, paid, overdue. | |
lineItems | array | Array of license objects. (Autogenerated). | |
emails | array | Internal system field. (Autogenerated). | |
addressCountry | string | Country where the invoice is issued. (Autogenerated). | |
invoiceCycle | string | Cycle of the invoice. Could be one of: monthly, quarterly, yearly, semiAnnual, once or custom. (Autogenerated). | |
custom | object | A flexible object with custom data. |
Invoices are normally generated automatically in Planhat when a license is created or renewed, invoices can include multiple line items. Planhat will not prepare invoices that you actually can send to your customers though. They're rather meant to help anyone working with your customers to know the status of current and past invoicing.
Invoices default date fields format should be days format integer. (Days since January 1, 1970, Unix epoch)
Property | Required | Type | Description |
|---|---|---|---|
_id | objectId | Planhat identifier. | |
currency | Yes | string | The currency code, for example "USD". There is a "soft" mapping to the id’s in your list of currencies. Technically we accept any string but we recommend using standard currency codes as Ids. Since the mapping is soft you can add sales with a currency code not yet available in your list of currencies. |
product | string | Name of the sales product. Not required but highly recommended. Even if you only have one product we suggest adding it as "Advanced Onboarding". | |
cId | Yes | objectId | Related company id (planhat identifier). |
cName | string | Company name. (Autogenerated). | |
extId | string | The invoice id in your own system. | |
sourceId | string | The invoice id from an integration (Salesforce, Hubspot, etc). | |
invoiceDate | integer | Date when invoice was created should be in days format integer. | |
lastUpdated | string | ISO date when invoice was updated. (Autogenerated). | |
invoiceNo | integer | Invoice number. (Autogenerated). | |
dueDate | integer | Date when invoice expires in days format integer. | |
paidDate | integer | Date when invoice is paid should be in days format integer. | |
amountTotal | number | Invoice amount. | |
status | string | Status of invoice could be pending, paid, overdue. | |
lineItems | array | Array of license objects. (Autogenerated). | |
emails | array | Internal system field. (Autogenerated). | |
addressCountry | string | Country where the invoice is issued. (Autogenerated). | |
invoiceCycle | string | Cycle of the invoice. Could be one of: monthly, quarterly, yearly, semiAnnual, once or custom. (Autogenerated). | |
custom | object | A flexible object with custom data. |
Invoices are normally generated automatically in Planhat when a license is created or renewed, invoices can include multiple line items. Planhat will not prepare invoices that you actually can send to your customers though. They're rather meant to help anyone working with your customers to know the status of current and past invoicing.
Invoices default date fields format should be days format integer. (Days since January 1, 1970, Unix epoch)
Property | Required | Type | Description |
|---|---|---|---|
_id | objectId | Planhat identifier. | |
currency | Yes | string | The currency code, for example "USD". There is a "soft" mapping to the id’s in your list of currencies. Technically we accept any string but we recommend using standard currency codes as Ids. Since the mapping is soft you can add sales with a currency code not yet available in your list of currencies. |
product | string | Name of the sales product. Not required but highly recommended. Even if you only have one product we suggest adding it as "Advanced Onboarding". | |
cId | Yes | objectId | Related company id (planhat identifier). |
cName | string | Company name. (Autogenerated). | |
extId | string | The invoice id in your own system. | |
sourceId | string | The invoice id from an integration (Salesforce, Hubspot, etc). | |
invoiceDate | integer | Date when invoice was created should be in days format integer. | |
lastUpdated | string | ISO date when invoice was updated. (Autogenerated). | |
invoiceNo | integer | Invoice number. (Autogenerated). | |
dueDate | integer | Date when invoice expires in days format integer. | |
paidDate | integer | Date when invoice is paid should be in days format integer. | |
amountTotal | number | Invoice amount. | |
status | string | Status of invoice could be pending, paid, overdue. | |
lineItems | array | Array of license objects. (Autogenerated). | |
emails | array | Internal system field. (Autogenerated). | |
addressCountry | string | Country where the invoice is issued. (Autogenerated). | |
invoiceCycle | string | Cycle of the invoice. Could be one of: monthly, quarterly, yearly, semiAnnual, once or custom. (Autogenerated). | |
custom | object | A flexible object with custom data. |
Create invoice
To create an invoice the only real value that is required is the cId but it doesn't make much sense to have an invoice just with a cId, that is why we suggest specifying a invoiceDate and currency.
You can instead reference the company externalId or sourceId using the following command structure: "cId": "extid-[company externalId]" or "cId": "srcid-[company sourceId]".
Example Request
curl --location -g --request POST 'https://api.planhat.com/invoices' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"dueDate": 19201,
"invoiceDate": 18836,
"currency": "USD",
"amountTotal": 10000,
"lineItems": [
{
"relatedId": "sale-61016c80675c1b871faf2d4f",
"saleId": "61016c80675c1b871faf2d4f",
"product": "Advanced Onboarding",
"amount": 10000,
"dateFrom": 18836
}
],
"cId": "61006bc89a3e0b702ed8ea49"
}'
Example Response
'{
"invoiceNo": 1,
"amountTotal": 10000,
"emails": [],
"status": "pending",
"_id": "61017a0372c0e0884d5e827e",
"dueDate": 19201,
"invoiceDate": 18836,
"currency": "USD",
"lineItems": [
{
"_id": "61017a0372c0e0884d5e827f",
"saleId": "61016c80675c1b871faf2d4f",
"product": "Advanced Onboarding",
"amount": 10000,
"dateFrom": 18836
}
],
"cId": "61006bc89a3e0b702ed8ea49",
"custom": {
"Sent Date": "2021-07-02T04:00:00.000Z",
"Sent": true
},
"cName": "Tenet",
"updatedAt": "2021-07-28T15:38:43.243Z",
"__v": 0
}'Create invoice
To create an invoice the only real value that is required is the cId but it doesn't make much sense to have an invoice just with a cId, that is why we suggest specifying a invoiceDate and currency.
You can instead reference the company externalId or sourceId using the following command structure: "cId": "extid-[company externalId]" or "cId": "srcid-[company sourceId]".
Example Request
curl --location -g --request POST 'https://api.planhat.com/invoices' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"dueDate": 19201,
"invoiceDate": 18836,
"currency": "USD",
"amountTotal": 10000,
"lineItems": [
{
"relatedId": "sale-61016c80675c1b871faf2d4f",
"saleId": "61016c80675c1b871faf2d4f",
"product": "Advanced Onboarding",
"amount": 10000,
"dateFrom": 18836
}
],
"cId": "61006bc89a3e0b702ed8ea49"
}'
Example Response
'{
"invoiceNo": 1,
"amountTotal": 10000,
"emails": [],
"status": "pending",
"_id": "61017a0372c0e0884d5e827e",
"dueDate": 19201,
"invoiceDate": 18836,
"currency": "USD",
"lineItems": [
{
"_id": "61017a0372c0e0884d5e827f",
"saleId": "61016c80675c1b871faf2d4f",
"product": "Advanced Onboarding",
"amount": 10000,
"dateFrom": 18836
}
],
"cId": "61006bc89a3e0b702ed8ea49",
"custom": {
"Sent Date": "2021-07-02T04:00:00.000Z",
"Sent": true
},
"cName": "Tenet",
"updatedAt": "2021-07-28T15:38:43.243Z",
"__v": 0
}'Create invoice
To create an invoice the only real value that is required is the cId but it doesn't make much sense to have an invoice just with a cId, that is why we suggest specifying a invoiceDate and currency.
You can instead reference the company externalId or sourceId using the following command structure: "cId": "extid-[company externalId]" or "cId": "srcid-[company sourceId]".
Example Request
curl --location -g --request POST 'https://api.planhat.com/invoices' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"dueDate": 19201,
"invoiceDate": 18836,
"currency": "USD",
"amountTotal": 10000,
"lineItems": [
{
"relatedId": "sale-61016c80675c1b871faf2d4f",
"saleId": "61016c80675c1b871faf2d4f",
"product": "Advanced Onboarding",
"amount": 10000,
"dateFrom": 18836
}
],
"cId": "61006bc89a3e0b702ed8ea49"
}'
Example Response
'{
"invoiceNo": 1,
"amountTotal": 10000,
"emails": [],
"status": "pending",
"_id": "61017a0372c0e0884d5e827e",
"dueDate": 19201,
"invoiceDate": 18836,
"currency": "USD",
"lineItems": [
{
"_id": "61017a0372c0e0884d5e827f",
"saleId": "61016c80675c1b871faf2d4f",
"product": "Advanced Onboarding",
"amount": 10000,
"dateFrom": 18836
}
],
"cId": "61006bc89a3e0b702ed8ea49",
"custom": {
"Sent Date": "2021-07-02T04:00:00.000Z",
"Sent": true
},
"cName": "Tenet",
"updatedAt": "2021-07-28T15:38:43.243Z",
"__v": 0
}'Update invoice
To update an invoice it's required to pass the invoice _id in the request URL as a parameter.
Alternately it’s possible to update using the invoice extId and/or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
Example Request
curl --location -g --request PUT 'https://api.planhat.com/invoices/61017a0372c0e0884d5e827e' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"paidDate": 18840
}'
Example Response
'{
"_id": "61017a0372c0e0884d5e827e",
"invoiceNo": 1,
"amountTotal": 10000,
"emails": [],
"status": "pending",
"dueDate": 19201,
"invoiceDate": 18836,
"currency": "USD",
"lineItems": [
{
"_id": "61017a0372c0e0884d5e827f",
"saleId": "61016c80675c1b871faf2d4f",
"product": "Advanced Onboarding",
"amount": 10000,
"dateFrom": 18836
}
],
"cId": "61006bc89a3e0b702ed8ea49",
"custom": {
"Sent Date": "2021-07-02T04:00:00.000Z",
"Sent": true
},
"cName": "Tenet",
"updatedAt": "2021-07-28T15:56:16.385Z",
"__v": 0,
"paidDate": 18840
}'Update invoice
To update an invoice it's required to pass the invoice _id in the request URL as a parameter.
Alternately it’s possible to update using the invoice extId and/or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
Example Request
curl --location -g --request PUT 'https://api.planhat.com/invoices/61017a0372c0e0884d5e827e' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"paidDate": 18840
}'
Example Response
'{
"_id": "61017a0372c0e0884d5e827e",
"invoiceNo": 1,
"amountTotal": 10000,
"emails": [],
"status": "pending",
"dueDate": 19201,
"invoiceDate": 18836,
"currency": "USD",
"lineItems": [
{
"_id": "61017a0372c0e0884d5e827f",
"saleId": "61016c80675c1b871faf2d4f",
"product": "Advanced Onboarding",
"amount": 10000,
"dateFrom": 18836
}
],
"cId": "61006bc89a3e0b702ed8ea49",
"custom": {
"Sent Date": "2021-07-02T04:00:00.000Z",
"Sent": true
},
"cName": "Tenet",
"updatedAt": "2021-07-28T15:56:16.385Z",
"__v": 0,
"paidDate": 18840
}'Update invoice
To update an invoice it's required to pass the invoice _id in the request URL as a parameter.
Alternately it’s possible to update using the invoice extId and/or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
Example Request
curl --location -g --request PUT 'https://api.planhat.com/invoices/61017a0372c0e0884d5e827e' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"paidDate": 18840
}'
Example Response
'{
"_id": "61017a0372c0e0884d5e827e",
"invoiceNo": 1,
"amountTotal": 10000,
"emails": [],
"status": "pending",
"dueDate": 19201,
"invoiceDate": 18836,
"currency": "USD",
"lineItems": [
{
"_id": "61017a0372c0e0884d5e827f",
"saleId": "61016c80675c1b871faf2d4f",
"product": "Advanced Onboarding",
"amount": 10000,
"dateFrom": 18836
}
],
"cId": "61006bc89a3e0b702ed8ea49",
"custom": {
"Sent Date": "2021-07-02T04:00:00.000Z",
"Sent": true
},
"cName": "Tenet",
"updatedAt": "2021-07-28T15:56:16.385Z",
"__v": 0,
"paidDate": 18840
}'Get invoices by ID
To get a specific invoice it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get an invoice using its extId and/or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
Example Request
curl --location -g --request GET 'https://api.planhat.com/invoices/5bec1521b63ce46d84dd7a7d' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"_id": "5bec1521b63ce46d84dd7a7d",
"invoiceNo": 1,
"amountDue": 226029,
"amountPaid": 226029,
"emails": [],
"status": "paid",
"cId": "598b753cc488358437483eb9",
"cName": "Alphabet Inc.",
"invoiceDate": 17752,
"dueDate": 18116,
"lineItems": [
{
"_id": "5bec1521b63ce46d84dd7a7e",
"licenseId": "5baa914c6919c0ec85106069",
"product": "License Fee",
"amount": 244864.75,
"dateFrom": 17752,
"dateTo": 18116
}
],
"__v": 0,
"paidDate": 18673,
"invoiceCycle": "once",
"custom": {
"t1": 0,
"HScore": 0,
"Days in Phase": 0,
"Sent": true,
"NRR30": 0,
"t123": "undefined",
"Logins": 0,
"Renewal in days": -1,
"Activity Count": 0,
"Week No": 29.285714285714285
},
"updatedAt": "2021-02-15T15:36:41.372Z",
"comments": [],
"amountTotal": 244864.75,
"lastUpdated": "2021-05-28T11:35:12.265Z"
}'Get invoices by ID
To get a specific invoice it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get an invoice using its extId and/or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
Example Request
curl --location -g --request GET 'https://api.planhat.com/invoices/5bec1521b63ce46d84dd7a7d' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"_id": "5bec1521b63ce46d84dd7a7d",
"invoiceNo": 1,
"amountDue": 226029,
"amountPaid": 226029,
"emails": [],
"status": "paid",
"cId": "598b753cc488358437483eb9",
"cName": "Alphabet Inc.",
"invoiceDate": 17752,
"dueDate": 18116,
"lineItems": [
{
"_id": "5bec1521b63ce46d84dd7a7e",
"licenseId": "5baa914c6919c0ec85106069",
"product": "License Fee",
"amount": 244864.75,
"dateFrom": 17752,
"dateTo": 18116
}
],
"__v": 0,
"paidDate": 18673,
"invoiceCycle": "once",
"custom": {
"t1": 0,
"HScore": 0,
"Days in Phase": 0,
"Sent": true,
"NRR30": 0,
"t123": "undefined",
"Logins": 0,
"Renewal in days": -1,
"Activity Count": 0,
"Week No": 29.285714285714285
},
"updatedAt": "2021-02-15T15:36:41.372Z",
"comments": [],
"amountTotal": 244864.75,
"lastUpdated": "2021-05-28T11:35:12.265Z"
}'Get invoices by ID
To get a specific invoice it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get an invoice using its extId and/or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
Example Request
curl --location -g --request GET 'https://api.planhat.com/invoices/5bec1521b63ce46d84dd7a7d' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"_id": "5bec1521b63ce46d84dd7a7d",
"invoiceNo": 1,
"amountDue": 226029,
"amountPaid": 226029,
"emails": [],
"status": "paid",
"cId": "598b753cc488358437483eb9",
"cName": "Alphabet Inc.",
"invoiceDate": 17752,
"dueDate": 18116,
"lineItems": [
{
"_id": "5bec1521b63ce46d84dd7a7e",
"licenseId": "5baa914c6919c0ec85106069",
"product": "License Fee",
"amount": 244864.75,
"dateFrom": 17752,
"dateTo": 18116
}
],
"__v": 0,
"paidDate": 18673,
"invoiceCycle": "once",
"custom": {
"t1": 0,
"HScore": 0,
"Days in Phase": 0,
"Sent": true,
"NRR30": 0,
"t123": "undefined",
"Logins": 0,
"Renewal in days": -1,
"Activity Count": 0,
"Week No": 29.285714285714285
},
"updatedAt": "2021-02-15T15:36:41.372Z",
"comments": [],
"amountTotal": 244864.75,
"lastUpdated": "2021-05-28T11:35:12.265Z"
}'Get invoices List
When fetching multiple invoices there are some options that can be used via query params:
companyId: Filter using company id. Multiple ids can be used separating them by commas.
limit: Limit the list length. Default as 100, max. 2000.
offset: Start the list on a specific integer index.
sort: Sort based on a specific property. Prefix the property "-" to change the sort order.
select: Select specific properties. Multiple properties can be specified separating them by commas.
Example Request
curl --location -g --request GET 'https://api.planhat.com/invoices?limit=2&offset=0&sort=-amountTotal&select=_id,product,currency,cId,amountTotal' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'[
{
"_id": "5bec1521b63ce46d84dd7a7d",
"invoiceNo": 1,
"amountDue": 226029,
"amountPaid": 226029,
"emails": [],
"status": "paid",
"cId": "598b753cc488358437483eb9",
"cName": "Alphabet Inc.",
"invoiceDate": 17752,
"dueDate": 18116,
"lineItems": [
{
"_id": "5bec1521b63ce46d84dd7a7e",
"licenseId": "5baa914c6919c0ec85106069",
"product": "License Fee",
"amount": 244864.75,
"dateFrom": 17752,
"dateTo": 18116
}
],
"__v": 0,
"paidDate": 18673,
"invoiceCycle": "once",
"custom": {
"t1": 0,
"HScore": 0,
"Days in Phase": 0,
"Sent": true,
"NRR30": 0,
"t123": "undefined",
"Logins": 0,
"Renewal in days": -1,
"Activity Count": 0,
"Week No": 29.285714285714285
},
"updatedAt": "2021-02-15T15:36:41.372Z",
"comments": [],
"amountTotal": 244864.75,
"lastUpdated": "2021-05-28T11:35:12.265Z"
},
{
"_id": "5bec958059e144aa751dd7e7",
"invoiceNo": 1,
"amountDue": 150890,
"amountPaid": 0,
"emails": [],
"status": "paid",
"dueDate": 17880,
"invoiceDate": 17850,
"currency": "USD",
"lineItems": [
{
"_id": "5bec958059e144aa751dd7e8",
"licenseId": "598b765d49c568a81b052acc",
"product": "License Fee",
"amount": 150890,
"dateFrom": 17386,
"dateTo": 17746
}
],
"cId": "598b762249c568a81b052a75",
"cName": "Amazon",
"__v": 0,
"custom": {
"t1": 0,
"HScore": 0,
"Days in Phase": 0,
"Sent": true,
"NRR30": 0,
"t123": "undefined",
"Logins": 0,
"Renewal in days": -1,
"Activity Count": 0,
"Week No": 29.285714285714285
},
"updatedAt": "2020-10-01T13:46:32.781Z",
"amountTotal": 150890,
"paidDate": 18551,
"lastUpdated": "2021-05-28T11:35:12.265Z"
}
]
Get invoices List
When fetching multiple invoices there are some options that can be used via query params:
companyId: Filter using company id. Multiple ids can be used separating them by commas.
limit: Limit the list length. Default as 100, max. 2000.
offset: Start the list on a specific integer index.
sort: Sort based on a specific property. Prefix the property "-" to change the sort order.
select: Select specific properties. Multiple properties can be specified separating them by commas.
Example Request
curl --location -g --request GET 'https://api.planhat.com/invoices?limit=2&offset=0&sort=-amountTotal&select=_id,product,currency,cId,amountTotal' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'[
{
"_id": "5bec1521b63ce46d84dd7a7d",
"invoiceNo": 1,
"amountDue": 226029,
"amountPaid": 226029,
"emails": [],
"status": "paid",
"cId": "598b753cc488358437483eb9",
"cName": "Alphabet Inc.",
"invoiceDate": 17752,
"dueDate": 18116,
"lineItems": [
{
"_id": "5bec1521b63ce46d84dd7a7e",
"licenseId": "5baa914c6919c0ec85106069",
"product": "License Fee",
"amount": 244864.75,
"dateFrom": 17752,
"dateTo": 18116
}
],
"__v": 0,
"paidDate": 18673,
"invoiceCycle": "once",
"custom": {
"t1": 0,
"HScore": 0,
"Days in Phase": 0,
"Sent": true,
"NRR30": 0,
"t123": "undefined",
"Logins": 0,
"Renewal in days": -1,
"Activity Count": 0,
"Week No": 29.285714285714285
},
"updatedAt": "2021-02-15T15:36:41.372Z",
"comments": [],
"amountTotal": 244864.75,
"lastUpdated": "2021-05-28T11:35:12.265Z"
},
{
"_id": "5bec958059e144aa751dd7e7",
"invoiceNo": 1,
"amountDue": 150890,
"amountPaid": 0,
"emails": [],
"status": "paid",
"dueDate": 17880,
"invoiceDate": 17850,
"currency": "USD",
"lineItems": [
{
"_id": "5bec958059e144aa751dd7e8",
"licenseId": "598b765d49c568a81b052acc",
"product": "License Fee",
"amount": 150890,
"dateFrom": 17386,
"dateTo": 17746
}
],
"cId": "598b762249c568a81b052a75",
"cName": "Amazon",
"__v": 0,
"custom": {
"t1": 0,
"HScore": 0,
"Days in Phase": 0,
"Sent": true,
"NRR30": 0,
"t123": "undefined",
"Logins": 0,
"Renewal in days": -1,
"Activity Count": 0,
"Week No": 29.285714285714285
},
"updatedAt": "2020-10-01T13:46:32.781Z",
"amountTotal": 150890,
"paidDate": 18551,
"lastUpdated": "2021-05-28T11:35:12.265Z"
}
]
Get invoices List
When fetching multiple invoices there are some options that can be used via query params:
companyId: Filter using company id. Multiple ids can be used separating them by commas.
limit: Limit the list length. Default as 100, max. 2000.
offset: Start the list on a specific integer index.
sort: Sort based on a specific property. Prefix the property "-" to change the sort order.
select: Select specific properties. Multiple properties can be specified separating them by commas.
Example Request
curl --location -g --request GET 'https://api.planhat.com/invoices?limit=2&offset=0&sort=-amountTotal&select=_id,product,currency,cId,amountTotal' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'[
{
"_id": "5bec1521b63ce46d84dd7a7d",
"invoiceNo": 1,
"amountDue": 226029,
"amountPaid": 226029,
"emails": [],
"status": "paid",
"cId": "598b753cc488358437483eb9",
"cName": "Alphabet Inc.",
"invoiceDate": 17752,
"dueDate": 18116,
"lineItems": [
{
"_id": "5bec1521b63ce46d84dd7a7e",
"licenseId": "5baa914c6919c0ec85106069",
"product": "License Fee",
"amount": 244864.75,
"dateFrom": 17752,
"dateTo": 18116
}
],
"__v": 0,
"paidDate": 18673,
"invoiceCycle": "once",
"custom": {
"t1": 0,
"HScore": 0,
"Days in Phase": 0,
"Sent": true,
"NRR30": 0,
"t123": "undefined",
"Logins": 0,
"Renewal in days": -1,
"Activity Count": 0,
"Week No": 29.285714285714285
},
"updatedAt": "2021-02-15T15:36:41.372Z",
"comments": [],
"amountTotal": 244864.75,
"lastUpdated": "2021-05-28T11:35:12.265Z"
},
{
"_id": "5bec958059e144aa751dd7e7",
"invoiceNo": 1,
"amountDue": 150890,
"amountPaid": 0,
"emails": [],
"status": "paid",
"dueDate": 17880,
"invoiceDate": 17850,
"currency": "USD",
"lineItems": [
{
"_id": "5bec958059e144aa751dd7e8",
"licenseId": "598b765d49c568a81b052acc",
"product": "License Fee",
"amount": 150890,
"dateFrom": 17386,
"dateTo": 17746
}
],
"cId": "598b762249c568a81b052a75",
"cName": "Amazon",
"__v": 0,
"custom": {
"t1": 0,
"HScore": 0,
"Days in Phase": 0,
"Sent": true,
"NRR30": 0,
"t123": "undefined",
"Logins": 0,
"Renewal in days": -1,
"Activity Count": 0,
"Week No": 29.285714285714285
},
"updatedAt": "2020-10-01T13:46:32.781Z",
"amountTotal": 150890,
"paidDate": 18551,
"lastUpdated": "2021-05-28T11:35:12.265Z"
}
]
Delete invoices
To delete an invoice it's required to pass the _id in the request URL as a parameter.
Invoice numbers are immutable. That means that if you have five invoices, 1, 2, 3, 4, 5, and delete the third, you will end with 1, 2, 4, 5 and the next one will be number 6.
Example Request
curl --location -g --request DELETE 'https://api.planhat.com/invoices/61017a0372c0e0884d5e827e' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'Delete invoices
To delete an invoice it's required to pass the _id in the request URL as a parameter.
Invoice numbers are immutable. That means that if you have five invoices, 1, 2, 3, 4, 5, and delete the third, you will end with 1, 2, 4, 5 and the next one will be number 6.
Example Request
curl --location -g --request DELETE 'https://api.planhat.com/invoices/61017a0372c0e0884d5e827e' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'Delete invoices
To delete an invoice it's required to pass the _id in the request URL as a parameter.
Invoice numbers are immutable. That means that if you have five invoices, 1, 2, 3, 4, 5, and delete the third, you will end with 1, 2, 4, 5 and the next one will be number 6.
Example Request
curl --location -g --request DELETE 'https://api.planhat.com/invoices/61017a0372c0e0884d5e827e' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'Bulk Upsert invoices
To create an invoice it's required to define a cId, currency, and invoiceDate.
You can instead reference the company externalId or sourceId using the following command structure: "cId": "extid-[company externalId]" or "cId": "srcid-[company sourceId]".
To update an invoice it is required to specify in the payload one of the following keyables, listed in order of priority: _id, sourceId, extId.
Since this is a bulk upsert operation it's possible to create and/or update multiple invoices with the same payload.
For more details please refer to the bulk upsert section.
Note: There is an upper limit of 5,000 items per request.
Example Request
curl --location -g --request PUT 'https://api.planhat.com/invoices' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"dueDate": 19201,
"invoiceDate": 18834,
"currency": "USD",
"amountTotal": 10000,
"lineItems": [
{
"relatedId": "sale-61016c80675c1b871faf2d4f",
"saleId": "61016c80675c1b871faf2d4f",
"product": "Advanced Onboarding",
"amount": 10000,
"dateFrom": 18836
}
],
"cId": "61006bc89a3e0b702ed8ea49"
},
{
"dueDate": 19210,
"invoiceDate": 18832,
"currency": "USD",
"amountTotal": 15000,
"lineItems": [
{
"relatedId": "sale-61016c80675c1b871faf2d4f",
"saleId": "61016c80675c1b871faf2d4f",
"product": "Advanced Onboarding",
"amount": 10000,
"dateFrom": 18836
}
],
"cId": "61006bc89a3e0b702ed8ea49"
}
]'
Example Response
'{
"created": 2,
"createdErrors": [],
"insertsKeys": [
{
"_id": "6101954772c0e0884d5e8b4f"
},
{
"_id": "6101954772c0e0884d5e8b50"
}
],
"updated": 0,
"updatedErrors": [],
"updatesKeys": [],
"nonupdates": 0,
"modified": [],
"upsertedIds": [
"6101954772c0e0884d5e8b4f",
"6101954772c0e0884d5e8b50"
],
"permissionErrors": []
}'Bulk Upsert invoices
To create an invoice it's required to define a cId, currency, and invoiceDate.
You can instead reference the company externalId or sourceId using the following command structure: "cId": "extid-[company externalId]" or "cId": "srcid-[company sourceId]".
To update an invoice it is required to specify in the payload one of the following keyables, listed in order of priority: _id, sourceId, extId.
Since this is a bulk upsert operation it's possible to create and/or update multiple invoices with the same payload.
For more details please refer to the bulk upsert section.
Note: There is an upper limit of 5,000 items per request.
Example Request
curl --location -g --request PUT 'https://api.planhat.com/invoices' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"dueDate": 19201,
"invoiceDate": 18834,
"currency": "USD",
"amountTotal": 10000,
"lineItems": [
{
"relatedId": "sale-61016c80675c1b871faf2d4f",
"saleId": "61016c80675c1b871faf2d4f",
"product": "Advanced Onboarding",
"amount": 10000,
"dateFrom": 18836
}
],
"cId": "61006bc89a3e0b702ed8ea49"
},
{
"dueDate": 19210,
"invoiceDate": 18832,
"currency": "USD",
"amountTotal": 15000,
"lineItems": [
{
"relatedId": "sale-61016c80675c1b871faf2d4f",
"saleId": "61016c80675c1b871faf2d4f",
"product": "Advanced Onboarding",
"amount": 10000,
"dateFrom": 18836
}
],
"cId": "61006bc89a3e0b702ed8ea49"
}
]'
Example Response
'{
"created": 2,
"createdErrors": [],
"insertsKeys": [
{
"_id": "6101954772c0e0884d5e8b4f"
},
{
"_id": "6101954772c0e0884d5e8b50"
}
],
"updated": 0,
"updatedErrors": [],
"updatesKeys": [],
"nonupdates": 0,
"modified": [],
"upsertedIds": [
"6101954772c0e0884d5e8b4f",
"6101954772c0e0884d5e8b50"
],
"permissionErrors": []
}'Bulk Upsert invoices
To create an invoice it's required to define a cId, currency, and invoiceDate.
You can instead reference the company externalId or sourceId using the following command structure: "cId": "extid-[company externalId]" or "cId": "srcid-[company sourceId]".
To update an invoice it is required to specify in the payload one of the following keyables, listed in order of priority: _id, sourceId, extId.
Since this is a bulk upsert operation it's possible to create and/or update multiple invoices with the same payload.
For more details please refer to the bulk upsert section.
Note: There is an upper limit of 5,000 items per request.
Example Request
curl --location -g --request PUT 'https://api.planhat.com/invoices' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"dueDate": 19201,
"invoiceDate": 18834,
"currency": "USD",
"amountTotal": 10000,
"lineItems": [
{
"relatedId": "sale-61016c80675c1b871faf2d4f",
"saleId": "61016c80675c1b871faf2d4f",
"product": "Advanced Onboarding",
"amount": 10000,
"dateFrom": 18836
}
],
"cId": "61006bc89a3e0b702ed8ea49"
},
{
"dueDate": 19210,
"invoiceDate": 18832,
"currency": "USD",
"amountTotal": 15000,
"lineItems": [
{
"relatedId": "sale-61016c80675c1b871faf2d4f",
"saleId": "61016c80675c1b871faf2d4f",
"product": "Advanced Onboarding",
"amount": 10000,
"dateFrom": 18836
}
],
"cId": "61006bc89a3e0b702ed8ea49"
}
]'
Example Response
'{
"created": 2,
"createdErrors": [],
"insertsKeys": [
{
"_id": "6101954772c0e0884d5e8b4f"
},
{
"_id": "6101954772c0e0884d5e8b50"
}
],
"updated": 0,
"updatedErrors": [],
"updatesKeys": [],
"nonupdates": 0,
"modified": [],
"upsertedIds": [
"6101954772c0e0884d5e8b4f",
"6101954772c0e0884d5e8b50"
],
"permissionErrors": []
}'