Invoices

Manage invoices and invoice items.

List invoices

GET/invoices

Retrieve a paginated list of invoices with optional filtering by status, customer, or date range.

Query parameters

limitinteger>= 1<= 1000default 100

The maximum number of items to return.

cursorstring

Opaque pagination token from a previous response's nextCursor.

customerIdarray of string

Filter invoices by customer IDs

statusarray of InvoiceStatus

Filter invoices by status

fromDatestringdate

Filter invoices created from this date

toDatestringdate

Filter invoices created up to this date

dueDateFromstringdate

Filter invoices with due date from this date

dueDateTostringdate

Filter invoices with due date up to this date

Responses

200

Invoices retrieved successfully

application/json

Invoices retrieved successfully

object

itemsarray of InvoiceListItemrequired

Show child attributes

invoiceIdstringrequired

Unique identifier for the invoice.

customerIdstringrequired

The customer this invoice is for.

invoiceNumberstringrequired

Human-readable invoice number.

statusenum<string>required

Current status of the invoice.

Current stage of the invoice lifecycle.

DRAFT: Being prepared; not yet visible to the customer.
SENT: Delivered to the customer and awaiting payment.
PAID: Payment has been received.
VOID: Canceled and no longer collectible.
OVERDUE: Past its due date without payment.

values

DRAFT
SENT
PAID
VOID
OVERDUE

dueDatestringdaterequired

When payment is due.

subtotalAmountMinorintegerint64

Sum of all line items before taxes, fees, and discounts, in minor units of the invoice currency (e.g., 2999 = $29.99 when the currency is USD).

totalAmountMinorintegerint64

Total amount the customer owes for this invoice after taxes, fees, and discounts, in minor currency units.

currencystring

The ISO 4217 currency code for all invoice amounts (e.g., "USD").

sentAtstringdate-time

When the invoice was sent to the customer (if status is sent or later).

paidAtstringdate-time

When the invoice was paid (if status is paid).

voidedAtstringdate-time

When the invoice was voided (if status is void).

invoiceUrlstringuri

Hosted URL where customer can view the invoice.

createdAtstringdate-timerequired

When the invoice was created.

updatedAtstringdate-timerequired

When the invoice was last updated.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

paginationobjectrequired

Cursor-based pagination information returned by list endpoints. Pass nextCursor as the cursor query parameter of the next request to fetch the following page.

Show child attributes

nextCursorstring | nullrequired

Opaque token for fetching the next page. Null when no more results.

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

GET /invoices

curl https://apiv2.example.com/api/v2/invoices \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'

fetch('https://apiv2.example.com/api/v2/invoices', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})

requests.get(
    "https://apiv2.example.com/api/v2/invoices",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/invoices"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

{
  "items": [
    {
      "invoiceId": "094f10ca-616e-441c-b264-9a2305d6692d",
      "customerId": "456789ab-cdef-0123-4567-89abcdef0123",
      "invoiceNumber": "INV-2024-001",
      "status": "SENT",
      "dueDate": "2024-02-15",
      "subtotalAmountMinor": 2999,
      "totalAmountMinor": 3239,
      "currency": "USD",
      "sentAt": "2024-01-15T10:00:00Z",
      "invoiceUrl": "https://invoices.yourapp.com/094f10ca-616e-441c-b264-9a2305d6692d",
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-15T10:00:00Z"
    },
    {
      "invoiceId": "123e4567-e89b-12d3-a456-426614174000",
      "customerId": "456789ab-cdef-0123-4567-89abcdef0123",
      "invoiceNumber": "INV-2024-002",
      "status": "PAID",
      "dueDate": "2024-03-15",
      "subtotalAmountMinor": 2999,
      "totalAmountMinor": 3239,
      "currency": "USD",
      "sentAt": "2024-02-15T10:00:00Z",
      "paidAt": "2024-03-10T14:30:00Z",
      "invoiceUrl": "https://invoices.yourapp.com/123e4567-e89b-12d3-a456-426614174000",
      "createdAt": "2024-02-15T10:00:00Z",
      "updatedAt": "2024-03-10T14:30:00Z"
    }
  ],
  "pagination": {
    "nextCursor": null
  }
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Get invoice

GET/invoices/{invoiceId}

Retrieve details of a specific invoice by its identifier, including status, due date, and payment information.

Path parameters

invoiceIdstringrequired

The unique identifier of the invoice to retrieve.

Responses

200

Invoice retrieved successfully

application/json

Invoice retrieved successfully

objectInvoice

An invoice with detailed line item breakdown that can be sent to customers for payment.

invoiceIdstringrequired

Unique identifier for the invoice.

customerIdstringrequired

The customer this invoice is for.

invoiceNumberstringrequired

Human-readable invoice number.

statusenum<string>required

Current status of the invoice.

Current stage of the invoice lifecycle.

DRAFT: Being prepared; not yet visible to the customer.
SENT: Delivered to the customer and awaiting payment.
PAID: Payment has been received.
VOID: Canceled and no longer collectible.
OVERDUE: Past its due date without payment.

values

DRAFT
SENT
PAID
VOID
OVERDUE

dueDatestringdaterequired

When payment is due.

lineItemsarray of InvoiceLineItemrequired

Detailed breakdown of items included in this invoice.

Show child attributes

descriptionstringrequired

Description of what this line item represents.

subscriptionIdstring

ID of the subscription this line item is associated with, if applicable.

licenseIdstring

ID of the license this line item is associated with, if applicable.

productOfferingIdstring

ID of the product offering this line item is associated with, if applicable.

quantityinteger>= 1

Quantity of items for this line item.

unitPriceMinorintegerint64

Price per unit before taxes and fees, in minor units of the invoice currency (e.g., 2999 = $29.99 when the currency is USD).

subtotalMinorintegerint64required

Line item subtotal (quantity x unitPriceMinor), in minor currency units.

totalMinorintegerint64required

Line item total after taxes, fees, and discounts, in minor currency units.

taxBreakdownarray of TaxBreakdownItem

Tax breakdown for this line item.

Show child attributes

descriptionstringrequired

Human-readable name of the tax or fee, suitable for display on invoices and receipts.

amountMinorintegerint64required

The amount charged for this tax component, in minor units of the currency of the transaction.

ratenumberdecimal

The tax rate applied, as a percentage (e.g., 8.25 for 8.25%). Omitted for flat fees that are not rate-based.

taxAmountMinorintegerint64

Total taxes for this line item, in minor currency units.

taxIncludedboolean

Whether taxes are included in the total.

feesarray of object

Detailed fee breakdown for this line item.

Show child attributes

namestringrequired

Fee name or description.

amountMinorintegerint64required

Fee amount, in minor currency units.

totalFeesMinorintegerint64

Total fees for this line item, in minor currency units.

discountsarray of object

Detailed discount breakdown for this line item.

Show child attributes

namestringrequired

Discount name or description.

amountMinorintegerint64required

Discount amount (positive value), in minor currency units.

totalDiscountsMinorintegerint64

Total discounts for this line item, in minor currency units.

subtotalAmountMinorintegerint64

Sum of all line items before taxes, fees, and discounts, in minor units of the invoice currency (e.g., 2999 = $29.99 when the currency is USD).

taxAmountMinorintegerint64

Total tax amount for the invoice, in minor currency units.

feeAmountMinorintegerint64

Total fee amount for the invoice, in minor currency units.

discountAmountMinorintegerint64

Total amount deducted by discounts (positive value), in minor currency units.

totalAmountMinorintegerint64

Total amount the customer owes for this invoice after taxes, fees, and discounts, in minor currency units.

currencystring

The ISO 4217 currency code for all invoice amounts (e.g., "USD").

sentAtstringdate-time

When the invoice was sent to the customer (if status is sent or later).

paidAtstringdate-time

When the invoice was paid (if status is paid).

voidedAtstringdate-time

When the invoice was voided (if status is void).

invoiceUrlstringuri

Hosted URL where customer can view the invoice.

createdAtstringdate-timerequired

When the invoice was created.

updatedAtstringdate-timerequired

When the invoice was last updated.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

GET /invoices/{invoiceId}

curl https://apiv2.example.com/api/v2/invoices/094f10ca-616e-441c-b264-9a2305d6692d \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'

fetch('https://apiv2.example.com/api/v2/invoices/094f10ca-616e-441c-b264-9a2305d6692d', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})

requests.get(
    "https://apiv2.example.com/api/v2/invoices/094f10ca-616e-441c-b264-9a2305d6692d",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/invoices/094f10ca-616e-441c-b264-9a2305d6692d"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

{
  "invoiceId": "123e4567-e89b-12d3-a456-426614174000",
  "customerId": "456789ab-cdef-0123-4567-89abcdef0123",
  "invoiceNumber": "INV-2024-001",
  "status": "SENT",
  "dueDate": "2024-02-15",
  "lineItems": [
    {
      "description": "Mobile subscription - Premium Plan",
      "subscriptionId": "b8174435-6378-4be5-a9f5-8b4aaadae5d4",
      "licenseId": "ffb19d4f-b3b6-4f2b-9365-dd80bdcf0a77",
      "productOfferingId": "mobile-plan-premium",
      "quantity": 1,
      "unitPriceMinor": 2999,
      "subtotalMinor": 2999,
      "totalMinor": 3739,
      "taxBreakdown": [
        {
          "description": "Sales Tax",
          "amountMinor": 240,
          "rate": 8.25
        }
      ],
      "taxAmountMinor": 240,
      "taxIncluded": false,
      "fees": [
        {
          "name": "Late payment fee",
          "amountMinor": 1000
        }
      ],
      "totalFeesMinor": 1000,
      "discounts": [
        {
          "name": "Volume discount",
          "amountMinor": 500
        }
      ],
      "totalDiscountsMinor": 500
    }
  ],
  "subtotalAmountMinor": 2999,
  "taxAmountMinor": 240,
  "feeAmountMinor": 250,
  "discountAmountMinor": 500,
  "totalAmountMinor": 2989,
  "currency": "USD",
  "sentAt": "2024-01-15T10:00:00Z",
  "paidAt": "2024-02-10T14:30:00Z",
  "voidedAt": "2024-02-05T09:00:00Z",
  "invoiceUrl": "https://invoices.yourapp.com/inv_123e4567",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:00:00Z",
  "metadata": {
    "propertyName": "string"
  }
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Mark invoice as paid

POST/invoices/{invoiceId}/mark-paid

Mark an invoice as paid when you manage your own payment processing.

Use this when you handle payment collection while Telness manages invoice generation and taxation. Only available for invoices in SENT or OVERDUE status. Triggers subscription renewals and prevents service cancellation.

Path parameters

invoiceIdstringrequired

The unique identifier of the invoice to mark as paid.

Headers

X-Idempotency-Keystringmax length 256

A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.

Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.

BodyMarkInvoiceAsPaidRequestapplication/json

Request to mark an invoice as paid when you manage your own payment processing.

paidAtstringdate-time

When the payment was received. If not provided, uses the current timestamp.

metadataobject with string keys

Metadata to attach to the invoice.

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

Responses

200

Invoice successfully marked as paid.

application/json

Invoice successfully marked as paid.

objectInvoice

An invoice with detailed line item breakdown that can be sent to customers for payment.

invoiceIdstringrequired

Unique identifier for the invoice.

customerIdstringrequired

The customer this invoice is for.

invoiceNumberstringrequired

Human-readable invoice number.

statusenum<string>required

Current status of the invoice.

Current stage of the invoice lifecycle.

DRAFT: Being prepared; not yet visible to the customer.
SENT: Delivered to the customer and awaiting payment.
PAID: Payment has been received.
VOID: Canceled and no longer collectible.
OVERDUE: Past its due date without payment.

values

DRAFT
SENT
PAID
VOID
OVERDUE

dueDatestringdaterequired

When payment is due.

lineItemsarray of InvoiceLineItemrequired

Detailed breakdown of items included in this invoice.

Show child attributes

descriptionstringrequired

Description of what this line item represents.

subscriptionIdstring

ID of the subscription this line item is associated with, if applicable.

licenseIdstring

ID of the license this line item is associated with, if applicable.

productOfferingIdstring

ID of the product offering this line item is associated with, if applicable.

quantityinteger>= 1

Quantity of items for this line item.

unitPriceMinorintegerint64

Price per unit before taxes and fees, in minor units of the invoice currency (e.g., 2999 = $29.99 when the currency is USD).

subtotalMinorintegerint64required

Line item subtotal (quantity x unitPriceMinor), in minor currency units.

totalMinorintegerint64required

Line item total after taxes, fees, and discounts, in minor currency units.

taxBreakdownarray of TaxBreakdownItem

Tax breakdown for this line item.

Show child attributes

descriptionstringrequired

Human-readable name of the tax or fee, suitable for display on invoices and receipts.

amountMinorintegerint64required

The amount charged for this tax component, in minor units of the currency of the transaction.

ratenumberdecimal

The tax rate applied, as a percentage (e.g., 8.25 for 8.25%). Omitted for flat fees that are not rate-based.

taxAmountMinorintegerint64

Total taxes for this line item, in minor currency units.

taxIncludedboolean

Whether taxes are included in the total.

feesarray of object

Detailed fee breakdown for this line item.

Show child attributes

namestringrequired

Fee name or description.

amountMinorintegerint64required

Fee amount, in minor currency units.

totalFeesMinorintegerint64

Total fees for this line item, in minor currency units.

discountsarray of object

Detailed discount breakdown for this line item.

Show child attributes

namestringrequired

Discount name or description.

amountMinorintegerint64required

Discount amount (positive value), in minor currency units.

totalDiscountsMinorintegerint64

Total discounts for this line item, in minor currency units.

subtotalAmountMinorintegerint64

Sum of all line items before taxes, fees, and discounts, in minor units of the invoice currency (e.g., 2999 = $29.99 when the currency is USD).

taxAmountMinorintegerint64

Total tax amount for the invoice, in minor currency units.

feeAmountMinorintegerint64

Total fee amount for the invoice, in minor currency units.

discountAmountMinorintegerint64

Total amount deducted by discounts (positive value), in minor currency units.

totalAmountMinorintegerint64

Total amount the customer owes for this invoice after taxes, fees, and discounts, in minor currency units.

currencystring

The ISO 4217 currency code for all invoice amounts (e.g., "USD").

sentAtstringdate-time

When the invoice was sent to the customer (if status is sent or later).

paidAtstringdate-time

When the invoice was paid (if status is paid).

voidedAtstringdate-time

When the invoice was voided (if status is void).

invoiceUrlstringuri

Hosted URL where customer can view the invoice.

createdAtstringdate-timerequired

When the invoice was created.

updatedAtstringdate-timerequired

When the invoice was last updated.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

POST /invoices/{invoiceId}/mark-paid

curl https://apiv2.example.com/api/v2/invoices/123e4567-e89b-12d3-a456-426614174000/mark-paid \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "paidAt": "2024-02-10T14:30:00Z",
  "metadata": {
    "propertyName": "string"
  }
}'

fetch('https://apiv2.example.com/api/v2/invoices/123e4567-e89b-12d3-a456-426614174000/mark-paid', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    paidAt: '2024-02-10T14:30:00Z',
    metadata: {
      propertyName: 'string'
    }
  })
})

requests.post(
    "https://apiv2.example.com/api/v2/invoices/123e4567-e89b-12d3-a456-426614174000/mark-paid",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "paidAt": "2024-02-10T14:30:00Z",
      "metadata": {
        "propertyName": "string"
      }
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/invoices/123e4567-e89b-12d3-a456-426614174000/mark-paid"

	payload := strings.NewReader(`{
  "paidAt": "2024-02-10T14:30:00Z",
  "metadata": {
    "propertyName": "string"
  }
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

{
  "invoiceId": "123e4567-e89b-12d3-a456-426614174000",
  "customerId": "456789ab-cdef-0123-4567-89abcdef0123",
  "invoiceNumber": "INV-2024-001",
  "status": "SENT",
  "dueDate": "2024-02-15",
  "lineItems": [
    {
      "description": "Mobile subscription - Premium Plan",
      "subscriptionId": "b8174435-6378-4be5-a9f5-8b4aaadae5d4",
      "licenseId": "ffb19d4f-b3b6-4f2b-9365-dd80bdcf0a77",
      "productOfferingId": "mobile-plan-premium",
      "quantity": 1,
      "unitPriceMinor": 2999,
      "subtotalMinor": 2999,
      "totalMinor": 3739,
      "taxBreakdown": [
        {
          "description": "Sales Tax",
          "amountMinor": 240,
          "rate": 8.25
        }
      ],
      "taxAmountMinor": 240,
      "taxIncluded": false,
      "fees": [
        {
          "name": "Late payment fee",
          "amountMinor": 1000
        }
      ],
      "totalFeesMinor": 1000,
      "discounts": [
        {
          "name": "Volume discount",
          "amountMinor": 500
        }
      ],
      "totalDiscountsMinor": 500
    }
  ],
  "subtotalAmountMinor": 2999,
  "taxAmountMinor": 240,
  "feeAmountMinor": 250,
  "discountAmountMinor": 500,
  "totalAmountMinor": 2989,
  "currency": "USD",
  "sentAt": "2024-01-15T10:00:00Z",
  "paidAt": "2024-02-10T14:30:00Z",
  "voidedAt": "2024-02-05T09:00:00Z",
  "invoiceUrl": "https://invoices.yourapp.com/inv_123e4567",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:00:00Z",
  "metadata": {
    "propertyName": "string"
  }
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}

{
  "message": "The request conflicts with the current state of the resource.",
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Invoices

List invoices

Query parameters

Responses

Get invoice

Path parameters

Responses

Mark invoice as paid

Path parameters

Headers

Body·MarkInvoiceAsPaidRequestapplication/json

Responses

BodyMarkInvoiceAsPaidRequestapplication/json