Skip to main content
POST
Create Manual Line Item

Authorizations

​
Authorization
string
header
required

API key authentication

Headers

​
Idempotency-Key
string

Optional idempotency key. If provided, duplicate requests with the same key return the previously created item.

Maximum string length: 255

Body

application/json
​
displayName
string
required

Human-readable label shown on the invoice.

Required string length: 1 - 255
​
currency
string
required

ISO 4217 currency code (e.g., USD). Must match the subscription or invoice currency.

Required string length: 3
​
quantity
number
required

Number of units.

​
unitPrice
number
required

Price per unit as a decimal amount (e.g., 29.99 for $29.99). Can be negative for credits or adjustments.

​
subscriptionId
string

The subscription ID. Exactly one of subscriptionId or invoiceId must be provided.

​
invoiceId
string

The invoice ID to attach this item directly to. Exactly one of subscriptionId or invoiceId must be provided. The invoice must be in ACTIVE or CLOSING state.

Pattern: ^inv_[a-zA-Z0-9]+$
​
description
string | null

Optional longer description shown on the invoice.

Maximum string length: 1000
​
invoiceAt
string<date-time> | null

When to collect this item into an invoice. Defaults to now. Ignored when invoiceId is provided.

​
periodStart
string<date-time> | null

Start of the billing period for display purposes. Defaults to now.

​
periodEnd
string<date-time> | null

End of the billing period for display purposes. Defaults to now.

​
idempotencyKey
string | null

Optional caller-provided idempotency key. Auto-generated if not provided.

Required string length: 1 - 255
​
itemId
string | null

Optional item to tag this line with, for accounting/GL mapping. Must belong to the caller's merchant and must not be archived. A manual line has no price, so it is never reached by a later restamp — supplying it here is the only opportunity to tag it.

Minimum string length: 1

Response

Idempotent retry — returns previously created item

​
id
string
required

The line item ID

​
subscriptionId
string
required

The subscription this line item belongs to

​
customerId
string
required

The customer ID that owns this line item

​
type
enum<string>
required

The type of line item. 'discount' and 'adjustment' line items have negative subtotal/total amounts: 'discount' is a grant discount, 'adjustment' is a discount agreed on the subscription.

Available options:
fee,
metered,
manual,
discount,
adjustment
​
status
enum<string>
required

Whether this item is pending or already on an invoice

Available options:
pending,
invoiced
​
displayName
string
required

Human-readable label shown on the invoice

​
currency
string
required

ISO 4217 currency code (e.g., USD)

​
periodStart
string<date-time>
required

Start of the billing period (inclusive)

​
periodEnd
string<date-time>
required

End of the billing period (exclusive)

​
invoiceAt
string<date-time>
required

When this line item should be collected into an invoice

​
unitPrice
string
required

Price per unit in invoice currency

​
createdAt
string<date-time>
required

When the line item was created

​
updatedAt
string<date-time>
required

When the line item was last updated

​
priceId
string | null

The price this line was generated from, or null when the line has no originating charge. With itemId it says whether a missing tag is fixable: priceId set and itemId null means the charge was simply untagged, which tagging it and restamping resolves; both null means the line records a grant-credit purchase, which is deferred revenue and is never tagged. Any measure of outstanding mapping work must exclude the latter or it can never reach zero.

​
itemId
string | null

Item the line's charge was tagged with, recorded when the line was generated and not re-resolved on read. null means the charge carried no tag at that moment, the line predates item stamping, or the line has no originating charge (a grant-credit purchase) — it is an expected value, not an error. Use priceId to tell those cases apart.

​
invoiceId
string | null

The invoice ID if this item has been invoiced

​
description
string | null

Optional longer description

​
calculatedAt
string<date-time> | null

When metered quantity was last computed

​
quantity
string | null

Units sold. Null for metered lines until invoice close

​
meteredQuantity
string | null

Raw metered usage. Null for fee/manual lines

​
usageDiscountIds
string[]

The subscription adjustments of type usageDiscount that reduced this line's billable quantity. Empty for every other line. Where this is non-empty, quantity is below meteredQuantity because an operator waived units, rather than because a grant covered them.

​
paymentTerm
enum<string> | null

When the line falls due relative to the window it covers. A fee line carries its price's term; a metered line is stamped in_arrears, though metered rows predating that rule carry null. Manual, grant-discount and adjustment lines are billed on no term of their own and are null. null is listed in the enum as well as via nullable because OpenAPI 3.0 validators check the enum independently — nullable: true alone does not admit it, and createLineItem (which always returns null here) was emitting a schema-violating body.

Available options:
in_advance,
in_arrears,
null
​
subtotal
string

quantity × unitPrice, before discounts and taxes. For prorated lines, may differ from quantity × unitPrice by display precision; subtotal is the authoritative billed amount. Defaults to '0.00' when not yet calculated.

​
taxesTotal
string | null

Total tax amount for this line item in decimal format. Null until invoice calculation is complete

​
total
string

Final total after discounts and taxes. Defaults to '0.00' when not yet calculated

​
estimatedMeteredQuantity
string | null

Real-time estimated metered usage quantity. Only present for type=metered items during an active billing period. Null for fee/manual items or when estimation is unavailable.

​
estimatedSubtotal
string | null

Real-time estimated subtotal for a line whose amount is not final yet: current usage for a metered item, the rate the subscription is on for a fee. Null for manual items, and for any line whose amount is already final or cannot be estimated.

​
provenance
object

How the line's amount before tax was calculated: a trace of one evaluation, saved when the invoice was calculated and fixed once it is issued. Returned only with expand=lineProvenance. Every field but status is present when status is recorded. Every number is a plain decimal string.