GET/admin/v1/invoices

List invoices

Lists invoices.

query parameters

organizationId
string
Filter results by organization identifier.
This is required if user identifier is not specified.
userId
string
Filter results by user identifier.
This is required if organization identifier is not specified.
pageSize
int32
The maximum number of invoices to return. The API may return fewer than this value.
If unspecified, at most 20 invoices will be returned. The maximum value is 100; values above 100 will be coerced to 100.
pageToken
string
A page token, received from a previous list invoices call. Provide this to retrieve the subsequent page.
When paginating, all other parameters provided to list invoices must match the call that provided the page token.
orderBy
string
A comma-separated list of fields to order by.
Supports:
- createTime asc
- createTime desc

Returns

invoices
Invoice[]
The list of invoices.
id
string
The system-assigned identifier of the invoice.
state
enum
The status of the invoice.
Possible values:
DRAFTOPENPAIDVOIDUNCOLLECTIBLEBROKEN
stateReason
string
The code that best describes the reason for the state.
stateTime
date-time
The time associated with the current state (e.g. paid time).
connection
Connection
The billing connection.
id
string
The system-assigned identifier of the connection.
uniqueId
string
The client defined unique identifier of the connection.
It is restricted to letters, numbers, underscores, and hyphens, with the first character a letter or a number, and a 255 character maximum.
ID's starting with conn_ are reserved.
displayName
string
The human-readable display name of the connection.
The maximum length is 200 characters.
state
enum
The current status of the connection.
Possible values:
PENDING_SETUPACTIVEBROKENDISABLEDARCHIVED
stateReason
string
The code that best describes the reason for the state.
type
string
The connection type.
delegate
ConnectionDelegate
The delegated connection.
id
string
The delegated connection identifier.
uniqueId
string
The client defined unique identifier of the delegated connection.
displayName
string
The human-readable display name of the delegated connection.
state
enum
The current status of the delegated connection.
Possible values:
PENDING_SETUPACTIVEBROKENDISABLEDARCHIVED
stateReason
string
The code that best describes the reason for the state.
type
string
The delegated connection type.
providers
ConnectionProvider[]
The connection providers.
type
string
The provider type.
default
boolean
Whether the connection is the default for the provider type.
createTime
date-time
The creation time of the connection.
updateTime
date-time
The last update time of the connection.
auth0
Auth0Connection
The Auth0 connection data.
domain
string
The Auth0 domain.
clientId
string
The Auth0 client ID.
clientSecret
string
The Auth0 client secret.
builtinEmail
BuiltinEmailConnection
The builtin email configuration data.
allowedEmails
string[]
The allowed email list.
googleCloudIdentityPlatform
GoogleCloudIdentityPlatformConnection
The Google Cloud Identity Platform (Firebase Auth) connection.
credentials
string
The service account key in JSON format.
projectId
string
The Google Cloud Identity Platform/Firebase project ID.
This will default to the project ID in the service account key if not specified.
postmark
PostmarkConnection
The Postmark configuration data.
serverToken
string
The Postmark server token (e.g. 942faf79-bf10-4dc1-830a-dc7943f43f35).
serverId
string
The Postmark server ID.
This is automatically populated when the server token is updated.
from
Email
The from email address.
The Postmark account must be allowed to send from this email address.
address
string
The email address (e.g. [email protected]).
displayName
string
The email name (e.g. Jane Doe).
replyTo
Email
The reply to email address.
address
string
The email address (e.g. [email protected]).
displayName
string
The email name (e.g. Jane Doe).
allowedEmails
string[]
The allowed email list.
stripe
StripeConnection
The Stripe billing configuration data.
accountId
string
The Stripe account ID (e.g. acct_1LcUvxQYGbxD2SPK)
live
boolean
The live vs test status for the Stripe account.
webhook
WebhookConnection
The webhooks configuration data.
url
string
The URL of the events webhook.
headers
string
The headers sent with requests to the connection URL.
signingSecrets
SigningSecret[]
The webhook secrets
secret
string
The signing secret value.
expireTime
date-time
The time the signing secret is set to expire.
externalId
string
The external identifier of the invoice.
number
string
The invoice number.
currencyCode
string
The currency code for the invoice (e.g. USD).
description
string
The user facing description for the invoice.
account
InvoiceAccount
The bill to contact information.
fullName
string
The company or individual's full name.
email
string
The billing email address.
phoneNumber
string
The billing phone number.
address
Address
The billing address.
lines
string[]
The address lines.
city
string
The city, district, suburb, town, or village.
state
string
The state, country, province, or region.
postalCode
string
The ZIP or postal code.
country
string
The 2-letter country code.
effectiveTime
date-time
The time the invoice was finalized.
period
Period
The billing period for the invoice.
startTime
date-time
The start time.
endTime
date-time
The end time.
subtotalAmount
string
The subtotal amount for the invoice.
This includes item-level discounts.
discountAmount
string
The invoice-level discount amount.
This does not include item level discounts.
balance
InvoiceBalance
The starting and ending account balance as of the time the invoice was finalized.
startAmount
string
The starting balance of the account.
endAmount
string
The ending balance of the account.
appliedAmount
string
The amount applied to the invoice from the balance.
A negative amount means a debit from the account balance. A positive amount means a credit to the account balance.
taxAmount
string
The tax amount for the invoice.
This is for rendering purposes only and is not the reported tax amount.
totalAmount
string
The total amount for the invoice.
dueAmount
string
The total amount minus any credits automatically associated with the invoice.
remainingDueAmount
string
The due amount minus the amount already paid.
dueTime
date-time
The time the invoice must be paid by.
paidAmount
string
The amount already paid towards the invoice.
paymentState
enum
The status of the invoice payment.
Possible values:
PAYMENT_METHOD_REQUIREDACTION_REQUIREDPROCESSING
paymentIntent
PaymentIntent
The payment intent for the invoice.
stripe
StripePaymentIntent
A Stripe payment intent.
accountId
string
The Stripe account ID (e.g. acct_1LcUvxQYGbxD2SPK)
live
boolean
Whether the Stripe payment intent was created in live mode.
clientSecret
string
The Stripe payment intent client secret.
items
InvoiceItem[]
The line items for the invoice.
id
string
The identifier of the item.
product
Product
The details of the associated product.
id
string
The system-assigned identifier of the product.
uniqueId
string
The client defined unique identifier of the product.
It is restricted to letters, numbers, underscores, and hyphens, with the first character a letter or a number, and a 255 character maximum.
ID's starting with pd_ are reserved.
displayName
string
The customer facing human-readable display name of the product.
The maximum length is 200 characters.
description
string
The public description of the product.
The maximum length is 1000 characters.
committed
boolean
Whether the price has been committed.
This is automatically set the first time the product is used in a plan.
archived
boolean
The archived status of the product.
It determines if the product can be activated by self-serve plans.
productConnections
ProductConnection[]
The connected products.
connection
Connection
The basic view of the connection.
id
string
The system-assigned identifier of the connection.
uniqueId
string
The client defined unique identifier of the connection.
It is restricted to letters, numbers, underscores, and hyphens, with the first character a letter or a number, and a 255 character maximum.
ID's starting with conn_ are reserved.
displayName
string
The human-readable display name of the connection.
The maximum length is 200 characters.
state
enum
The current status of the connection.
Possible values:
PENDING_SETUPACTIVEBROKENDISABLEDARCHIVED
stateReason
string
The code that best describes the reason for the state.
type
string
The connection type.
delegate
ConnectionDelegate
The delegated connection.
id
string
The delegated connection identifier.
uniqueId
string
The client defined unique identifier of the delegated connection.
displayName
string
The human-readable display name of the delegated connection.
state
enum
The current status of the delegated connection.
Possible values:
PENDING_SETUPACTIVEBROKENDISABLEDARCHIVED
stateReason
string
The code that best describes the reason for the state.
type
string
The delegated connection type.
providers
ConnectionProvider[]
The connection providers.
type
string
The provider type.
default
boolean
Whether the connection is the default for the provider type.
createTime
date-time
The creation time of the connection.
updateTime
date-time
The last update time of the connection.
auth0
Auth0Connection
The Auth0 connection data.
domain
string
The Auth0 domain.
clientId
string
The Auth0 client ID.
clientSecret
string
The Auth0 client secret.
builtinEmail
BuiltinEmailConnection
The builtin email configuration data.
allowedEmails
string[]
The allowed email list.
googleCloudIdentityPlatform
GoogleCloudIdentityPlatformConnection
The Google Cloud Identity Platform (Firebase Auth) connection.
credentials
string
The service account key in JSON format.
projectId
string
The Google Cloud Identity Platform/Firebase project ID.
This will default to the project ID in the service account key if not specified.
postmark
PostmarkConnection
The Postmark configuration data.
serverToken
string
The Postmark server token (e.g. 942faf79-bf10-4dc1-830a-dc7943f43f35).
serverId
string
The Postmark server ID.
This is automatically populated when the server token is updated.
from
Email
The from email address.
The Postmark account must be allowed to send from this email address.
address
string
The email address (e.g. [email protected]).
displayName
string
The email name (e.g. Jane Doe).
replyTo
Email
The reply to email address.
address
string
The email address (e.g. [email protected]).
displayName
string
The email name (e.g. Jane Doe).
allowedEmails
string[]
The allowed email list.
stripe
StripeConnection
The Stripe billing configuration data.
accountId
string
The Stripe account ID (e.g. acct_1LcUvxQYGbxD2SPK)
live
boolean
The live vs test status for the Stripe account.
webhook
WebhookConnection
The webhooks configuration data.
url
string
The URL of the events webhook.
headers
string
The headers sent with requests to the connection URL.
signingSecrets
SigningSecret[]
The webhook secrets
secret
string
The signing secret value.
expireTime
date-time
The time the signing secret is set to expire.
externalId
string
The external identifier of the connected product.
state
enum
The status of the connected product.
Possible values:
ACTIVEBROKENDISABLED
stateReason
string
The code that best describes the reason for the state.
pullTime
date-time
The last time the product was pulled from the connection.
pushTime
date-time
The last time the product was pushed to the connection.
createTime
date-time
The creation time of the product connection.
updateTime
date-time
The last update time of the product connection.
createTime
date-time
The creation time of the product.
updateTime
date-time
The last update time of the product.
price
Price
The details of the associated price.
id
string
The system-assigned identifier of the price.
connection
Connection
The connection.
id
string
The system-assigned identifier of the connection.
uniqueId
string
The client defined unique identifier of the connection.
It is restricted to letters, numbers, underscores, and hyphens, with the first character a letter or a number, and a 255 character maximum.
ID's starting with conn_ are reserved.
displayName
string
The human-readable display name of the connection.
The maximum length is 200 characters.
state
enum
The current status of the connection.
Possible values:
PENDING_SETUPACTIVEBROKENDISABLEDARCHIVED
stateReason
string
The code that best describes the reason for the state.
type
string
The connection type.
delegate
ConnectionDelegate
The delegated connection.
id
string
The delegated connection identifier.
uniqueId
string
The client defined unique identifier of the delegated connection.
displayName
string
The human-readable display name of the delegated connection.
state
enum
The current status of the delegated connection.
Possible values:
PENDING_SETUPACTIVEBROKENDISABLEDARCHIVED
stateReason
string
The code that best describes the reason for the state.
type
string
The delegated connection type.
providers
ConnectionProvider[]
The connection providers.
type
string
The provider type.
default
boolean
Whether the connection is the default for the provider type.
createTime
date-time
The creation time of the connection.
updateTime
date-time
The last update time of the connection.
auth0
Auth0Connection
The Auth0 connection data.
domain
string
The Auth0 domain.
clientId
string
The Auth0 client ID.
clientSecret
string
The Auth0 client secret.
builtinEmail
BuiltinEmailConnection
The builtin email configuration data.
allowedEmails
string[]
The allowed email list.
googleCloudIdentityPlatform
GoogleCloudIdentityPlatformConnection
The Google Cloud Identity Platform (Firebase Auth) connection.
credentials
string
The service account key in JSON format.
projectId
string
The Google Cloud Identity Platform/Firebase project ID.
This will default to the project ID in the service account key if not specified.
postmark
PostmarkConnection
The Postmark configuration data.
serverToken
string
The Postmark server token (e.g. 942faf79-bf10-4dc1-830a-dc7943f43f35).
serverId
string
The Postmark server ID.
This is automatically populated when the server token is updated.
from
Email
The from email address.
The Postmark account must be allowed to send from this email address.
address
string
The email address (e.g. [email protected]).
displayName
string
The email name (e.g. Jane Doe).
replyTo
Email
The reply to email address.
address
string
The email address (e.g. [email protected]).
displayName
string
The email name (e.g. Jane Doe).
allowedEmails
string[]
The allowed email list.
stripe
StripeConnection
The Stripe billing configuration data.
accountId
string
The Stripe account ID (e.g. acct_1LcUvxQYGbxD2SPK)
live
boolean
The live vs test status for the Stripe account.
webhook
WebhookConnection
The webhooks configuration data.
url
string
The URL of the events webhook.
headers
string
The headers sent with requests to the connection URL.
signingSecrets
SigningSecret[]
The webhook secrets
secret
string
The signing secret value.
expireTime
date-time
The time the signing secret is set to expire.
externalId
string
The external identifier of the connected price.
state
enum
The status of the connected price.
Possible values:
ACTIVEBROKENARCHIVED
stateReason
string
The code that best describes the reason for the state.
currencyCode
string
The currency for the price.
billingMode
enum
The billing mode for the price.
Possible values:
FIXED_TERMUSAGE_BASED
interval
Interval
The billing interval for the price.
quantity
int32
The interval quantity.
unit
enum
The interval unit.
Possible values:
DAYWEEKMONTHYEAR
displayName
string
The admin-facing display name of the price.
product
Product
The product associated with the price.
id
string
The system-assigned identifier of the product.
uniqueId
string
The client defined unique identifier of the product.
It is restricted to letters, numbers, underscores, and hyphens, with the first character a letter or a number, and a 255 character maximum.
ID's starting with pd_ are reserved.
displayName
string
The customer facing human-readable display name of the product.
The maximum length is 200 characters.
description
string
The public description of the product.
The maximum length is 1000 characters.
committed
boolean
Whether the price has been committed.
This is automatically set the first time the product is used in a plan.
archived
boolean
The archived status of the product.
It determines if the product can be activated by self-serve plans.
productConnections
ProductConnection[]
The connected products.
connection
Connection
The basic view of the connection.
id
string
The system-assigned identifier of the connection.
uniqueId
string
The client defined unique identifier of the connection.
It is restricted to letters, numbers, underscores, and hyphens, with the first character a letter or a number, and a 255 character maximum.
ID's starting with conn_ are reserved.
displayName
string
The human-readable display name of the connection.
The maximum length is 200 characters.
state
enum
The current status of the connection.
Possible values:
PENDING_SETUPACTIVEBROKENDISABLEDARCHIVED
stateReason
string
The code that best describes the reason for the state.
type
string
The connection type.
delegate
ConnectionDelegate
The delegated connection.
id
string
The delegated connection identifier.
uniqueId
string
The client defined unique identifier of the delegated connection.
displayName
string
The human-readable display name of the delegated connection.
state
enum
The current status of the delegated connection.
Possible values:
PENDING_SETUPACTIVEBROKENDISABLEDARCHIVED
stateReason
string
The code that best describes the reason for the state.
type
string
The delegated connection type.
providers
ConnectionProvider[]
The connection providers.
type
string
The provider type.
default
boolean
Whether the connection is the default for the provider type.
createTime
date-time
The creation time of the connection.
updateTime
date-time
The last update time of the connection.
auth0
Auth0Connection
The Auth0 connection data.
domain
string
The Auth0 domain.
clientId
string
The Auth0 client ID.
clientSecret
string
The Auth0 client secret.
builtinEmail
BuiltinEmailConnection
The builtin email configuration data.
allowedEmails
string[]
The allowed email list.
googleCloudIdentityPlatform
GoogleCloudIdentityPlatformConnection
The Google Cloud Identity Platform (Firebase Auth) connection.
credentials
string
The service account key in JSON format.
projectId
string
The Google Cloud Identity Platform/Firebase project ID.
This will default to the project ID in the service account key if not specified.
postmark
PostmarkConnection
The Postmark configuration data.
serverToken
string
The Postmark server token (e.g. 942faf79-bf10-4dc1-830a-dc7943f43f35).
serverId
string
The Postmark server ID.
This is automatically populated when the server token is updated.
from
Email
The from email address.
The Postmark account must be allowed to send from this email address.
address
string
The email address (e.g. [email protected]).
displayName
string
The email name (e.g. Jane Doe).
replyTo
Email
The reply to email address.
address
string
The email address (e.g. [email protected]).
displayName
string
The email name (e.g. Jane Doe).
allowedEmails
string[]
The allowed email list.
stripe
StripeConnection
The Stripe billing configuration data.
accountId
string
The Stripe account ID (e.g. acct_1LcUvxQYGbxD2SPK)
live
boolean
The live vs test status for the Stripe account.
webhook
WebhookConnection
The webhooks configuration data.
url
string
The URL of the events webhook.
headers
string
The headers sent with requests to the connection URL.
signingSecrets
SigningSecret[]
The webhook secrets
secret
string
The signing secret value.
expireTime
date-time
The time the signing secret is set to expire.
externalId
string
The external identifier of the connected product.
state
enum
The status of the connected product.
Possible values:
ACTIVEBROKENDISABLED
stateReason
string
The code that best describes the reason for the state.
pullTime
date-time
The last time the product was pulled from the connection.
pushTime
date-time
The last time the product was pushed to the connection.
createTime
date-time
The creation time of the product connection.
updateTime
date-time
The last update time of the product connection.
createTime
date-time
The creation time of the product.
updateTime
date-time
The last update time of the product.
archived
boolean
The archived status of the price.
It determines if the price can be used.
pullTime
date-time
The last time the price was pulled from the connection.
pushTime
date-time
The last time the price was pushed to the connection.
createTime
date-time
The creation time of the price.
updateTime
date-time
The last update time of the price.
fixed
PriceFixedPrice
The price is fixed per quantity.
amount
string
The decimal amount for the defined currency (e.g. 9.95).
transformQuantity
PriceTransformQuantity
Whether to transform the quantity before multiplying amount.
divisor
int32
The amount to divide the quantity by.
round
enum
Whether to round the result up or down.
Possible values:
UPDOWN
tiered
PriceTieredPrice
The price is dependent on the quantity.
mode
enum
The strategy for evaluating the tiers.
Possible values:
GRADUATEDVOLUME
tiers
TieredPriceTier[]
The tiers for the price.
upper
int32
The upper quantity for tier (inclusive).
unitAmount
string
The per quantity amount for the tier.
flatAmount
string
The flat amount for the tier.
quantity
int32
The quantity of the item product/price.
subtotalAmount
string
The total amount for the line item excluding taxes and discounts.
discountAmount
string
The item-level discount amount.
description
string
The user facing description for the line item.
externalId
string
The external identifier of the invoice item.
proration
boolean
Whether the item was a proration.
period
Period
The billing period for the item.
startTime
date-time
The start time.
endTime
date-time
The end time.
changes
InvoiceChange[]
The prorated changes that occurred mid-billing cycle.
time
date-time
The time the change occurred.
description
string
The user-facing description for the change.
subtotalAmount
string
The total amount for the change excluding taxes and discounts.
discountAmount
string
The change discount amount.
startQuantity
int32
The starting quantity of the change.
endQuantity
int32
The ending quantity of the change.
startItemIds
string[]
The starting (credited) item identifiers.
endItemIds
string[]
The ending (charged) item identifiers.
pullTime
date-time
The last time the invoice was pulled from the connection.
createTime
date-time
The creation time of the invoice.
updateTime
date-time
The last update time of the invoice.
nextPageToken
string
A token, which can be sent as pageToken to retrieve the next page. If this field is omitted, there are no subsequent pages.
previousPageToken
string
A token, which can be sent as pageToken to retrieve the previous page. If this field is absent, there are no preceding pages. If this field is an empty string then the previous page is the first result.

code
enum
The general error code (e.g. INVALID_ARGUMENT).
Possible values:
OKCANCELLEDUNKNOWNINVALID_ARGUMENTDEADLINE_EXCEEDEDNOT_FOUNDALREADY_EXISTSPERMISSION_DENIEDUNAUTHENTICATEDRESOURCE_EXHAUSTEDFAILED_PRECONDITIONABORTEDOUT_OF_RANGEUNIMPLEMENTEDINTERNALUNAVAILABLEDATA_LOSS
message
string
A developer-facing error message.
reason
string
A reason code for the error (e.g. USER_PENDING_DELETION).
param
string
The parameter path related to the error (e.g. member.userId).
metadata
string
Additional metadata related to the error.

curl https://api.userhub.com/admin/v1/invoices?organizationId=org_28seyVGVL1got6 \
  -H "Authorization: Bearer $ADMIN_API_KEY"

const res = await adminApi.invoices.list({
  organizationId: "org_28seyVGVL1got6",
});

res, err := adminApi.Invoices().List(
    context.Background(),
    &adminapi.InvoiceListInput{
        OrganizationId: "org_28seyVGVL1got6",
    },
)

$res = $adminApi->invoices->list(
    organizationId: 'org_28seyVGVL1got6',
);

res = admin_api.invoices.list(
    organization_id="org_28seyVGVL1got6",
)

Response bodyJSON

{
  "invoices": [
    {
      "id": "in_4QPqKvtqkpJzP7",
      "state": "OPEN",
      "stateTime": null,
      "connection": {
        "id": "conn_4HdRKnTvPmmjYK",
        "displayName": "Stripe",
        "state": "ACTIVE",
        "type": "STRIPE",
        "delegate": null,
        "providers": [],
        "createTime": "2024-06-15T13:00:00Z",
        "updateTime": "2024-06-15T13:00:00Z"
      },
      "externalId": "in_1NrpEGGZpdmtrghC4slAL174",
      "number": "ACME-123",
      "currencyCode": "USD",
      "description": "This is a test.",
      "account": {
        "fullName": "Jane Doe",
        "email": "[email protected]",
        "phoneNumber": "+12125550123",
        "address": {
          "lines": [
            "42 West St"
          ],
          "city": "Brooklyn",
          "state": "NY",
          "postalCode": "11222",
          "country": "US"
        }
      },
      "effectiveTime": "2024-06-15T13:00:00Z",
      "period": {
        "startTime": "2024-06-15T13:00:00Z",
        "endTime": "2024-06-15T13:00:00Z"
      },
      "subtotalAmount": "9",
      "discountAmount": "1",
      "balance": {
        "startAmount": "100",
        "endAmount": "200",
        "appliedAmount": "-100"
      },
      "taxAmount": "2",
      "dueAmount": "10",
      "dueTime": "2024-06-15T13:00:00Z",
      "paidAmount": "0",
      "paymentIntent": null,
      "items": [
        {
          "id": "ii_35kH3awC",
          "product": null,
          "price": null,
          "quantity": 2,
          "subtotalAmount": "10",
          "discountAmount": "1",
          "description": "This is a test item.",
          "externalId": "ii_456",
          "period": null
        }
      ],
      "changes": [],
      "pullTime": "2024-06-15T13:00:00Z",
      "createTime": "2024-06-15T13:00:00Z",
      "updateTime": "2024-06-15T13:00:00Z"
    }
  ],
  "nextPageToken": ""
}

PreviousThe invoice object

NextGet an invoice

List invoices

.css-10iahqc{text-transform:capitalize;}query parameters

Returns

query parameters