Create Manual Line Item

Create a manual line item for a billing v1 subscription. Manual line items are ad-hoc charges or credits that flow through the same collection pipeline as auto-generated items. Exactly one of subscriptionId or invoiceId must be provided.

POST /v2/invoices/lineItems

Create Manual Line Item

cURL

curl --request POST \
  --url https://api.paygentic.io/v2/invoices/lineItems \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "displayName": "<string>",
  "currency": "<string>",
  "quantity": 123,
  "unitPrice": 123,
  "subscriptionId": "<string>",
  "invoiceId": "<string>",
  "description": "<string>",
  "invoiceAt": "2023-11-07T05:31:56Z",
  "periodStart": "2023-11-07T05:31:56Z",
  "periodEnd": "2023-11-07T05:31:56Z",
  "idempotencyKey": "<string>",
  "itemId": "<string>"
}
'

200

{
  "id": "<string>",
  "subscriptionId": "<string>",
  "customerId": "<string>",
  "type": "fee",
  "status": "pending",
  "displayName": "<string>",
  "currency": "<string>",
  "periodStart": "2023-11-07T05:31:56Z",
  "periodEnd": "2023-11-07T05:31:56Z",
  "invoiceAt": "2023-11-07T05:31:56Z",
  "unitPrice": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "priceId": "<string>",
  "itemId": "<string>",
  "invoiceId": "<string>",
  "description": "<string>",
  "calculatedAt": "2023-11-07T05:31:56Z",
  "quantity": "<string>",
  "meteredQuantity": "<string>",
  "paymentTerm": "in_advance",
  "subtotal": "<string>",
  "taxesTotal": "<string>",
  "total": "<string>",
  "estimatedMeteredQuantity": "<string>",
  "estimatedSubtotal": "<string>"
}

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

200

application/json

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

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 based on current metered usage. Only present for type=metered items during an active billing period. Null for fee/manual items or when estimation is unavailable.