Valdyr
View as MarkdownOpen in ClaudeOpen in ChatGPT

Invoices

Inspect invoice payments and their provider lifecycle.

List invoices

GET/invoices

Retrieve invoices visible to the caller, newest first.

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 ID. When omitted, all customers visible to the caller are included.

statusarray of InvoiceStatus

Filter invoices by status.

fromDatestringdate

Include invoices created on or after this date.

toDatestringdate

Include invoices created on or before this date.

dueDateFromstringdate

Include invoices due on or after this date.

dueDateTostringdate

Include invoices due on or before 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 collects payment from.

numberstring

The provider's human-readable invoice number or payment reference. Absent until the provider assigns one.

invoiceNumberstringdeprecatedrequired

Deprecated. Read number instead.

statusenum<string>required

Current status of the invoice.

Current stage of the invoice lifecycle.

  • UNKNOWN: The provider status could not be mapped.
  • DRAFT: The invoice has not been issued.
  • ISSUED: The provider issued the invoice and it is awaiting payment.
  • SENT: Deprecated alias accepted in status filters. Responses use ISSUED.
  • PARTIALLY_PAID: Some, but not all, of the amount due has been paid.
  • PAID: The invoice has been paid.
  • OVERDUE: The invoice is past its due date and remains unpaid.
  • UNCOLLECTIBLE: The provider no longer expects to collect the invoice.
  • VOID: The invoice was canceled and is no longer collectible.
  • CREDITED: The invoice was settled by credit.

values

  • UNKNOWN
  • DRAFT
  • ISSUED
  • SENT
  • PARTIALLY_PAID
  • PAID
  • OVERDUE
  • UNCOLLECTIBLE
  • VOID
  • CREDITED
paymentProviderenum<string>

The provider that issued and manages the invoice.

Payment service provider that processes the transaction.

values

  • STRIPE
  • BILLOGRAM
dueDatestringdaterequired

The date payment is due. Absent when the provider has no due date.

subtotalAmountMinorintegerint64deprecated

Deprecated. Get the invoice and read its related payment intent instead.

totalAmountMinorintegerint64deprecated

Deprecated. Read amountDueMinor instead.

amountDueMinorintegerint64required

The amount due when the invoice was issued, in minor units of the invoice currency.

amountPaidMinorintegerint64required

The amount credited to the invoice, in minor units of the invoice currency.

amountRemainingMinorintegerint64required

The amount still unpaid, in minor units of the invoice currency.

currencystringrequired

The ISO 4217 currency code for the invoice amounts.

issuedAtstringdate-time

When the provider issued the invoice. Absent while the invoice is a draft.

sentAtstringdate-timedeprecated

Deprecated. Read issuedAt instead.

paidAtstringdate-time

When the invoice became paid.

voidedAtstringdate-time

When the invoice was voided.

hostedUrlstringuri

The provider-hosted page where the customer can view and pay the invoice.

invoiceUrlstringurideprecated

Deprecated. Read hostedUrl instead.

pdfUrlstringuri

Direct URL to the provider-generated invoice PDF.

createdAtstringdate-timerequired

When the invoice record was created.

updatedAtstringdate-timerequired

When the invoice record was last updated.

metadataobject with string keysdeprecated

Deprecated. Invoice metadata is not stored by the platform.

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": [
    {
      "amountDueMinor": 3239,
      "amountPaidMinor": 0,
      "amountRemainingMinor": 3239,
      "createdAt": "2026-08-01T08:00:00Z",
      "currency": "USD",
      "customerId": "456789ab-cdef-0123-4567-89abcdef0123",
      "dueDate": "2026-08-31",
      "hostedUrl": "https://example.com/invoices/094f10ca-616e-441c-b264-9a2305d6692d",
      "invoiceId": "094f10ca-616e-441c-b264-9a2305d6692d",
      "invoiceNumber": "INV-2026-001",
      "invoiceUrl": "https://example.com/invoices/094f10ca-616e-441c-b264-9a2305d6692d",
      "issuedAt": "2026-08-01T08:00:00Z",
      "number": "INV-2026-001",
      "paymentProvider": "STRIPE",
      "pdfUrl": "https://example.com/invoices/094f10ca-616e-441c-b264-9a2305d6692d.pdf",
      "sentAt": "2026-08-01T08:00:00Z",
      "status": "OVERDUE",
      "totalAmountMinor": 3239,
      "updatedAt": "2026-08-01T08:00: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 an invoice's provider-backed lifecycle and balances, together with its related payment intent when available.

Path parameters

invoiceIdstringrequired

The unique identifier of the invoice to retrieve.

Responses

200

Invoice retrieved successfully

application/json

Invoice retrieved successfully

objectInvoice

An invoice used to collect a payment from a customer. The invoice records the provider's invoice lifecycle and balances; the related payment intent records what is being collected, its payment attempts, and any refunds.

invoiceIdstringrequired

Unique identifier for the invoice.

customerIdstringrequired

The customer this invoice collects payment from.

numberstring

The provider's human-readable invoice number or payment reference. Absent until the provider assigns one.

lineItemsarray of InvoiceLineItemdeprecatedrequired

Deprecated. Read paymentIntent.lineItems instead.

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.

invoiceNumberstringdeprecatedrequired

Deprecated. Read number instead.

statusenum<string>required

Current status of the invoice.

Current stage of the invoice lifecycle.

  • UNKNOWN: The provider status could not be mapped.
  • DRAFT: The invoice has not been issued.
  • ISSUED: The provider issued the invoice and it is awaiting payment.
  • SENT: Deprecated alias accepted in status filters. Responses use ISSUED.
  • PARTIALLY_PAID: Some, but not all, of the amount due has been paid.
  • PAID: The invoice has been paid.
  • OVERDUE: The invoice is past its due date and remains unpaid.
  • UNCOLLECTIBLE: The provider no longer expects to collect the invoice.
  • VOID: The invoice was canceled and is no longer collectible.
  • CREDITED: The invoice was settled by credit.

values

  • UNKNOWN
  • DRAFT
  • ISSUED
  • SENT
  • PARTIALLY_PAID
  • PAID
  • OVERDUE
  • UNCOLLECTIBLE
  • VOID
  • CREDITED
paymentProviderenum<string>

The provider that issued and manages the invoice.

Payment service provider that processes the transaction.

values

  • STRIPE
  • BILLOGRAM
paymentIntentobject

The payment intent associated with this invoice, including payment attempts and refunds. This field is absent for invoices that do not have a related payment intent.

The amount the platform is collecting from a customer, with its payment attempts, refunds, and billed line items.

A payment intent is created automatically when payment collection starts for an order or invoice; you do not create one directly. Read it to see what is due, what was attempted, and what was refunded. Card collection starts through a payment session or payment link; invoice collection creates the payment intent as part of issuing the invoice.

Show child attributes
paymentIntentIdstringrequired

The unique identifier for this payment intent.

customerIdstringrequired

The customer this payment intent collects from.

statusenum<string>required

Current stage of a payment intent as it is collected through the payment provider.

  • UNKNOWN: The platform has no supported mapping for the current provider state.
  • PENDING: Created, no charge attempted yet.
  • REQUIRES_ACTION: The customer must take action to continue (e.g., 3D Secure authentication).
  • PROCESSING: A charge is in flight with the payment provider.
  • SUCCEEDED: The full amount has been collected.
  • REQUIRES_PAYMENT_METHOD: The last charge attempt failed; a new or updated payment method is needed to retry.
  • CANCELED: Collection was canceled and no further charges will be attempted.

values

  • UNKNOWN
  • PENDING
  • REQUIRES_ACTION
  • PROCESSING
  • SUCCEEDED
  • REQUIRES_PAYMENT_METHOD
  • CANCELED
amountMinorintegerint64required

The total amount to collect, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).

currencystringrequired

The ISO 4217 currency code the amount is collected in (e.g., "USD").

descriptionstring

A human-readable description of what is being collected.

dueAtstringdate-time

When the amount is due.

lineItemsarray of PaymentIntentLineItemrequired

The items that make up the collected amount.

Show child attributes
descriptionstringrequired

What this line item represents.

amountMinorintegerint64required

The base cost of the line item before discounts, in minor units of the payment intent's currency (e.g., 2900 = $29.00 when the currency is USD). The taxes are added to it, unless includesTax is true and they are a part of it.

includesTaxboolean

Whether the taxes are a part of amountMinor rather than added to it.

subscriptionIdstring

The subscription this line item is associated with, if any.

licenseIdstring

The license this line item is associated with, if any.

discountsarray of object

Discounts applied to this line item.

Show child attributes
taxesarray of object

Taxes applied to this line item.

Show child attributes
discountsarray of PaymentIntentDiscountrequired

Reductions applied to the payment intent as a whole rather than to one billed line.

Show child attributes
descriptionstringrequired

Why the payment intent was reduced.

amountMinorintegerint64required

The positive amount deducted, in minor units of the payment intent currency.

attemptsarray of PaymentAttemptrequired

Charge attempts made against this payment intent, most recent first.

Show child attributes
paymentAttemptIdstringrequired

The unique identifier for this charge attempt.

amountMinorintegerint64required

The amount charged in this attempt, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).

currencystringrequired

The ISO 4217 currency code the attempt was charged in (e.g., "USD").

resultenum<string>required

Whether the charge attempt succeeded or failed.

values

  • SUCCEEDED
  • FAILED
reasonstring

Failure reason when the attempt did not succeed.

chargedAtstringdate-time

When the charge was made.

createdAtstringdate-timerequired

When the attempt was created.

refundsarray of PaymentRefundrequired

Refunds issued against this payment intent.

Show child attributes
refundIdstringrequired

The unique identifier for this refund.

amountMinorintegerint64required

The refunded amount, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).

currencystringrequired

The ISO 4217 currency code the refund is issued in (e.g., "USD").

reasonenum<string>

Why the refund was issued.

values

  • UNKNOWN
  • DUPLICATE
  • FRAUDULENT
  • REQUESTED_BY_CUSTOMER
  • DISPUTE_LOST
statusenum<string>required

Current stage of the refund.

values

  • PENDING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • REQUIRES_ACTION
createdAtstringdate-timerequired

When the refund was created.

createdAtstringdate-timerequired

When the payment intent was created.

updatedAtstringdate-timerequired

When the payment intent was last updated.

dueDatestringdaterequired

The date payment is due. Absent when the provider has no due date.

subtotalAmountMinorintegerint64deprecated

Deprecated. Read the related payment intent's line items instead.

taxAmountMinorintegerint64deprecated

Deprecated. Read the related payment intent's line-item taxes instead.

feeAmountMinorintegerint64deprecated

Deprecated. The invoice projection has no separate fee total.

discountAmountMinorintegerint64deprecated

Deprecated. Read the related payment intent's line-item discounts instead.

totalAmountMinorintegerint64deprecated

Deprecated. Read amountDueMinor instead.

amountDueMinorintegerint64required

The amount due when the invoice was issued, in minor units of the invoice currency.

amountPaidMinorintegerint64required

The amount credited to the invoice, in minor units of the invoice currency.

amountRemainingMinorintegerint64required

The amount still unpaid, in minor units of the invoice currency.

currencystringrequired

The ISO 4217 currency code for the invoice amounts.

issuedAtstringdate-time

When the provider issued the invoice. Absent while the invoice is a draft.

sentAtstringdate-timedeprecated

Deprecated. Read issuedAt instead.

paidAtstringdate-time

When the invoice became paid.

voidedAtstringdate-time

When the invoice was voided.

hostedUrlstringuri

The provider-hosted page where the customer can view and pay the invoice.

invoiceUrlstringurideprecated

Deprecated. Read hostedUrl instead.

pdfUrlstringuri

Direct URL to the provider-generated invoice PDF.

createdAtstringdate-timerequired

When the invoice record was created.

updatedAtstringdate-timerequired

When the invoice record was last updated.

metadataobject with string keysdeprecated

Deprecated. Invoice metadata is not stored by the platform.

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",
  "number": "INV-2026-001",
  "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
    }
  ],
  "invoiceNumber": "string",
  "status": "UNKNOWN",
  "paymentProvider": "STRIPE",
  "paymentIntent": {
    "paymentIntentId": "64870b5c-fb61-4c9a-955a-e148e0826c20",
    "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "status": "SUCCEEDED",
    "amountMinor": 2900,
    "currency": "USD",
    "description": "Mobile subscription renewal",
    "dueAt": "2024-01-15T10:00:00Z",
    "lineItems": [
      {
        "description": "Mobile subscription - Premium Plan",
        "amountMinor": 2900,
        "includesTax": false,
        "subscriptionId": "a8174435-6378-4be5-a9f5-8b4aaadae5d4",
        "licenseId": "ffb19d4f-b3b6-4f2b-9365-dd80bdcf0a77",
        "discounts": [
          {
            "description": "Loyalty discount",
            "amountMinor": 500
          }
        ],
        "taxes": [
          {
            "description": "VAT 25%",
            "amountMinor": 725
          }
        ]
      }
    ],
    "discounts": [
      {
        "description": "Goodwill credit",
        "amountMinor": 1000
      }
    ],
    "attempts": [
      {
        "paymentAttemptId": "a4da2b04-aa79-4b40-8987-048d6caf118f",
        "amountMinor": 2900,
        "currency": "USD",
        "result": "SUCCEEDED",
        "reason": "card_declined",
        "chargedAt": "2024-01-15T10:00:00Z",
        "createdAt": "2024-01-15T10:00:00Z"
      }
    ],
    "refunds": [
      {
        "refundId": "c014b666-22e4-430e-bb18-9257a383dfe2",
        "amountMinor": 2900,
        "currency": "USD",
        "reason": "REQUESTED_BY_CUSTOMER",
        "status": "SUCCEEDED",
        "createdAt": "2024-01-15T10:00:00Z"
      }
    ],
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-01-15T10:00:00Z"
  },
  "dueDate": "2026-08-31",
  "subtotalAmountMinor": 1,
  "taxAmountMinor": 1,
  "feeAmountMinor": 1,
  "discountAmountMinor": 1,
  "totalAmountMinor": 1,
  "amountDueMinor": 3239,
  "amountPaidMinor": 0,
  "amountRemainingMinor": 3239,
  "currency": "USD",
  "issuedAt": "2026-08-01T08:00:00Z",
  "sentAt": "2024-01-15T10:30:00Z",
  "paidAt": "2026-08-20T14:30:00Z",
  "voidedAt": "2026-08-10T09:00:00Z",
  "hostedUrl": "https://example.com/invoices/123e4567-e89b-12d3-a456-426614174000",
  "invoiceUrl": "https://example.com/resource",
  "pdfUrl": "https://example.com/invoices/123e4567-e89b-12d3-a456-426614174000.pdf",
  "createdAt": "2026-08-01T08:00:00Z",
  "updatedAt": "2026-08-01T08: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 used to collect a payment from a customer. The invoice records the provider's invoice lifecycle and balances; the related payment intent records what is being collected, its payment attempts, and any refunds.

invoiceIdstringrequired

Unique identifier for the invoice.

customerIdstringrequired

The customer this invoice collects payment from.

numberstring

The provider's human-readable invoice number or payment reference. Absent until the provider assigns one.

lineItemsarray of InvoiceLineItemdeprecatedrequired

Deprecated. Read paymentIntent.lineItems instead.

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.

invoiceNumberstringdeprecatedrequired

Deprecated. Read number instead.

statusenum<string>required

Current status of the invoice.

Current stage of the invoice lifecycle.

  • UNKNOWN: The provider status could not be mapped.
  • DRAFT: The invoice has not been issued.
  • ISSUED: The provider issued the invoice and it is awaiting payment.
  • SENT: Deprecated alias accepted in status filters. Responses use ISSUED.
  • PARTIALLY_PAID: Some, but not all, of the amount due has been paid.
  • PAID: The invoice has been paid.
  • OVERDUE: The invoice is past its due date and remains unpaid.
  • UNCOLLECTIBLE: The provider no longer expects to collect the invoice.
  • VOID: The invoice was canceled and is no longer collectible.
  • CREDITED: The invoice was settled by credit.

values

  • UNKNOWN
  • DRAFT
  • ISSUED
  • SENT
  • PARTIALLY_PAID
  • PAID
  • OVERDUE
  • UNCOLLECTIBLE
  • VOID
  • CREDITED
paymentProviderenum<string>

The provider that issued and manages the invoice.

Payment service provider that processes the transaction.

values

  • STRIPE
  • BILLOGRAM
paymentIntentobject

The payment intent associated with this invoice, including payment attempts and refunds. This field is absent for invoices that do not have a related payment intent.

The amount the platform is collecting from a customer, with its payment attempts, refunds, and billed line items.

A payment intent is created automatically when payment collection starts for an order or invoice; you do not create one directly. Read it to see what is due, what was attempted, and what was refunded. Card collection starts through a payment session or payment link; invoice collection creates the payment intent as part of issuing the invoice.

Show child attributes
paymentIntentIdstringrequired

The unique identifier for this payment intent.

customerIdstringrequired

The customer this payment intent collects from.

statusenum<string>required

Current stage of a payment intent as it is collected through the payment provider.

  • UNKNOWN: The platform has no supported mapping for the current provider state.
  • PENDING: Created, no charge attempted yet.
  • REQUIRES_ACTION: The customer must take action to continue (e.g., 3D Secure authentication).
  • PROCESSING: A charge is in flight with the payment provider.
  • SUCCEEDED: The full amount has been collected.
  • REQUIRES_PAYMENT_METHOD: The last charge attempt failed; a new or updated payment method is needed to retry.
  • CANCELED: Collection was canceled and no further charges will be attempted.

values

  • UNKNOWN
  • PENDING
  • REQUIRES_ACTION
  • PROCESSING
  • SUCCEEDED
  • REQUIRES_PAYMENT_METHOD
  • CANCELED
amountMinorintegerint64required

The total amount to collect, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).

currencystringrequired

The ISO 4217 currency code the amount is collected in (e.g., "USD").

descriptionstring

A human-readable description of what is being collected.

dueAtstringdate-time

When the amount is due.

lineItemsarray of PaymentIntentLineItemrequired

The items that make up the collected amount.

Show child attributes
descriptionstringrequired

What this line item represents.

amountMinorintegerint64required

The base cost of the line item before discounts, in minor units of the payment intent's currency (e.g., 2900 = $29.00 when the currency is USD). The taxes are added to it, unless includesTax is true and they are a part of it.

includesTaxboolean

Whether the taxes are a part of amountMinor rather than added to it.

subscriptionIdstring

The subscription this line item is associated with, if any.

licenseIdstring

The license this line item is associated with, if any.

discountsarray of object

Discounts applied to this line item.

Show child attributes
taxesarray of object

Taxes applied to this line item.

Show child attributes
discountsarray of PaymentIntentDiscountrequired

Reductions applied to the payment intent as a whole rather than to one billed line.

Show child attributes
descriptionstringrequired

Why the payment intent was reduced.

amountMinorintegerint64required

The positive amount deducted, in minor units of the payment intent currency.

attemptsarray of PaymentAttemptrequired

Charge attempts made against this payment intent, most recent first.

Show child attributes
paymentAttemptIdstringrequired

The unique identifier for this charge attempt.

amountMinorintegerint64required

The amount charged in this attempt, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).

currencystringrequired

The ISO 4217 currency code the attempt was charged in (e.g., "USD").

resultenum<string>required

Whether the charge attempt succeeded or failed.

values

  • SUCCEEDED
  • FAILED
reasonstring

Failure reason when the attempt did not succeed.

chargedAtstringdate-time

When the charge was made.

createdAtstringdate-timerequired

When the attempt was created.

refundsarray of PaymentRefundrequired

Refunds issued against this payment intent.

Show child attributes
refundIdstringrequired

The unique identifier for this refund.

amountMinorintegerint64required

The refunded amount, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).

currencystringrequired

The ISO 4217 currency code the refund is issued in (e.g., "USD").

reasonenum<string>

Why the refund was issued.

values

  • UNKNOWN
  • DUPLICATE
  • FRAUDULENT
  • REQUESTED_BY_CUSTOMER
  • DISPUTE_LOST
statusenum<string>required

Current stage of the refund.

values

  • PENDING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • REQUIRES_ACTION
createdAtstringdate-timerequired

When the refund was created.

createdAtstringdate-timerequired

When the payment intent was created.

updatedAtstringdate-timerequired

When the payment intent was last updated.

dueDatestringdaterequired

The date payment is due. Absent when the provider has no due date.

subtotalAmountMinorintegerint64deprecated

Deprecated. Read the related payment intent's line items instead.

taxAmountMinorintegerint64deprecated

Deprecated. Read the related payment intent's line-item taxes instead.

feeAmountMinorintegerint64deprecated

Deprecated. The invoice projection has no separate fee total.

discountAmountMinorintegerint64deprecated

Deprecated. Read the related payment intent's line-item discounts instead.

totalAmountMinorintegerint64deprecated

Deprecated. Read amountDueMinor instead.

amountDueMinorintegerint64required

The amount due when the invoice was issued, in minor units of the invoice currency.

amountPaidMinorintegerint64required

The amount credited to the invoice, in minor units of the invoice currency.

amountRemainingMinorintegerint64required

The amount still unpaid, in minor units of the invoice currency.

currencystringrequired

The ISO 4217 currency code for the invoice amounts.

issuedAtstringdate-time

When the provider issued the invoice. Absent while the invoice is a draft.

sentAtstringdate-timedeprecated

Deprecated. Read issuedAt instead.

paidAtstringdate-time

When the invoice became paid.

voidedAtstringdate-time

When the invoice was voided.

hostedUrlstringuri

The provider-hosted page where the customer can view and pay the invoice.

invoiceUrlstringurideprecated

Deprecated. Read hostedUrl instead.

pdfUrlstringuri

Direct URL to the provider-generated invoice PDF.

createdAtstringdate-timerequired

When the invoice record was created.

updatedAtstringdate-timerequired

When the invoice record was last updated.

metadataobject with string keysdeprecated

Deprecated. Invoice metadata is not stored by the platform.

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",
  "number": "INV-2026-001",
  "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
    }
  ],
  "invoiceNumber": "string",
  "status": "UNKNOWN",
  "paymentProvider": "STRIPE",
  "paymentIntent": {
    "paymentIntentId": "64870b5c-fb61-4c9a-955a-e148e0826c20",
    "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "status": "SUCCEEDED",
    "amountMinor": 2900,
    "currency": "USD",
    "description": "Mobile subscription renewal",
    "dueAt": "2024-01-15T10:00:00Z",
    "lineItems": [
      {
        "description": "Mobile subscription - Premium Plan",
        "amountMinor": 2900,
        "includesTax": false,
        "subscriptionId": "a8174435-6378-4be5-a9f5-8b4aaadae5d4",
        "licenseId": "ffb19d4f-b3b6-4f2b-9365-dd80bdcf0a77",
        "discounts": [
          {
            "description": "Loyalty discount",
            "amountMinor": 500
          }
        ],
        "taxes": [
          {
            "description": "VAT 25%",
            "amountMinor": 725
          }
        ]
      }
    ],
    "discounts": [
      {
        "description": "Goodwill credit",
        "amountMinor": 1000
      }
    ],
    "attempts": [
      {
        "paymentAttemptId": "a4da2b04-aa79-4b40-8987-048d6caf118f",
        "amountMinor": 2900,
        "currency": "USD",
        "result": "SUCCEEDED",
        "reason": "card_declined",
        "chargedAt": "2024-01-15T10:00:00Z",
        "createdAt": "2024-01-15T10:00:00Z"
      }
    ],
    "refunds": [
      {
        "refundId": "c014b666-22e4-430e-bb18-9257a383dfe2",
        "amountMinor": 2900,
        "currency": "USD",
        "reason": "REQUESTED_BY_CUSTOMER",
        "status": "SUCCEEDED",
        "createdAt": "2024-01-15T10:00:00Z"
      }
    ],
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-01-15T10:00:00Z"
  },
  "dueDate": "2026-08-31",
  "subtotalAmountMinor": 1,
  "taxAmountMinor": 1,
  "feeAmountMinor": 1,
  "discountAmountMinor": 1,
  "totalAmountMinor": 1,
  "amountDueMinor": 3239,
  "amountPaidMinor": 0,
  "amountRemainingMinor": 3239,
  "currency": "USD",
  "issuedAt": "2026-08-01T08:00:00Z",
  "sentAt": "2024-01-15T10:30:00Z",
  "paidAt": "2026-08-20T14:30:00Z",
  "voidedAt": "2026-08-10T09:00:00Z",
  "hostedUrl": "https://example.com/invoices/123e4567-e89b-12d3-a456-426614174000",
  "invoiceUrl": "https://example.com/resource",
  "pdfUrl": "https://example.com/invoices/123e4567-e89b-12d3-a456-426614174000.pdf",
  "createdAt": "2026-08-01T08:00:00Z",
  "updatedAt": "2026-08-01T08: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."
}