{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/recurly/json-schema/recurly-line-item-schema.json",
  "title": "Line item",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/recurly-openapi.yml#/components/schemas/LineItem",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "title": "Line item ID",
      "maxLength": 13
    },
    "object": {
      "type": "string",
      "title": "Object type"
    },
    "uuid": {
      "type": "string",
      "title": "UUID",
      "description": "The UUID is useful for matching data with the CSV exports and building URLs into Recurly's UI.",
      "maxLength": 32
    },
    "type": {
      "title": "Line item type",
      "description": "Charges are positive line items that debit the account. Credits are negative line items that credit the account.",
      "$ref": "#/$defs/LineItemTypeEnum"
    },
    "item_code": {
      "type": "string",
      "title": "Item Code",
      "description": "Unique code to identify an item. Available when the Credit Invoices feature is enabled.",
      "pattern": "/^[a-z0-9_+-]+$/",
      "maxLength": 50
    },
    "item_id": {
      "type": "string",
      "title": "Item ID",
      "description": "System-generated unique identifier for an item. Available when the Credit Invoices feature is enabled.",
      "maxLength": 13
    },
    "external_sku": {
      "type": "string",
      "title": "External SKU",
      "description": "Optional Stock Keeping Unit assigned to an item. Available when the Credit Invoices feature is enabled.",
      "maxLength": 50
    },
    "revenue_schedule_type": {
      "title": "Revenue schedule type",
      "$ref": "#/$defs/LineItemRevenueScheduleTypeEnum"
    },
    "state": {
      "title": "Current state of the line item",
      "description": "Pending line items are charges or credits on an account that have not been applied to an invoice yet. Invoiced line items will always have an `invoice_id` value.",
      "$ref": "#/$defs/LineItemStateEnum"
    },
    "legacy_category": {
      "title": "Legacy category",
      "description": "Category to describe the role of a line item on a legacy invoice:\n- \"charges\" refers to charges being billed for on this invoice.\n- \"credits\" refers to refund or proration credits. This portion of the invoice can be considered a credit memo.\n- \"applied_credits\" refers to previous credits applied to this invoice. See their original_line_item_id to determine where the credit first originated.\n- \"carryforwards\" can be ignored. They exist to consume any remaining credit balance. A new credit with the same amount will be created and placed back on the account.\n",
      "$ref": "#/$defs/LegacyCategoryEnum"
    },
    "account": {
      "$ref": "#/$defs/AccountMini"
    },
    "bill_for_account_id": {
      "type": "string",
      "title": "Bill For Account ID",
      "maxLength": 13,
      "description": "The UUID of the account responsible for originating the line item."
    },
    "subscription_id": {
      "type": "string",
      "title": "Subscription ID",
      "description": "If the line item is a charge or credit for a subscription, this is its ID.",
      "maxLength": 13
    },
    "plan_id": {
      "type": "string",
      "title": "Plan ID",
      "description": "If the line item is a charge or credit for a plan or add-on, this is the plan's ID.",
      "maxLength": 13
    },
    "plan_code": {
      "type": "string",
      "title": "Plan code",
      "description": "If the line item is a charge or credit for a plan or add-on, this is the plan's code.",
      "maxLength": 50
    },
    "add_on_id": {
      "type": "string",
      "title": "Add-on ID",
      "description": "If the line item is a charge or credit for an add-on this is its ID.",
      "maxLength": 13
    },
    "add_on_code": {
      "type": "string",
      "title": "Add-on code",
      "description": "If the line item is a charge or credit for an add-on, this is its code.",
      "maxLength": 50
    },
    "invoice_id": {
      "type": "string",
      "title": "Invoice ID",
      "description": "Once the line item has been invoiced this will be the invoice's ID.",
      "maxLength": 13
    },
    "invoice_number": {
      "type": "string",
      "title": "Invoice number",
      "description": "Once the line item has been invoiced this will be the invoice's number. If VAT taxation and the Country Invoice Sequencing feature are enabled, invoices will have country-specific invoice numbers for invoices billed to EU countries (ex: FR1001). Non-EU invoices will continue to use the site-level invoice number sequence."
    },
    "previous_line_item_id": {
      "type": "string",
      "title": "Previous line item ID",
      "description": "Will only have a value if the line item is a credit created from a previous credit, or if the credit was created from a charge refund.",
      "maxLength": 13
    },
    "original_line_item_invoice_id": {
      "type": "string",
      "title": "Original line item's invoice ID",
      "description": "The invoice where the credit originated. Will only have a value if the line item is a credit created from a previous credit, or if the credit was created from a charge refund.",
      "maxLength": 13
    },
    "origin": {
      "title": "Origin of line item",
      "description": "A credit created from an original charge will have the value of the charge's origin.",
      "$ref": "#/$defs/LineItemOriginEnum"
    },
    "accounting_code": {
      "type": "string",
      "title": "Accounting code",
      "description": "Internal accounting code to help you reconcile your revenue to the correct ledger. Line items created as part of a subscription invoice will use the plan or add-on's accounting code, otherwise the value will only be present if you define an accounting code when creating the line item.",
      "maxLength": 20
    },
    "product_code": {
      "type": "string",
      "title": "Product code",
      "description": "For plan-related line items this will be the plan's code, for add-on related line items it will be the add-on's code. For item-related line items it will be the item's `external_sku`.",
      "maxLength": 50
    },
    "credit_reason_code": {
      "title": "Credit reason code",
      "description": "The reason the credit was given when line item is `type=credit`.",
      "default": "general",
      "$ref": "#/$defs/FullCreditReasonCodeEnum"
    },
    "currency": {
      "type": "string",
      "title": "Currency",
      "description": "3-letter ISO 4217 currency code.",
      "maxLength": 3
    },
    "amount": {
      "type": "number",
      "format": "float",
      "title": "Total after discounts and taxes",
      "description": "`(quantity * unit_amount) - discount + tax`"
    },
    "description": {
      "type": "string",
      "title": "Description",
      "description": "Description that appears on the invoice. For subscription related items this will be filled in automatically.",
      "maxLength": 255
    },
    "quantity": {
      "type": "integer",
      "title": "Quantity",
      "description": "This number will be multiplied by the unit amount to compute the subtotal before any discounts or taxes.",
      "default": 1
    },
    "quantity_decimal": {
      "type": "string",
      "title": "Quantity Decimal",
      "description": "A floating-point alternative to Quantity. If this value is present, it will be used in place of Quantity for calculations, and Quantity will be the rounded integer value of this number. This field supports up to 9 decimal places. The Decimal Quantity feature must be enabled to utilize this field."
    },
    "unit_amount": {
      "type": "number",
      "format": "float",
      "title": "Unit amount",
      "description": "Positive amount for a charge, negative amount for a credit."
    },
    "unit_amount_decimal": {
      "type": "string",
      "title": "Unit amount decimal",
      "description": "Positive amount for a charge, negative amount for a credit."
    },
    "tax_inclusive": {
      "type": "boolean",
      "title": "Tax Inclusive?",
      "description": "Determines whether or not tax is included in the unit amount. The Tax Inclusive Pricing feature (separate from the Mixed Tax Pricing feature) must be enabled to utilize this flag."
    },
    "subtotal": {
      "type": "number",
      "format": "float",
      "title": "Total before discounts and taxes",
      "description": "`quantity * unit_amount`"
    },
    "discount": {
      "type": "number",
      "format": "float",
      "title": "Discount",
      "description": "The sum of all discounts applied to the line item."
    },
    "discounts": {
      "type": "array",
      "title": "Discounts",
      "description": "The breakdown of discounts applied to the line item by coupon redemption.",
      "items": {
        "$ref": "#/$defs/LineItemDiscount"
      }
    },
    "liability_gl_account_code": {
      "type": "string",
      "title": "Accounting code for the ledger account.",
      "description": "Unique code to identify the ledger account. Each code must start\nwith a letter or number. The following special characters are\nallowed: `-_.,:`\n",
      "pattern": "/^[A-Za-z0-9](( *)?[\\-A-Za-z0-9_.,:])*$/",
      "maxLength": 255
    },
    "revenue_gl_account_code": {
      "type": "string",
      "title": "Accounting code for the ledger account.",
      "description": "Unique code to identify the ledger account. Each code must start\nwith a letter or number. The following special characters are\nallowed: `-_.,:`\n",
      "pattern": "/^[A-Za-z0-9](( *)?[\\-A-Za-z0-9_.,:])*$/",
      "maxLength": 255
    },
    "performance_obligation_id": {
      "type": "string",
      "title": "Performance Obligation ID",
      "description": "The ID of a performance obligation. Performance obligations are\nonly accessible as a part of the Recurly RevRec Standard and\nRecurly RevRec Advanced features.\n",
      "maxLength": 13
    },
    "tax": {
      "type": "number",
      "format": "float",
      "title": "Tax",
      "description": "The tax amount for the line item."
    },
    "taxable": {
      "type": "boolean",
      "title": "Taxable?",
      "description": "`true` if the line item is taxable, `false` if it is not."
    },
    "tax_exempt": {
      "type": "boolean",
      "title": "Tax exempt?",
      "description": "`true` exempts tax on charges, `false` applies tax on charges. If not defined, then defaults to the Plan and Site settings. This attribute does not work for credits (negative line items). Credits are always applied post-tax. Pre-tax discounts should use the Coupons feature."
    },
    "avalara_transaction_type": {
      "type": "integer",
      "title": "Avalara Transaction Type",
      "description": "Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the line item is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types.",
      "minimum": 0
    },
    "avalara_service_type": {
      "type": "integer",
      "title": "Avalara Service Type",
      "description": "Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the line item is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types.",
      "minimum": 0
    },
    "vertex_transaction_type": {
      "$ref": "#/$defs/VertexTransactionTypeEnum"
    },
    "tax_code": {
      "type": "string",
      "maxLength": 50,
      "title": "Tax code",
      "description": "Optional field used by Avalara, Vertex, and Recurly's In-the-Box tax solution to determine taxation rules. You can pass in specific tax codes using any of these tax integrations. For Recurly's In-the-Box tax offering you can also choose to instead use simple values of `unknown`, `physical`, or `digital` tax codes."
    },
    "harmonized_system_code": {
      "type": "string",
      "title": "Harmonized System Code",
      "description": "The Harmonized System (HS) code is an internationally standardized system of names and numbers to classify traded products. The HS code, sometimes called Commodity Code, is used by customs authorities around the world to identify products when assessing duties and taxes. The HS code may also be referred to as the tariff code or customs code. Values should contain only digits and decimals.",
      "maxLength": 25,
      "pattern": "^\\d+(\\.\\d+)*$"
    },
    "tax_info": {
      "$ref": "#/$defs/TaxInfo"
    },
    "origin_tax_address_source": {
      "$ref": "#/$defs/OriginTaxAddressSourceEnum"
    },
    "destination_tax_address_source": {
      "$ref": "#/$defs/DestinationTaxAddressSourceEnum"
    },
    "proration_rate": {
      "type": "number",
      "format": "float",
      "title": "Proration rate",
      "description": "When a line item has been prorated, this is the rate of the proration. Proration rates were made available for line items created after March 30, 2017. For line items created prior to that date, the proration rate will be `null`, even if the line item was prorated.",
      "minimum": 0,
      "maximum": 1
    },
    "refund": {
      "type": "boolean",
      "title": "Refund?"
    },
    "refunded_quantity": {
      "type": "integer",
      "title": "Refunded Quantity",
      "description": "For refund charges, the quantity being refunded. For non-refund charges, the total quantity refunded (possibly over multiple refunds)."
    },
    "refunded_quantity_decimal": {
      "type": "string",
      "title": "Refunded Quantity Decimal",
      "description": "A floating-point alternative to Refunded Quantity. For refund charges, the quantity being refunded. For non-refund charges, the total quantity refunded (possibly over multiple refunds). The Decimal Quantity feature must be enabled to utilize this field."
    },
    "credit_applied": {
      "type": "number",
      "format": "float",
      "title": "Credit Applied",
      "description": "The amount of credit from this line item that was applied to the invoice."
    },
    "shipping_address": {
      "$ref": "#/$defs/ShippingAddress"
    },
    "start_date": {
      "type": "string",
      "format": "date-time",
      "title": "Start date",
      "description": "If an end date is present, this is value indicates the beginning of a billing time range. If no end date is present it indicates billing for a specific date."
    },
    "end_date": {
      "type": "string",
      "format": "date-time",
      "title": "End date",
      "description": "If this date is provided, it indicates the end of a time range."
    },
    "custom_fields": {
      "$ref": "#/$defs/CustomFields"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "title": "Created at",
      "description": "When the line item was created."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "title": "Last updated at",
      "description": "When the line item was last changed."
    }
  },
  "$defs": {
    "AccountMini": {
      "type": "object",
      "title": "Account mini details",
      "properties": {
        "id": {
          "type": "string",
          "maxLength": 13,
          "readOnly": true
        },
        "object": {
          "type": "string",
          "title": "Object type",
          "readOnly": true
        },
        "code": {
          "type": "string",
          "description": "The unique identifier of the account.",
          "maxLength": 50
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "The email address used for communicating with this customer.",
          "maxLength": 255
        },
        "first_name": {
          "type": "string",
          "maxLength": 255
        },
        "last_name": {
          "type": "string",
          "maxLength": 255
        },
        "company": {
          "type": "string",
          "maxLength": 255
        },
        "parent_account_id": {
          "type": "string",
          "maxLength": 13
        },
        "bill_to": {
          "type": "string",
          "maxLength": 6
        },
        "dunning_campaign_id": {
          "type": "string",
          "title": "Dunning Campaign ID",
          "description": "Unique ID to identify a dunning campaign. Used to specify if a non-default dunning campaign should be assigned to this account. For sites without multiple dunning campaigns enabled, the default dunning campaign will always be used."
        }
      }
    },
    "CustomField": {
      "type": "object",
      "title": "Custom field",
      "properties": {
        "name": {
          "type": "string",
          "title": "Field name",
          "description": "Fields must be created in the UI before values can be assigned to them.",
          "pattern": "/^[a-z0-9_-]+$/i",
          "maxLength": 50
        },
        "value": {
          "type": "string",
          "title": "Field value",
          "description": "Any values that resemble a credit card number or security code (CVV/CVC) will be rejected.",
          "maxLength": 255
        },
        "source_record_type": {
          "type": "string",
          "title": "Source record type",
          "description": "The type of record this custom field was automatically copied from. Only present when the field was copied from another record.",
          "readOnly": true,
          "$ref": "#/$defs/SourceRecordTypeEnum"
        },
        "source_record_id": {
          "type": "string",
          "title": "Source record ID",
          "description": "The UUID of the record this custom field was automatically copied from. Only present when the field was copied from another record.",
          "readOnly": true
        }
      },
      "required": [
        "name",
        "value"
      ]
    },
    "CustomFields": {
      "type": "array",
      "title": "Custom fields",
      "description": "The custom fields will only be altered when they are included in a request. Sending an empty array will not remove any existing values. To remove a field send the name with a null or empty value.",
      "items": {
        "$ref": "#/$defs/CustomField"
      }
    },
    "DestinationTaxAddressSourceEnum": {
      "type": "string",
      "title": "Destination tax address source",
      "description": "The source of the address that will be used as the destinaion in determining taxes. Available only when the site is on an Elite plan. A value of \"destination\" refers to the \"Customer tax address\". A value of \"origin\" refers to the \"Business entity tax address\".",
      "default": "destination",
      "enum": [
        "destination",
        "origin"
      ]
    },
    "FullCreditReasonCodeEnum": {
      "type": "string",
      "enum": [
        "general",
        "gift_card",
        "promotional",
        "refund",
        "service",
        "write_off"
      ]
    },
    "LegacyCategoryEnum": {
      "type": "string",
      "enum": [
        "applied_credit",
        "carryforward",
        "charge",
        "credit"
      ]
    },
    "LineItemDiscount": {
      "type": "object",
      "title": "Line item discount",
      "description": "A discount applied to a line item charge by a coupon redemption.",
      "properties": {
        "object": {
          "type": "string",
          "title": "Object type",
          "description": "Will always be `line_item_discount`.",
          "readOnly": true
        },
        "coupon_id": {
          "type": "string",
          "title": "Coupon ID",
          "description": "The ID of the coupon that generated this discount.",
          "readOnly": true
        },
        "coupon_redemption_id": {
          "type": "string",
          "title": "Coupon Redemption ID",
          "description": "The ID of the coupon redemption that generated this discount.",
          "readOnly": true
        },
        "order_applied": {
          "type": "integer",
          "title": "Order applied",
          "description": "The order in which this discount was applied when multiple coupons were redeemed.",
          "readOnly": true
        },
        "discount_amount": {
          "type": "number",
          "format": "float",
          "title": "Discount amount",
          "description": "The amount discounted on this line item by this coupon redemption.",
          "readOnly": true
        },
        "currency": {
          "type": "string",
          "title": "Currency",
          "description": "3-letter ISO 4217 currency code.",
          "maxLength": 3,
          "readOnly": true
        }
      }
    },
    "LineItemOriginEnum": {
      "type": "string",
      "enum": [
        "add_on",
        "add_on_trial",
        "carryforward",
        "coupon",
        "credit",
        "debit",
        "one_time",
        "plan",
        "plan_trial",
        "setup_fee",
        "prepayment"
      ]
    },
    "LineItemRevenueScheduleTypeEnum": {
      "type": "string",
      "enum": [
        "at_invoice",
        "at_range_end",
        "at_range_start",
        "evenly",
        "never"
      ]
    },
    "LineItemStateEnum": {
      "type": "string",
      "enum": [
        "invoiced",
        "pending"
      ]
    },
    "LineItemTypeEnum": {
      "type": "string",
      "enum": [
        "charge",
        "credit"
      ]
    },
    "OriginTaxAddressSourceEnum": {
      "type": "string",
      "title": "Origin tax address source",
      "description": "The source of the address that will be used as the origin in determining taxes. Available only when the site is on an Elite plan. A value of \"origin\" refers to the \"Business entity tax address\". A value of \"destination\" refers to the \"Customer tax address\".",
      "default": "origin",
      "enum": [
        "origin",
        "destination"
      ]
    },
    "ShippingAddress": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "title": "Shipping Address ID",
          "maxLength": 13,
          "readOnly": true
        },
        "object": {
          "type": "string",
          "title": "Object type",
          "readOnly": true
        },
        "account_id": {
          "type": "string",
          "title": "Account ID",
          "maxLength": 13,
          "readOnly": true
        },
        "nickname": {
          "type": "string",
          "maxLength": 255
        },
        "first_name": {
          "type": "string",
          "maxLength": 255
        },
        "last_name": {
          "type": "string",
          "maxLength": 255
        },
        "company": {
          "type": "string",
          "maxLength": 255
        },
        "email": {
          "type": "string",
          "maxLength": 255
        },
        "vat_number": {
          "type": "string",
          "maxLength": 20
        },
        "phone": {
          "type": "string",
          "maxLength": 30
        },
        "street1": {
          "type": "string",
          "maxLength": 255
        },
        "street2": {
          "type": "string",
          "maxLength": 255
        },
        "city": {
          "type": "string",
          "maxLength": 255
        },
        "region": {
          "type": "string",
          "maxLength": 255,
          "description": "State or province."
        },
        "postal_code": {
          "type": "string",
          "maxLength": 20,
          "description": "Zip or postal code."
        },
        "country": {
          "type": "string",
          "maxLength": 50,
          "description": "Country, 2-letter ISO 3166-1 alpha-2 code."
        },
        "geo_code": {
          "type": "string",
          "maxLength": 20,
          "description": "Code that represents a geographic entity (location or object). Only returned when Vertex or Avalara for Communications is enabled."
        },
        "created_at": {
          "type": "string",
          "title": "Created at",
          "format": "date-time",
          "readOnly": true
        },
        "updated_at": {
          "type": "string",
          "title": "Updated at",
          "format": "date-time",
          "readOnly": true
        }
      }
    },
    "SourceRecordTypeEnum": {
      "type": "string",
      "description": "The type of record a custom field was automatically copied from.",
      "enum": [
        "account",
        "plan",
        "product",
        "subscription"
      ]
    },
    "TaxDetail": {
      "type": "object",
      "title": "Tax detail",
      "properties": {
        "type": {
          "type": "string",
          "title": "Type",
          "description": "Provides the tax type for the region or type of Comminications tax when Avalara for Communications or Vertex is enabled. For Canadian Sales Tax, this will be GST, HST, QST or PST."
        },
        "region": {
          "type": "string",
          "title": "Region",
          "description": "Provides the tax region applied on an invoice. For Canadian Sales Tax, this will be either the 2 letter province code or country code. Not present when Avalara for Communications is enabled."
        },
        "rate": {
          "type": "number",
          "format": "float",
          "title": "Rate",
          "description": "Provides the tax rate for the region."
        },
        "tax": {
          "type": "number",
          "format": "float",
          "title": "Tax",
          "description": "The total tax applied for this tax type."
        },
        "name": {
          "type": "string",
          "title": "Name",
          "description": "Provides the name of the Communications tax applied. Present only when Avalara for Communications or Vertex is enabled."
        },
        "level": {
          "type": "string",
          "title": "Level",
          "description": "Provides the jurisdiction level for the Communications tax applied. Example values include city, state and federal. Present only when Avalara for Communications or Vertex is enabled."
        },
        "billable": {
          "type": "boolean",
          "title": "Billable",
          "description": "Whether or not the line item is taxable. Only populated for a single LineItem fetch when Avalara for Communications or Vertex is enabled."
        }
      }
    },
    "TaxInfo": {
      "type": "object",
      "title": "Tax info",
      "description": "Only for merchants using Recurly's In-The-Box taxes.",
      "properties": {
        "type": {
          "type": "string",
          "title": "Type",
          "description": "Provides the tax type as \"vat\" for EU VAT, \"usst\" for U.S. Sales Tax, or the 2 letter country code for country level tax types like Canada, Australia, New Zealand, Israel, and all non-EU European countries. Not present when Avalara for Communications is enabled."
        },
        "region": {
          "type": "string",
          "title": "Region",
          "description": "Provides the tax region applied on an invoice. For U.S. Sales Tax, this will be the 2 letter state code. For EU VAT this will be the 2 letter country code. For all country level tax types, this will display the regional tax, like VAT, GST, or PST. Not present when Avalara for Communications is enabled."
        },
        "rate": {
          "type": "number",
          "format": "float",
          "title": "Rate",
          "description": "The combined tax rate. Not present when Avalara for Communications is enabled."
        },
        "tax_details": {
          "type": "array",
          "description": "Provides additional tax details for Communications taxes when Avalara for Communications or Vertex Tax Breakdown is enabled or Canadian Sales Tax. Tax details will only be populated for the Invoice response when fetching a single invoice and not for the InvoiceList or LineItemList. Only populated for a single LineItem fetch when Avalara for Communications is enabled.",
          "items": {
            "$ref": "#/$defs/TaxDetail"
          }
        }
      }
    },
    "VertexTransactionTypeEnum": {
      "type": "string",
      "title": "Vertex Transaction Type",
      "description": "Used by Vertex for tax calculations. Possible values are sale, rental, lease.",
      "enum": [
        "sale",
        "rental",
        "lease"
      ]
    }
  }
}