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 users 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 200 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. Multicapture also works with payment line items. However, you can’t use other 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 Commercial Enhanced Data Program (CEDP), which replaces their U.S. Level 2/3 interchange programs, including information about its network fees, see the CEDP Support article.

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 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, 8398, 4468, 5499, 5541, 5542, 5983 For Visa: 5812, 5814, 3501-4010, 3351-3500, 7512, 7513, 3000-3299, 4511, 4411, 4112, 4722, 5962, 5966, and 5967
Sales tax requirement	For Mastercard: sales tax must be between 0.1% and 30%, unless the business is using 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 For Visa: sales tax must be between 0.1% and 22% unless the business is using one of the following MCCs - 4468, 5499, 5541, 5542, or 5983	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()!@:%_\+.~#?&\/\/=]*)`
amount_details[line_items][0][payment_method_options][klarna][subscription_reference]	string	Arbitrary identifier of your choosing to describe a subscription. Used in select Klarna recurring integrations. This isn’t visible to customers.	Max 255 characters. No special regex.

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
Select a languagecURL
 No results
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": 4000,
  "currency": "usd"
  "amount_details": {
    "shipping": {
      "from_postal_code": "94110",
      "to_postal_code": "94117",
      "amount": 100
    },
    "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": 100,
          "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,
          "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",
  "amount": 2500,
  "amount_capturable": 0,
  "amount_received": 2500,
  "payment_details": {
    "customer_reference": "customer_reference",
    "order_reference": "order_reference"
  },
  "amount_details": {
    "discount_amount": 100,
    "shipping": {
      "amount": 100,
      "from_postal_code": "94110",
      "to_postal_code": "94117"
    },
    "tax": {
      "total_tax_amount": 500
    },
    "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"
    }
  }
  ...
}

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

Using Flexible Payment Scenarios

Multicapture

You can also pass in line items during multicaptures.

Note

Multicapture isn’t supported for Klarna or PayPal.

Create and confirm an uncaptured PaymentIntent

Note

The API response doesn’t include line items by default. To return line items, expand amount_details.line_items.

Specify the capture_method as manual when creating the PaymentIntent and use the if_available parameter to request multicapture for this payment. The created PaymentIntent allows multiple captures if the payment method supports it.

In the response, the amount_details field contains the line items specified on the PaymentIntent.

{
  amount: 4600,
  amount_capturable: 4600,
  amount_received: 0,
  payment_details: {
    customer_reference: "customer_reference",
    order_reference: "order_reference"
  },
  amount_details: {
    discount_amount: 200,
    tax: {
      total_tax_amount: 400
    },
    shipping: {
      from_postal_code: "94110",
      to_postal_code: "94117",
      amount: 400
    },
    line_items: [
      {
        product_code: "SKU001",
        product_name: "Product 001",
        unit_cost: 2000,
        quantity: 1,
        unit_of_measure: "feet",
        payment_method_options: {
          card: {
            commodity_code: "123123"
          }
        }
      },
      {
        product_code: "SKU002",
        product_name: "Product 002",
        unit_cost: 2000,
        quantity: 1,
        unit_of_measure: "gallons",
        payment_method_options: {
          card: {
            commodity_code: "123123"
          }
        }
      }
    ]
  }
  ...
}

Capture the PaymentIntent

You can add amount_details on the first capture even if they weren’t specified at creation.
If you provided amount_details at creation, you must either pass in amount_details or unset them on the first capture.

The same rules apply to amount_details[line_items]—you can add them on the first capture if not specified at creation, but must include or explicitly unset them if they were present at creation.

In the response, the amount_details field contains the line items specified on the first capture.

{
  amount: 4600,
  amount_capturable: 2300,
  amount_received: 2300,
  payment_details: {
    customer_reference: "customer_reference",
    order_reference: "order_reference"
  },
  amount_details: {
    discount_amount: 100,
    tax: {
      total_tax_amount: 200
    },
    shipping: {
      from_postal_code: "94110",
      to_postal_code: "94117",
      amount: 200
    },
    line_items: [
      {
        product_code: "SKU001",
        product_name: "Product 001",
        unit_cost: 2000,
        quantity: 1,
        unit_of_measure: "feet",
        payment_method_options: {
          card: {
            commodity_code: "123123"
          }
        }
      }
    ]
  },
  status: "requires_capture"
  ...
}

The PaymentIntent remains in a requires_capture state. At this point, you can either:

Continue to capture the PaymentIntent multiple times up to the full amount of the PaymentIntent.
Transition the PaymentIntent to a succeeded state by setting final_capture to true, or making a capture without the final_capture parameter (because final_capture defaults to true).

If previous captures included amount_details or amount_details[line_items], you must continue to include them in subsequent captures.
If previous captures didn’t include these fields, you can’t add them in later captures.

In the response, the amount_details field contains the line items from the first two captures, according to the following rules:

discount_amount, tax.total_tax_amount and shipping.amount are summed across captures.
shipping.from_postal_code and shipping.to_postal_code might be omitted in the captures, but if it’s provided, you must not change it across captures.
line_items will be aggregated across captures.

{
  amount: 4600,
  amount_capturable: 0,
  amount_received: 4600,
  payment_details: {
    customer_reference: "customer_reference",
    order_reference: "order_reference"
  },
  amount_details: {
    discount_amount: 200,
    tax: {
      total_tax_amount: 400
    },
    shipping: {
      from_postal_code: "94110",
      to_postal_code: "94117",
      amount: 400
    },
    line_items: [
      {
        product_code: "SKU001",
        product_name: "Product 001",
        unit_cost: 2000,
        quantity: 1,
        unit_of_measure: "feet",
        payment_method_options: {
          card: {
            commodity_code: "123123"
          }
        }
      },
      {
        product_code: "SKU002",
        product_name: "Product 002",
        unit_cost: 2000,
        quantity: 1,
        unit_of_measure: "gallons",
        payment_method_options: {
          card: {
            commodity_code: "123123"
          }
        }
      }
    ]
  },
  status: "succeeded"
  ...
}