Valdyr
View as MarkdownOpen in ClaudeOpen in ChatGPT

Invoices

The invoices of the customers that the user manages.

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
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.

createdAtstringdate-timerequired

When the invoice record was created.

currencystringrequired

The ISO 4217 currency code for the invoice amounts.

customerIdstringrequired

The customer this invoice collects payment from.

dueDatestringdaterequired

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

hostedUrlstringuri

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

invoiceIdstringrequired

Unique identifier for the invoice.

issuedAtstringdate-time

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

numberstring

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

sentAtstringdate-timedeprecated

Deprecated. Read issuedAt instead.

paidAtstringdate-time

When the invoice became paid.

paymentProviderenum<string>

The provider that issued and manages the invoice.

Payment service provider that processes the transaction.

values

  • STRIPE
  • BILLOGRAM
invoiceUrlstringurideprecated

Deprecated. Read hostedUrl instead.

pdfUrlstringuri

Direct URL to the provider-generated invoice PDF.

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
updatedAtstringdate-timerequired

When the invoice record was last updated.

voidedAtstringdate-time

When the invoice was voided.

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. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

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.

detailsarray of object

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

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

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

propertystring

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

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

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
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

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

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

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.

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. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

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.

detailsarray of object

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

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

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

propertystring

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

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

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
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

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

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

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.

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. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

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.

detailsarray of object

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

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

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

propertystring

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

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

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
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

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

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

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.

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. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

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.

detailsarray of object

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

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

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

propertystring

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

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

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
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

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

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

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.

Auth required

Send

  • X-Api-Key + Bearer JWT
GET /invoices
curl https://apiv2.example.com/api/v2/end-user/invoices \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
fetch('https://apiv2.example.com/api/v2/end-user/invoices', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})
requests.get(
    "https://apiv2.example.com/api/v2/end-user/invoices",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)
package main

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

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

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

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

	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
  }
}
{
  "code": "bad_request",
  "details": [
    {
      "code": "invalid_email",
      "message": "Email format is invalid.",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields.",
  "message": "The request body is invalid."
}
{
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header.",
  "message": "Authentication is required to access this resource."
}
{
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions.",
  "message": "You do not have permission to perform this action."
}
{
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support.",
  "message": "An unexpected error occurred on the server."
}

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.

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.

createdAtstringdate-timerequired

When the invoice record was created.

currencystringrequired

The ISO 4217 currency code for the invoice amounts.

customerIdstringrequired

The customer this invoice collects payment from.

dueDatestringdaterequired

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

hostedUrlstringuri

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

invoiceIdstringrequired

Unique identifier for the invoice.

issuedAtstringdate-time

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

numberstring

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

sentAtstringdate-timedeprecated

Deprecated. Read issuedAt instead.

paidAtstringdate-time

When the invoice became paid.

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
amountMinorintegerint64required

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

attemptsarray of PaymentAttemptrequired

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

Show child attributes
amountMinorintegerint64required

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

chargedAtstringdate-time

When the charge was made.

createdAtstringdate-timerequired

When the attempt was created.

currencystringrequired

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

paymentAttemptIdstringrequired

The unique identifier for this charge attempt.

reasonstring

Failure reason when the attempt did not succeed.

resultenum<string>required

Whether the charge attempt succeeded or failed.

values

  • SUCCEEDED
  • FAILED
createdAtstringdate-timerequired

When the payment intent was created.

currencystringrequired

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

customerIdstringrequired

The customer this payment intent collects from.

descriptionstring

A human-readable description of what is being collected.

discountsarray of PaymentIntentDiscountrequired

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

Show child attributes
amountMinorintegerint64required

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

descriptionstringrequired

Why the payment intent was reduced.

dueAtstringdate-time

When the amount is due.

lineItemsarray of PaymentIntentLineItemrequired

The items that make up the collected amount.

Show child attributes
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.

descriptionstringrequired

What this line item represents.

discountsarray of object

Discounts applied to this line item.

Show child attributes
includesTaxboolean

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

licenseIdstring

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

subscriptionIdstring

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

taxesarray of object

Taxes applied to this line item.

Show child attributes
paymentIntentIdstringrequired

The unique identifier for this payment intent.

refundsarray of PaymentRefundrequired

Refunds issued against this payment intent.

Show child attributes
amountMinorintegerint64required

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

createdAtstringdate-timerequired

When the refund was created.

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
refundIdstringrequired

The unique identifier for this refund.

statusenum<string>required

Current stage of the refund.

values

  • PENDING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • REQUIRES_ACTION
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
updatedAtstringdate-timerequired

When the payment intent was last updated.

paymentProviderenum<string>

The provider that issued and manages the invoice.

Payment service provider that processes the transaction.

values

  • STRIPE
  • BILLOGRAM
invoiceUrlstringurideprecated

Deprecated. Read hostedUrl instead.

pdfUrlstringuri

Direct URL to the provider-generated invoice PDF.

lineItemsarray of InvoiceLineItemdeprecatedrequired

Deprecated. Read paymentIntent.lineItems instead.

Show child attributes
descriptionstringrequired

Description of what this line item represents.

discountsarray of object

Detailed discount breakdown for this line item.

Show child attributes
amountMinorintegerint64required

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

namestringrequired

Discount name or description.

feesarray of object

Detailed fee breakdown for this line item.

Show child attributes
amountMinorintegerint64required

Fee amount, in minor currency units.

namestringrequired

Fee name or description.

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.

subscriptionIdstring

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

subtotalMinorintegerint64required

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

taxAmountMinorintegerint64

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

taxBreakdownarray of TaxBreakdownItem

Tax breakdown for this line item.

Show child attributes
amountMinorintegerint64required

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

descriptionstringrequired

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

ratenumberdecimal

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

taxIncludedboolean

Whether taxes are included in the total.

totalDiscountsMinorintegerint64

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

totalFeesMinorintegerint64

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

totalMinorintegerint64required

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

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).

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
updatedAtstringdate-timerequired

When the invoice record was last updated.

voidedAtstringdate-time

When the invoice was voided.

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. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

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.

detailsarray of object

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

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

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

propertystring

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

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

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
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

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

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

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.

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. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

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.

detailsarray of object

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

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

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

propertystring

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

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

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
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

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

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

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.

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. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

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.

detailsarray of object

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

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

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

propertystring

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

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

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
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

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

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

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.

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. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

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.

detailsarray of object

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

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

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

propertystring

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

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

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
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

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

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

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.

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. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

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.

detailsarray of object

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

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

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

propertystring

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

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

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
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

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

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

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.

Auth required

Send

  • X-Api-Key + Bearer JWT
GET /invoices/{invoiceId}
curl https://apiv2.example.com/api/v2/end-user/invoices/094f10ca-616e-441c-b264-9a2305d6692d \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
fetch('https://apiv2.example.com/api/v2/end-user/invoices/094f10ca-616e-441c-b264-9a2305d6692d', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})
requests.get(
    "https://apiv2.example.com/api/v2/end-user/invoices/094f10ca-616e-441c-b264-9a2305d6692d",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)
package main

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

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

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

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

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

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

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

}
{
  "subtotalAmountMinor": 1,
  "taxAmountMinor": 1,
  "feeAmountMinor": 1,
  "discountAmountMinor": 1,
  "totalAmountMinor": 1,
  "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/123e4567-e89b-12d3-a456-426614174000",
  "invoiceId": "123e4567-e89b-12d3-a456-426614174000",
  "issuedAt": "2026-08-01T08:00:00Z",
  "number": "INV-2026-001",
  "sentAt": "2024-01-15T10:30:00Z",
  "paidAt": "2026-08-20T14:30:00Z",
  "paymentIntent": {
    "amountMinor": 2900,
    "attempts": [
      {
        "amountMinor": 2900,
        "chargedAt": "2024-01-15T10:00:00Z",
        "createdAt": "2024-01-15T10:00:00Z",
        "currency": "USD",
        "paymentAttemptId": "a4da2b04-aa79-4b40-8987-048d6caf118f",
        "reason": "card_declined",
        "result": "SUCCEEDED"
      }
    ],
    "createdAt": "2024-01-15T10:00:00Z",
    "currency": "USD",
    "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "description": "Mobile subscription renewal",
    "discounts": [
      {
        "amountMinor": 1000,
        "description": "Goodwill credit"
      }
    ],
    "dueAt": "2024-01-15T10:00:00Z",
    "lineItems": [
      {
        "amountMinor": 2900,
        "description": "Mobile subscription - Premium Plan",
        "discounts": [
          {
            "amountMinor": 500,
            "description": "Loyalty discount"
          }
        ],
        "includesTax": false,
        "licenseId": "ffb19d4f-b3b6-4f2b-9365-dd80bdcf0a77",
        "subscriptionId": "a8174435-6378-4be5-a9f5-8b4aaadae5d4",
        "taxes": [
          {
            "amountMinor": 725,
            "description": "VAT 25%"
          }
        ]
      }
    ],
    "paymentIntentId": "64870b5c-fb61-4c9a-955a-e148e0826c20",
    "refunds": [
      {
        "amountMinor": 2900,
        "createdAt": "2024-01-15T10:00:00Z",
        "currency": "USD",
        "reason": "REQUESTED_BY_CUSTOMER",
        "refundId": "c014b666-22e4-430e-bb18-9257a383dfe2",
        "status": "SUCCEEDED"
      }
    ],
    "status": "SUCCEEDED",
    "updatedAt": "2024-01-15T10:00:00Z"
  },
  "paymentProvider": "STRIPE",
  "invoiceUrl": "https://example.com/resource",
  "pdfUrl": "https://example.com/invoices/123e4567-e89b-12d3-a456-426614174000.pdf",
  "lineItems": [
    {
      "description": "Mobile subscription - Premium Plan",
      "discounts": [
        {
          "amountMinor": 500,
          "name": "Volume discount"
        }
      ],
      "fees": [
        {
          "amountMinor": 1000,
          "name": "Late payment fee"
        }
      ],
      "licenseId": "ffb19d4f-b3b6-4f2b-9365-dd80bdcf0a77",
      "productOfferingId": "mobile-plan-premium",
      "quantity": 1,
      "subscriptionId": "b8174435-6378-4be5-a9f5-8b4aaadae5d4",
      "subtotalMinor": 2999,
      "taxAmountMinor": 240,
      "taxBreakdown": [
        {
          "amountMinor": 240,
          "description": "Sales Tax",
          "rate": 8.25
        }
      ],
      "taxIncluded": false,
      "totalDiscountsMinor": 500,
      "totalFeesMinor": 1000,
      "totalMinor": 3739,
      "unitPriceMinor": 2999
    }
  ],
  "invoiceNumber": "string",
  "status": "UNKNOWN",
  "updatedAt": "2026-08-01T08:00:00Z",
  "voidedAt": "2026-08-10T09:00:00Z",
  "metadata": {
    "propertyName": "string"
  }
}
{
  "code": "bad_request",
  "details": [
    {
      "code": "invalid_email",
      "message": "Email format is invalid.",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields.",
  "message": "The request body is invalid."
}
{
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header.",
  "message": "Authentication is required to access this resource."
}
{
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions.",
  "message": "You do not have permission to perform this action."
}
{
  "code": "not_found",
  "hint": "Verify the customerId and try again.",
  "message": "The requested customer could not be found."
}
{
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support.",
  "message": "An unexpected error occurred on the server."
}