Payments Line ItemsPrivate preview

Send additional transaction metadata across supported Payment Method Types to access cost savings, facilitate payment reconciliation, and improve auth rates.

Contact to enable

Contact your sales representative or support to enable this private preview feature.

Payment Line Items is a feature in the Payment Intents API that provides benefits for cards and local payment methods processing.

Cost savings for eligible commercial cards for IC+ users: By passing Payment Line Items, you can participate in the Level 2/Level 3 (L2/L3) program that major card networks administer. For eligible commercial cards, passing line item data can provide interchange fee savings.
Facilitate reconciliation: In cases where there are no cost savings, passing line item data can facilitate reconciliation for your customers. For example, if you primarily serve government customers, it will aid the customer in reconciling a purchase against what shows up on their statement.
Improved authorization rates: Payment methods like PayPal and Klarna use line item data in their underwriting models, potentially allowing them to approve more payments when line items data is passed.

Feature restrictions

Payment Line Items have the following restrictions across supported payment method types:

	Cards L2/L3 program	Klarna	PayPal
Geographic availability	Only supported for US domestic transactions (US user accepting US issued cards, excluding US territories)	Supported for all payments, regardless of business or customer location	Supported for all payments, regardless of business or customer location
Card networks	Only supported for Visa, Mastercard, and American Express (cost savings requires direct agreement with American Express)	Not applicable	Not applicable
Number of Line Items	Currently supports 100 line items (maximum of 4 line items for American Express)	Same as cards	Same as cards
Feature compatibility	Only auto and separate authorization and capture modes work with Payment Line Items. You can’t currently use flexible payment scenarios or decremental authorization for transactions where you’re passing in Payment Line Items.	Same as cards	Same as cards
Industry specific metadata	You can’t send line items alongside industry specific metadata (such as car rental/lodging, and airlines).	Same as cards. Klarna supports industry specific metadata with Extra Merchant Data.	Same as cards
Surfaces	Only available for payments made through the PaymentIntents API.	Same as cards	Same as cards

Cards L2/L3 Rates Eligibility

See Industry to MCC codes to see what MCC your business might fall under.

Stripe API doesn’t reject line items that don’t meet the network MCC or tax requirements. However, these transactions don’t qualify for the corresponding Level 2/3 savings.

Cards L2/L3 Rates Eligibility	Level 2	Level 3
Card types	Only Business, Purchasing, and Corporate cards are eligible	Only Purchasing and Corporate cards are eligible
MCCs	Users with the following MCCs aren’t eligible for Level II: For Mastercard: 5812, 3501-3999, 7011, 3351-3500, 7512, 7513, 7519, 3000-3299, 4511, 4112, 8398, 4468, 5541, 5542, 5499, 5983 For Visa: 5812, 5814, 3501-4010, 3351-3500, 7512, 7513, 3000-3299, 4511, 4411, 4112, 4722, 5962, 5966, and 5967	Users with the following MCCs aren’t eligible for Level III: For Mastercard: 5812, 3501-3999, 7011, 3351-3500, 7512, 7513, 7519, 3000-3299, 4511, 4112 For Visa: 5812, 5814, 3501-4010, 3351-3500, 7512, 7513, 3000-3299, 4511, 4411, 4112, 4722, 5962, 5966, and 5967
Sales tax requirement	For Visa: sales tax must be between 0.1% and 22% unless the business is one of the following MCCs - 4468, 5499, 5541, 5542, and 5983 For Mastercard: sales tax must be between 0.1% and 30%, unless the business is in one of the following MCCs - 4468, 5541, 5542, 5499, 5983, 7511, 9752, 4111, 4131, 4215, 4784, 8211, 8220, 8398, 8661, 9211, 9222, 9311, 9399, 9402	Not applicable

Field Requirements

All the fields mentioned below are passed inside amount_details. Refer to Sample request (Level II data) to learn about passing data.

Cards Supported fields

Private preview

Two more fields [Commodity Code] and [Unit of Measure] aren’t yet available in private preview, but will become required for the Visa CEDP program (refer to Network Cost Updates for Feb 20, 2025).

Field Name	Type	Values / Restrictions	Description	Required For L2/L3	Required API Fields
payment_details[customer_reference]	string	This field isn’t available for non-card payments.	Some customers might be required by their company or organization to provide this information. If so, provide this value. Otherwise you can ignore this field.
payment_details[order_reference]	string	This field isn’t available for non-card payments. If automatic_payment_methods.enabled is set to `true`, you must set this field as Card is a default Payment Method.	A unique value assigned by the business to identify the transaction.	✅ L2/L3
discount_amount	number	Value must be > 0	The total discount applied on the transaction.
shipping[to_postal_code]	string	Max length 10 chars. Value must be alphanumeric characters	If a physical good is being shipped, the postal code of where it’s being shipped to.
shipping[from_postal_code]	string	Max length 10 chars. Value must be alphanumeric characters	If a physical good is being shipped, the postal code of where it’s being shipped from.
shipping[amount]	number	Value must be >= 0	If a physical good is being shipped, the cost of shipping.
tax[total_tax_amount]	number	Value must be >= 0	The total amount of tax on the transaction.	✅ L2
line_items[tax][total_tax_amount]	number	Value must be >= 0	The total amount of tax on a single line item.	✅ L3
line_items[product_name]	string	Max length 100 chars	The product name of the line item.	✅ L3	✅
line_items[product_code]	string	Max length 12 chars	The product code of the line item, such as an SKU.	✅ L3
line_items[unit_cost]	number	Value must be >= 0	The unit cost of the line item.	✅ L3	✅
line_items[quantity]	number	Value must be > 0	The quantity of items.	✅ L3	✅
line_items[discount_amount]	number	Value must be > 0	The discount applied on this line item.

Note

The following fields are mutually exclusive; you can provide only one in a request:

Either tax[total_tax_amount] or line_items[tax][total_tax_amount]
Either discount_amount or line_items[discount_amount]

Additional Klarna supported fields

Klarna supports the above fields for cards, and in addition, also supports:

Field Name	Type	Values and Restrictions	Description	Required
line_items[pmo][klarna][product_url]	string	Max 1024 characters. Rough Regex: `https?:\/\/[-a-zA-Z0-9@:%._\+~#=]{1,256}\.[a-zA-Z0-9()]{1,64}\b([-a-zA-Z0-9()!@:%_\+.~#?&\/\/=]*)`	Valid http or https URL of the product
line_items[pmo][klarna][image_url]	string	Max 1024 characters. Rough Regex: `https?:\/\/[-a-zA-Z0-9@:%._\+~#=]{1,256}\.[a-zA-Z0-9()]{1,64}\b([-a-zA-Z0-9()!@:%_\+.~#?&\/\/=]*)`	Valid http or https URL of the image

Note

For Klarna transactions, total amount is implicitly derived from the formula (unit_cost * quantity) - discount_amount + tax.total_tax_amount. There is no explicit field to pass the amount.

Additional PayPal Supported Fields

PayPal supports the above fields for cards, and in addition, also supports:

Field Name	Type	Values / Restrictions	Description
line_items[pmo][paypal][description]	string	Max 127 characters	Description of the line item.
line_items[pmo][paypal][category]	enum	digital_goods, physical_goods, donation	Type of the line item.
line_items[pmo][paypal][sold_by]	string	Max 127 characters	The Stripe account ID of the connected account that sells the item.

Cards-specific Line Items for L2/L3 rates

Pass in required data for eligible cards to qualify for L2/L3 network programs

Level II: sales tax charged on transactions
Level III: line item level breakdown such as product code, quantity, unit cost

Sample request (Level II data)

Sample response

{
  id: "pi_3OoMm5BLxXjrKOiR3LRyi610",
  amount: 4600,
  currency: "usd"
  amount_details: {
    tax: {
      total_tax_amount: 500
    },
  },
  status: "requires_payment_method"
}

Payment Intent Confirmation

PaymentIntent capture

Capture the PaymentIntent separately after confirmation by passing in manual_capture: true during PaymentIntent Creation or Confirmation, and then call the Capture endpoint separately.

Pass in an updated amount_details hash during Capture if needed.

Payment Method Specific Line Items

Pass in additional payment method types on a per-line-item basis all in one place. You can pass in data related to payment methods you might not be confirming with as well, as long as the parameter is supported. This can simplify your integration, without requiring engineering effort to add and remove payment method specific fields for each payment method.

Note

Line items are not included by default in the API response. To return line items, expand amount_details.line_items

Sample request

Command Line
cURL
curl https://api.stripe.com/v1/payment_intents \
  -u "sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=4600 \
  -d currency=usd \
  -d "payment_method_types[0]"=card \
  -d "payment_method_types[1]"=paypal \
  -d "payment_method_types[2]"=klarna \
  -d "payment_details[customer_reference]"=customer_reference \
  -d "payment_details[order_reference]"=order_reference \
  -d "amount_details[discount_amount]"=0 \
  -d "amount_details[shipping][from_postal_code]"=94110 \
  -d "amount_details[shipping][to_postal_code]"=94117 \
  -d "amount_details[shipping][amount]"=100 \
  -d "amount_details[tax][total_tax_amount]"=500 \
  -d "amount_details[line_items][0][product_code]"=SKU001 \
  -d "amount_details[line_items][0][product_name]"="Product 001" \
  -d "amount_details[line_items][0][unit_cost]"=2000 \
  -d "amount_details[line_items][0][quantity]"=1 \
  -d "amount_details[line_items][0][discount_amount]"=0 \
  -d "amount_details[line_items][0][tax][total_tax_amount]"=100 \
  --data-urlencode "amount_details[line_items][0][payment_method_options][klarna][image_url]"="https://www.example.com/image.jpg" \
  --data-urlencode "amount_details[line_items][0][payment_method_options][klarna][product_url]"="https://www.example.com/product" \
  -d "amount_details[line_items][0][payment_method_options][paypal][description]"="This is a sample product description unique to PayPal for SKU001" \
  -d "amount_details[line_items][0][payment_method_options][paypal][category]"=digital_goods \
  -d "amount_details[line_items][1][product_code]"=SKU002 \
  -d "amount_details[line_items][1][product_name]"="Product 002" \
  -d "amount_details[line_items][1][unit_cost]"=1800 \
  -d "amount_details[line_items][1][quantity]"=1 \
  -d "amount_details[line_items][1][discount_amount]"=0 \
  -d "amount_details[line_items][1][tax][total_tax_amount]"=100 \
  --data-urlencode "amount_details[line_items][1][payment_method_options][klarna][image_url]"="https://www.example.com/image.jpg" \
  --data-urlencode "amount_details[line_items][1][payment_method_options][klarna][product_url]"="https://www.example.com/product" \
  -d "amount_details[line_items][1][payment_method_options][paypal][description]"="This is a sample product description unique to PayPal for SKU002" \
  -d "amount_details[line_items][1][payment_method_options][paypal][category]"=physical_goods \
  -d "expand[0]"="amount_details.line_items"

Sample response

{
  id: "pi_3OoMm5BLxXjrKOiR3LRyi610",
  amount: 4600,
  currency: "usd"
  amount_details: {
    shipping: {
      from_postal_code: "94110",
      to_postal_code: "94117",
      amount: 100
    },
    tax: {
      total_tax_amount: 500
    },
    line_items: {
      object: "list",
      url: "/v1/payment_intents/pi_3OoMm5BLxXjrKOiR3LRyi610/amount_details_line_items",
      has_more: false,
      data: [{
          _id: "li_123",
          product_code: "SKU001",
          product_name: "Product 001",
          unit_cost: 2000,
          quantity: 1,
          discount_amount: 0,
          tax: {
            total_tax_amount: 100
          },
          payment_method_options: {
            klarna: {
              image_url: "https://www.example.com/image.jpg",
              product_url: "https://www.example.com/product"
            },
            paypal: {
              description: "This is a sample product description unique to PayPal for SKU001",
              category: digital_goods,
            }
          }
        },
        {
          _id: "li_456",
          product_code: "SKU002",
          product_name: "Product 002",
          unit_cost: 1800,
          quantity: 1,
          discount_amount: 0,
          tax: {
            total_tax_amount: 100
          },
          payment_method_options: {
            klarna: {
              image_url: "https://www.example.com/image.jpg",
              product_url: "https://www.example.com/product"
            },
            paypal: {
              description: "This is a sample product description unique to PayPal for SKU001",
              category: physical_goods,
            }
          }
        }
      ]
    }
  },
  status: "requires_payment_method"
}

Industry to MCC codes

Category	Description
Food & Beverage	5812: Restaurants (not fast food) 5814: Fast Food Restaurants
Hospitality & Travel	3000-3299: Airlines 3501-3999, 7011: Hotels & Lodging 3351-3500: Car Rental Agencies 4722: Travel Agencies and Tour Operators 7512: Automobile Rental Agency 7513: Truck Rental and Leasing 7519: Motor Home and Recreational Vehicle Rental 4411: Cruise Lines 4112: Passenger Railways 4111: Local and Suburban Commuter Transit 4215: Courier Services 4784: Bridge and Road Fees 4468: Marinas, Marine Service 5983: Fuel Dealers
Retail & E-Commerce	5962: Direct Marketing—Travel 5966: Direct Marketing—Outbound Telemarketing 5967: Direct Marketing—Other
Utilities & Miscellaneous	8398: Charitable and Social Service Organizations 9752: U.K. Petrol Stations, Electronic Hot File 9211: Court Costs, including Alimony and Child Support 9311: Tax Payments 9222: Fines 9402: Postal Services – Government Only and other similar services 9399: Government Services (Not Elsewhere Classified) and other similar services 8661: Religious Organizations 8211: Schools and Educational Institutions 8220: Colleges, Universities