Payment line itemsPublic preview

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

Available with preview header

You can use this public-preview feature by including the version header 2025-04-30.preview or higher in your API request.

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: Passing line item data can also 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 Klarna and PayPal use line item data in their underwriting models, potentially allowing them to approve more credit based payment options 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).	Klarna is a global payment method. For business location support, see Klarna payments.	Available for customers in all locations. For business location support, see PayPal payments.
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. (American Express Specification restricts us to send them only the first 4 line items.)	Same as cards	Same as cards
Feature compatibility	Both automatic capture and manual capture modes work with payment line items. You can’t currently use flexible payment scenarios or decrement authorization for payments where you’re passing in line items.	Both automatic capture and manual capture modes work with payment line items.	Both automatic capture and manual capture modes work with payment line items.
Industry specific metadata	You can’t send line items alongside industry specific metadata such as car rental/lodging, and airlines	Klarna supports industry specific metadata with Extra Merchant Data (private preview).	Same as cards
Surfaces	Available for payments made through the PaymentIntents API.	Same as cards	Same as cards

Cards L2/L3 Rates Eligibility

Visa CEDP Program

To learn more about Visa’s introduction of a new program called Commercial Enhanced Data Program (CEDP) in replacement of their existing U.S. Level 2/3 interchange programs as well as the additional network fees that apply, refer to the Network Cost Updates for Feb 20, 2025.

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 and/or tax requirements, but 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 2: 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 3: 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, or 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, or 9402	Not applicable
Minimum Field Requirements	tax[total_tax_amount] payment_details[order_reference]	line_item[product_name] line_item[unit_cost] line_item[quantity] line_item[tax][total_tax_amount] line_item[product_code] line_items[unit_of_measure] payment_details[order_reference]

Field Requirements

All the fields mentioned below are passed within the amount_details or payment_details parameters. Refer to Sample request (Level 2 data) to learn about passing data.

General supported fields

Field Name	Type	Description	Format
line_item[product_name]	string	The product name of the line item.	Required field Required for L3 Max length 1024 chars (Cards truncates to 26 characters and Paypal truncates to 127 characters)
line_item[unit_cost]	integer	The unit cost of the line item represented in the smallest currency unit	Required field Required for L3 Value must be >= 0
line_item[quantity]	integer	The quantity of items.	Required field Required for L3 Value must be > 0
line_item[tax][total_tax_amount]	integer	The total amount of tax on a single line item represented in the smallest currency unit	Required for L3 Value must be >= 0 Conditional validation ¹
line_item[product_code]	string	The product code of the line item, such as an SKU	Required for L3 Max length 12 chars
line_items[unit_of_measure]	string	A unit of measure for the line item, such as gallons, feet, meters, and so on	Required for L3 Max length 12 chars Alphanumeric
payment_details[order_reference]	string	A unique value assigned by the business to identify the transaction.	Conditionally required ³ Required for L3 Required for L2 Before we send this string to a card network, we truncate it to 25 alphanumeric characters, excluding spaces
tax[total_tax_amount]	integer	The total amount of tax on the transaction represented in the smallest currency unit	Required for L2 Value must be >= 0 Conditional validation ¹
payment_details[customer_reference]	string	A unique value to identify the customer. This field is available only for card payments	Before we send this string to a card network, we truncate it to 25 alphanumeric characters, excluding spaces
shipping[to_postal_code]	string	If a physical good is being shipped, the postal code of where it’s being shipped to	Max length 10 chars Alphanumeric
shipping[from_postal_code]	string	If a physical good is being shipped, the postal code of where it’s being shipped from	Max length 10 chars Alphanumeric
shipping[amount]	integer	If a physical good is being shipped, the cost of shipping represented in the smallest currency unit	Value must be >= 0
discount_amount	integer	The total discount applied on the transaction represented in the smallest currency unit	Value must be > 0 Conditional validation ²
line_item[discount_amount]	integer	The discount applied on this line item represented in the smallest currency unit	Value must be > 0 Conditional validation ²

¹ tax[total_tax_amount] and line_items[tax][total_tax_amount] are mutually exclusive. You can only specify one or the other.

² discount_amount and line_items[discount_amount] are mutually exclusive. You can only specify one or the other.

³ The field payment_details[order_reference] is required when the Payment Method Types array contains card, including when automatic_payment_methods.enabled is set to true.

Additional Cards supported fields

Cards supports the preceding general fields, and also supports:

Field Name	Type	Description	Format
line_items[payment_method_options][card][commodity_code]	string	Identifier that categorizes the items being purchased using a standardized commodity scheme, such as (but not limited to): UNSPSC, NAICS, NAPCS, and so on.	Max length 12 chars. Value must be alphanumeric characters without spaces.

Additional Klarna supported fields

Klarna supports the preceding general fields, and also supports:

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

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 preceding general fields, and also supports:

Field Name	Type	Description	Format
line_items[payment_method_options][paypal][description]	string	Description of the line item.	Max 127 characters
line_items[payment_method_options][paypal][category]	enum	Type of the line item.	digital_goods, physical_goods, donation
line_items[payment_method_options][paypal][sold_by]	string	The Stripe account ID of the connected account that sells the item. Leave blank if you are not a connected account.	Max 127 characters

Cards-specific line items for L2/L3 rates

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

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

Sample request (Level 2 data)

Sample response (Level 2 data)

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

PaymentIntent Operations

You can pass line items during both confirmation and capture.

Set line items during Confirmation

You can set line items during confirmation regardless of the capture_method you choose. If you pass line items during confirmation, then capture separately, you don’t need to pass line items again.

Set line items during Capture

If you don’t specify line items during confirmation, you can pass them during capture.

Note

Not supported when using PayPal

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 (with Payment Method Specific line items)

Command Line
cURL
curl https://api.stripe.com/v1/payment_intents \
  -u "sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=4000 \
  -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[shipping][from_postal_code]"=94110 \
  -d "amount_details[shipping][to_postal_code]"=94117 \
  -d "amount_details[shipping][amount]"=100 \
  -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][discount_amount]"=100 \
  -d "amount_details[line_items][0][quantity]"=1 \
  -d "amount_details[line_items][0][tax][total_tax_amount]"=100 \
  -d "amount_details[line_items][0][unit_of_measure]"=feet \
  -d "amount_details[line_items][0][payment_method_options][card][commodity_code]"=123123 \
  --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][tax][total_tax_amount]"=100 \
  -d "amount_details[line_items][1][unit_of_measure]"=gallons \
  -d "amount_details[line_items][1][payment_method_options][card][commodity_code]"=123123 \
  --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 (with Payment Method Specific line items)

{
  id: "pi_3OoMm5BLxXjrKOiR3LRyi610",
  amount: 4600,
  currency: "usd"
  amount_details: {
    discount_amount: 100,
    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
          },
          unit_of_measure: "feet",
          payment_method_options: {
            card: {
              commodity_code: "123123",
            },
            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
          },
          unit_of_measure: "gallons",
          payment_method_options: {
            card: {
              commodity_code: "123123",
            },
            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"
}

Using top-level discount and/or tax

The following example shows passing the top-level discount_amount and tax without line item level tax and discount_amount

Sample request (top-level discount and/or tax)

Sample response (top-level discount and/or tax)

{
  "id": "pi_3R0p2JCvDOElLqwO0mlHFrzv",
  "object": "payment_intent",
  "amount": 2500,
  "amount_capturable": 0,
  "amount_details": {
    "discount_amount": 100,
    "line_items": {
      "object": "list",
      "data": [
        {
          "id": "uli_RueKif6jOR65uG",
          "object": "amount_details_line_item",
          "discount_amount": null,
          "payment_method_options": {
            "klarna": {
              "image_url": "https://www.example.com/image.jpg",
              "product_url": "https://www.example.com/product"
            },
            "paypal": {
              "category": "digital_goods",
              "description": "This is a sample product description unique to PayPal for SKU001"
            }
          },
          "product_code": "SKU001",
          "product_name": "Product 001",
          "quantity": 1,
          "tax": null,
          "unit_cost": 2000
        }
      ],
      "has_more": false,
      "url": "/v1/payment_intents/pi_3R0p2JCvDOElLqwO0mlHFrzv/amount_details_line_items"
    },
    "shipping": {
      "amount": 100,
      "from_postal_code": "94110",
      "to_postal_code": "94117"
    },
    "tax": {
      "total_tax_amount": 500
    },
    "tip": {}
  },
  "amount_received": 0,
  "amount_subtotal": 2500,
  "capture_method": "automatic_async",
  "payment_details": {
    "customer_reference": "customer_reference",
    "order_reference": "order_reference"
  },
  "payment_method": null,
  "payment_method_configuration_details": null,
  "payment_method_options": {
    "card": {
      "installments": null,
      "mandate_options": null,
      "network": null,
      "request_three_d_secure": "automatic"
    },
    "klarna": {
      "preferred_locale": null
    },
    "paypal": {
      "preferred_locale": null,
      "reference": null
    }
  },
  "payment_method_types": ["card", "paypal", "klarna"],
  ...
}

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