Find Invoices

POST

companies

{company_id}

invoices

find

Find Invoices

curl --request POST \
  --url https://api.maplebilling.com/api/v1/companies/{company_id}/invoices/find \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "pagination": {
    "from_key": "<unknown>",
    "limit": 20
  },
  "include_meta": true,
  "query": {
    "auto_charges": "<unknown>",
    "billed_customer_id": "<unknown>",
    "currency": "<unknown>",
    "customer_id": "<unknown>",
    "due": {
      "eq": "<unknown>",
      "gt": "<unknown>",
      "gte": "<unknown>",
      "lte": "<unknown>"
    },
    "due_date": {
      "eq": "<unknown>",
      "gte": "<unknown>",
      "lt": "<unknown>",
      "lte": "<unknown>"
    },
    "hide_zero": "<unknown>",
    "invoice_date": {
      "eq": "<unknown>",
      "gte": "<unknown>",
      "lt": "<unknown>",
      "lte": "<unknown>"
    },
    "invoice_number": "<unknown>",
    "invoice_sent": "<unknown>",
    "managed_externally": "<unknown>",
    "owner_ids": {
      "condition": "AND",
      "values": [
        "<string>"
      ]
    },
    "paid": {
      "eq": "<unknown>",
      "gt": "<unknown>",
      "gte": "<unknown>",
      "lte": "<unknown>"
    },
    "paid_date": {
      "eq": "<unknown>",
      "gte": "<unknown>",
      "lt": "<unknown>",
      "lte": "<unknown>"
    },
    "payment_methods": {
      "condition": "AND",
      "values": [
        "<string>"
      ]
    },
    "product_ids": {
      "condition": "AND",
      "values": [
        "<string>"
      ]
    },
    "product_pricing_ids": {
      "condition": "AND",
      "values": [
        "<string>"
      ]
    },
    "product_pricing_tags": {
      "condition": "AND",
      "values": [
        "<string>"
      ]
    },
    "product_tags": {
      "condition": "AND",
      "values": [
        "<string>"
      ]
    },
    "search": "<unknown>",
    "status": "PENDING",
    "statuses": "PENDING",
    "subscription_id": "<unknown>",
    "total": {
      "eq": "<unknown>",
      "gt": "<unknown>",
      "gte": "<unknown>",
      "lte": "<unknown>"
    },
    "uuid": "<unknown>"
  },
  "sort_key": "createdAtDesc"
}
'

{
  "pagination": {
    "from_key": "<unknown>",
    "limit": 123
  },
  "results": [
    {
      "auto_charges": true,
      "billed_customer_id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "currency": "<string>",
      "customer": {
        "address": {
          "address_line_1": "<string>",
          "address_line_2": "<string>",
          "city": "<string>",
          "country": "<string>",
          "place_id": "<unknown>",
          "state": "<string>",
          "zip": "<string>"
        },
        "arr": {
          "currency": "<string>",
          "value_in_cents": 123
        },
        "billing_emails": [
          "<string>"
        ],
        "company_id": "<string>",
        "computed_entitlements": [
          {
            "entitlement_id": "<string>",
            "id": "<string>",
            "inherited_from_id": "<unknown>",
            "inherited_from_type": "<unknown>",
            "key": "<string>",
            "name": "<string>",
            "original_value": "<unknown>",
            "overridden": "<unknown>",
            "type": "<string>",
            "value": "<unknown>"
          }
        ],
        "created_at": "2023-11-07T05:31:56Z",
        "customer_integration_metadata": {},
        "email": "<string>",
        "exclude_from_metrics": true,
        "id": "<string>",
        "identifier": "<string>",
        "integration_references": [
          {
            "integration_icon": "<string>",
            "integration_id": "<string>",
            "integration_key": "<string>",
            "integration_name": "<string>",
            "reference_type": "<string>",
            "remote_id": "<string>",
            "remote_type": "<string>"
          }
        ],
        "locale": "<string>",
        "managed_externally": true,
        "metadata": {},
        "mrr": {
          "currency": "<string>",
          "value_in_cents": 123
        },
        "name": "<string>",
        "org_name": "<string>",
        "owner_id": "<unknown>",
        "parent_customer_id": "<unknown>",
        "phone": "<string>",
        "status": "<string>",
        "title": "<string>",
        "updated_at": "2023-11-07T05:31:56Z"
      },
      "customer_id": "<string>",
      "due": {
        "currency": "<string>",
        "value_in_cents": 123
      },
      "due_date": "2023-11-07T05:31:56Z",
      "hosted_link": "<unknown>",
      "invoice_date": "2023-11-07T05:31:56Z",
      "name": "<string>",
      "number": "<string>",
      "paid": {
        "currency": "<string>",
        "value_in_cents": 123
      },
      "paid_date": "<unknown>",
      "pdf_link": "<unknown>",
      "prorated_amount": {
        "currency": "<string>",
        "value_in_cents": 123
      },
      "status": "<string>",
      "sub_total": {
        "currency": "<string>",
        "value_in_cents": 123
      },
      "subscription_id": "<unknown>",
      "total": {
        "currency": "<string>",
        "value_in_cents": 123
      },
      "updated_at": "2023-11-07T05:31:56Z",
      "uuid": "<string>"
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key

string

The idempotency key that will be used to ensure the request is only performed once

Path Parameters

company_id

string

required

The company ID with the prefix 'cmp_'.

Body

application/json

pagination

object

required

The pagination parameters for the request

Show child attributes

pagination.from_key

null | string

pagination.limit

integer<int64>

default:20

Required range: 0 <= x <= 200

include_meta

boolean | null

Whether to include additional metadata in the pagination response such the number of total results

query

object

The find criteria for the invoice

Show child attributes

query.auto_charges

null | boolean

Whether the invoice is set to auto charge

query.billed_customer_id

null | string

The customer the invoices are billed to

query.currency

null | string

The currency of the invoice

query.customer_id

null | string

The customer for the invoice

query.due

object

Filter based on due amount ranges

Show child attributes

query.due.eq

null | number

Equal to

query.due.gt

null | number

Greater than

query.due.gte

null | number

Greater than or equal to

query.due.lte

null | number

Less than or equal to

query.due_date

object

The due date range of the invoice

Show child attributes

query.due_date.eq

null | string<date-time>

Equal to the specific time

query.due_date.gte

null | string<date-time>

On or after the specific time

query.due_date.lt

null | string<date-time>

Before the specific time

query.due_date.lte

null | string<date-time>

On or before the specific time

query.hide_zero

null | boolean

Whether to hide zero invoices

query.invoice_date

object

The invoice date range of the invoice

Show child attributes

query.invoice_date.eq

null | string<date-time>

Equal to the specific time

query.invoice_date.gte

null | string<date-time>

On or after the specific time

query.invoice_date.lt

null | string<date-time>

Before the specific time

query.invoice_date.lte

null | string<date-time>

On or before the specific time

query.invoice_number

null | string

The invoice number to match invoices

query.invoice_sent

null | boolean

Whether the invoice was sent to the customer via email

query.managed_externally

null | boolean

Whether the invoice was originally generated and is managed outside of Maple

query.owner_ids

object

Show child attributes

query.owner_ids.condition

enum<string>

required

Available options:

AND,

OR

query.owner_ids.values

string[]

required

query.paid

object

Filter based on paid amount ranges

Show child attributes

query.paid.eq

null | number

Equal to

query.paid.gt

null | number

Greater than

query.paid.gte

null | number

Greater than or equal to

query.paid.lte

null | number

Less than or equal to

query.paid_date

object

The paid date range of the invoice

Show child attributes

query.paid_date.eq

null | string<date-time>

Equal to the specific time

query.paid_date.gte

null | string<date-time>

On or after the specific time

query.paid_date.lt

null | string<date-time>

Before the specific time

query.paid_date.lte

null | string<date-time>

On or before the specific time

query.payment_methods

object

Filter based on payment methods

Show child attributes

query.payment_methods.condition

enum<string>

required

Available options:

AND,

OR

query.payment_methods.values

string[]

required

query.product_ids

object

Filter based on product ID ranges

Show child attributes

query.product_ids.condition

enum<string>

required

Available options:

AND,

OR

query.product_ids.values

string[]

required

query.product_pricing_ids

object

Filter based on product pricing ID ranges

Show child attributes

query.product_pricing_ids.condition

enum<string>

required

Available options:

AND,

OR

query.product_pricing_ids.values

string[]

required

query.product_pricing_tags

object

Filter based on product pricing tags

Show child attributes

query.product_pricing_tags.condition

enum<string>

required

Available options:

AND,

OR

query.product_pricing_tags.values

string[]

required

query.product_tags

object

Filter based on product tags

Show child attributes

query.product_tags.condition

enum<string>

required

Available options:

AND,

OR

query.product_tags.values

string[]

required

query.search

null | string

Any search string to match invoices

query.status

null | enum<string>

The specific status of the invoice can be one of PENDING, OVERDUE, PAID, VOID or DRAFT

Available options:

PENDING,

OVERDUE,

PAID,

VOID,

DRAFT,

PAYMENT_PROCESSING

query.statuses

string[] | null

The status of the subscriptions can include PENDING, OVERDUE, PAID, VOID and DRAFT

query.subscription_id

null | string

The subscription ID to which invoices are tied

query.total

object

Filter based on total amount ranges

Show child attributes

query.total.eq

null | number

Equal to

query.total.gt

null | number

Greater than

query.total.gte

null | number

Greater than or equal to

query.total.lte

null | number

Less than or equal to

query.uuid

null | string

The exact UUID of the invoice

sort_key

enum<string>

default:createdAtDesc

Available options:

createdAtDesc,

createdAtAsc,

updatedAtAsc,

updatedAtDesc,

aToZ,

zToA,

invoiceDateAsc,

invoiceDateDesc,

dueDateAsc,

dueDateDesc,

totalAmountAsc,

totalAmountDesc

Response

200 - application/json

pagination

object

Show child attributes

pagination.from_key

null | string

pagination.limit

integer<int64>

results

object[] | null

Show child attributes

results.auto_charges

boolean

Whether the invoice is automatically charged to the payment method on file for the customer

results.billed_customer_id

string

The billed customer ID for the invoice. This matches the customer_id by default, but can be set to another parent customer ID

results.created_at

string<date-time>

The date the invoice was created

results.currency

string

The currency of the invoice

results.customer

object

The expanded customer details for the invoice

Show child attributes

results.customer.address

object

The address of the customer

Show child attributes

results.customer.address.address_line_1

string

results.customer.address.address_line_2

string

results.customer.address.city

string

results.customer.address.country

string

2-character country code (ISO 3166-1 alpha-2)

results.customer.address.place_id

null | string

results.customer.address.state

string

results.customer.address.zip

string

results.customer.arr

object

The ARR of the customer

Show child attributes

results.customer.arr.currency

string

results.customer.arr.value_in_cents

integer<int64>

results.customer.billing_emails

string[] | null

The additional emails to cc on customer's invoices

results.customer.company_id

string

The company ID of the customer

results.customer.computed_entitlements

object[] | null

The computed entitlements for the customer

Show child attributes

results.customer.computed_entitlements.entitlement_id

string

results.customer.computed_entitlements.id

string

results.customer.computed_entitlements.inherited_from_id

null | string

results.customer.computed_entitlements.inherited_from_type

null | string

results.customer.computed_entitlements.key

string

results.customer.computed_entitlements.name

string

results.customer.computed_entitlements.original_value

any

results.customer.computed_entitlements.overridden

null | boolean

results.customer.computed_entitlements.type

string

results.customer.computed_entitlements.value

any

results.customer.created_at

string<date-time>

The date the customer was created

results.customer.customer_integration_metadata

object

Show child attributes

results.customer.customer_integration_metadata.{key}

object

Show child attributes

results.customer.customer_integration_metadata.{key}.avalara

object

Show child attributes

results.customer.customer_integration_metadata.{key}.avalara.entity_code

string

results.customer.email

string

The email of the customer

results.customer.exclude_from_metrics

boolean

Whether to exclude this customer and related fields from any metrics in Maple

results.customer.id

string

The ID of the customer in Maple

results.customer.identifier

string

The unique identifier for the customer that ties back to your system. You can query for a customer using this identifier

results.customer.integration_references

object[]

The integration references of this customer in third-party applications connected to Maple

Show child attributes

results.customer.integration_references.integration_icon

string

results.customer.integration_references.integration_id

string

results.customer.integration_references.integration_key

string

results.customer.integration_references.integration_name

string

results.customer.integration_references.reference_type

string

results.customer.integration_references.remote_id

string

results.customer.integration_references.remote_type

string

results.customer.locale

string

The locale of the customer

results.customer.managed_externally

boolean

Whether this customer is managed outside of Maple

results.customer.metadata

object

The metadata as key-value pairs attached to this customer

results.customer.mrr

object

The MRR of the customer

Show child attributes

results.customer.mrr.currency

string

results.customer.mrr.value_in_cents

integer<int64>

results.customer.name

string

The name of the customer

results.customer.org_name

string

The name of the company or the organization this customer is a part of

results.customer.owner_id

null | string

The company user ID of person in Maple assigned to manage this customer

results.customer.parent_customer_id

null | string

The customer ID of the parent customer assigned in Maple

results.customer.phone

string

The phone number of the customer

results.customer.status

string

The status of the customer such as ACTIVE or ARCHIVED

results.customer.title

string

The title of the customer, such as CEO, VP

results.customer.updated_at

string<date-time>

The date the customer was last updated

results.customer_id

string

The customer ID for the invoice

results.due

object

The total amount due on the invoice after any payments

Show child attributes

results.due.currency

string

results.due.value_in_cents

integer<int64>

results.due_date

string<date-time>

The date the invoice total is due

results.hosted_link

null | string

The hosted link for the invoice

results.invoice_date

string<date-time>

The date for the invoice

results.name

string

The name of the invoice

results.number

string

The invoice number for the invoice

results.paid

object

The total amount paid against the invoice

Show child attributes

results.paid.currency

string

results.paid.value_in_cents

integer<int64>

results.paid_date

null | string<date-time>

The date the invoice was paid

results.pdf_link

null | string

The PDF link for the invoice

results.prorated_amount

object

Any prorated amounts for the invoice

Show child attributes

results.prorated_amount.currency

string

results.prorated_amount.value_in_cents

integer<int64>

results.status

string

The status of the invoice such as PAID, DRAFT, VOID or PENDING

results.sub_total

object

The subtotal of the invoice which is prior to applying credits

Show child attributes

results.sub_total.currency

string

results.sub_total.value_in_cents

integer<int64>

results.subscription_id

null | string

The subscription ID for the invoice, if is not a one-time invoice

results.total

object

The final total of the invoice after applying all credits, discounts and taxes

Show child attributes

results.total.currency

string

results.total.value_in_cents

integer<int64>

results.updated_at

string<date-time>

The last date the invoice was updated

results.uuid

string

The unique identifier for the invoice

Next InvoiceRetrieve the upcoming invoice for the given subscription including any upcoming one time charges.

⌘I

Find Invoices

curl --request POST \
  --url https://api.maplebilling.com/api/v1/companies/{company_id}/invoices/find \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "pagination": {
    "from_key": "<unknown>",
    "limit": 20
  },
  "include_meta": true,
  "query": {
    "auto_charges": "<unknown>",
    "billed_customer_id": "<unknown>",
    "currency": "<unknown>",
    "customer_id": "<unknown>",
    "due": {
      "eq": "<unknown>",
      "gt": "<unknown>",
      "gte": "<unknown>",
      "lte": "<unknown>"
    },
    "due_date": {
      "eq": "<unknown>",
      "gte": "<unknown>",
      "lt": "<unknown>",
      "lte": "<unknown>"
    },
    "hide_zero": "<unknown>",
    "invoice_date": {
      "eq": "<unknown>",
      "gte": "<unknown>",
      "lt": "<unknown>",
      "lte": "<unknown>"
    },
    "invoice_number": "<unknown>",
    "invoice_sent": "<unknown>",
    "managed_externally": "<unknown>",
    "owner_ids": {
      "condition": "AND",
      "values": [
        "<string>"
      ]
    },
    "paid": {
      "eq": "<unknown>",
      "gt": "<unknown>",
      "gte": "<unknown>",
      "lte": "<unknown>"
    },
    "paid_date": {
      "eq": "<unknown>",
      "gte": "<unknown>",
      "lt": "<unknown>",
      "lte": "<unknown>"
    },
    "payment_methods": {
      "condition": "AND",
      "values": [
        "<string>"
      ]
    },
    "product_ids": {
      "condition": "AND",
      "values": [
        "<string>"
      ]
    },
    "product_pricing_ids": {
      "condition": "AND",
      "values": [
        "<string>"
      ]
    },
    "product_pricing_tags": {
      "condition": "AND",
      "values": [
        "<string>"
      ]
    },
    "product_tags": {
      "condition": "AND",
      "values": [
        "<string>"
      ]
    },
    "search": "<unknown>",
    "status": "PENDING",
    "statuses": "PENDING",
    "subscription_id": "<unknown>",
    "total": {
      "eq": "<unknown>",
      "gt": "<unknown>",
      "gte": "<unknown>",
      "lte": "<unknown>"
    },
    "uuid": "<unknown>"
  },
  "sort_key": "createdAtDesc"
}
'

{
  "pagination": {
    "from_key": "<unknown>",
    "limit": 123
  },
  "results": [
    {
      "auto_charges": true,
      "billed_customer_id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "currency": "<string>",
      "customer": {
        "address": {
          "address_line_1": "<string>",
          "address_line_2": "<string>",
          "city": "<string>",
          "country": "<string>",
          "place_id": "<unknown>",
          "state": "<string>",
          "zip": "<string>"
        },
        "arr": {
          "currency": "<string>",
          "value_in_cents": 123
        },
        "billing_emails": [
          "<string>"
        ],
        "company_id": "<string>",
        "computed_entitlements": [
          {
            "entitlement_id": "<string>",
            "id": "<string>",
            "inherited_from_id": "<unknown>",
            "inherited_from_type": "<unknown>",
            "key": "<string>",
            "name": "<string>",
            "original_value": "<unknown>",
            "overridden": "<unknown>",
            "type": "<string>",
            "value": "<unknown>"
          }
        ],
        "created_at": "2023-11-07T05:31:56Z",
        "customer_integration_metadata": {},
        "email": "<string>",
        "exclude_from_metrics": true,
        "id": "<string>",
        "identifier": "<string>",
        "integration_references": [
          {
            "integration_icon": "<string>",
            "integration_id": "<string>",
            "integration_key": "<string>",
            "integration_name": "<string>",
            "reference_type": "<string>",
            "remote_id": "<string>",
            "remote_type": "<string>"
          }
        ],
        "locale": "<string>",
        "managed_externally": true,
        "metadata": {},
        "mrr": {
          "currency": "<string>",
          "value_in_cents": 123
        },
        "name": "<string>",
        "org_name": "<string>",
        "owner_id": "<unknown>",
        "parent_customer_id": "<unknown>",
        "phone": "<string>",
        "status": "<string>",
        "title": "<string>",
        "updated_at": "2023-11-07T05:31:56Z"
      },
      "customer_id": "<string>",
      "due": {
        "currency": "<string>",
        "value_in_cents": 123
      },
      "due_date": "2023-11-07T05:31:56Z",
      "hosted_link": "<unknown>",
      "invoice_date": "2023-11-07T05:31:56Z",
      "name": "<string>",
      "number": "<string>",
      "paid": {
        "currency": "<string>",
        "value_in_cents": 123
      },
      "paid_date": "<unknown>",
      "pdf_link": "<unknown>",
      "prorated_amount": {
        "currency": "<string>",
        "value_in_cents": 123
      },
      "status": "<string>",
      "sub_total": {
        "currency": "<string>",
        "value_in_cents": 123
      },
      "subscription_id": "<unknown>",
      "total": {
        "currency": "<string>",
        "value_in_cents": 123
      },
      "updated_at": "2023-11-07T05:31:56Z",
      "uuid": "<string>"
    }
  ]
}

API Features

API Reference

Webhook Reference

Authorizations

Headers

Path Parameters

Body

Response