如何在Stripe Checkout的相同价格ID line_items中添加额外字段？

Stripe Checkout的line_items数组本身不支持直接添加自定义字段（比如你代码里的additional_field），直接传入会被API忽略。不过有几种可行的替代方案来实现类似需求：

方案1：将行项目附加信息存入Session的Metadata #

把每个行项目的额外信息结构化后存入Checkout Session的全局metadata字段，支付完成后通过Webhook或Session详情获取解析。示例代码：

$stripe = new \Stripe\StripeClient('...');

// 定义行项目
$lineItems = [
    [
        'price' => 'price_...',
        'quantity' => 1,
    ],
    [
        'price' => 'price_...',
        'quantity' => 2,
    ]
];

// 构建行项目对应的附加信息，用索引关联
$lineItemDetails = [
    '0' => ['additional_field' => 'value_for_item_1'],
    '1' => ['additional_field' => 'value_for_item_2']
];

$stripe->checkout->sessions->create([
    'success_url' => 'https://example.com/success',
    'line_items' => $lineItems,
    'mode' => 'payment',
    'metadata' => [
        'line_item_extra' => json_encode($lineItemDetails)
    ]
]);

后续通过checkout.session.completed等Webhook事件获取Session数据后，解析metadata.line_item_extra即可对应到每个行项目的附加信息。

方案2：为不同附加信息创建独立Price对象 #

基于同一个产品创建多个Price，每个Price携带专属的metadata，这样相同基础价格的行项目可以通过不同Price区分附加信息。示例代码：

$stripe = new \Stripe\StripeClient('...');

// 创建带自定义metadata的Price（复用同一个产品）
$priceWithExtra1 = $stripe->prices->create([
    'product' => 'prod_...',
    'unit_amount' => 1000, // 和目标价格一致的金额
    'currency' => 'usd',
    'metadata' => [
        'additional_field' => 'specific_value_1'
    ]
]);

$priceWithExtra2 = $stripe->prices->create([
    'product' => 'prod_...',
    'unit_amount' => 1000,
    'currency' => 'usd',
    'metadata' => [
        'additional_field' => 'specific_value_2'
    ]
]);

// 在Checkout中使用不同Price
$stripe->checkout->sessions->create([
    'success_url' => 'https://example.com/success',
    'line_items' => [
        [
            'price' => $priceWithExtra1->id,
            'quantity' => 1,
        ],
        [
            'price' => $priceWithExtra2->id,
            'quantity' => 1,
        ]
    ],
    'mode' => 'payment',
]);

这种方式的优势是附加信息直接和行项目的Price绑定，后续查看支付记录或Webhook数据时无需额外解析全局metadata，但需要注意管理Price对象，避免冗余创建。

方案3：关联自建订单系统存储附加信息 #

如果有自建订单系统，可先将行项目的附加信息存入自身数据库，再把订单ID存入Checkout Session的metadata。支付完成后通过订单ID从数据库中提取对应信息。示例代码：

$stripe = new \Stripe\StripeClient('...');

// 假设已在自建系统中创建订单，ID为order_789，包含所有行项目附加信息
$orderId = 'order_789';

$stripe->checkout->sessions->create([
    'success_url' => "https://example.com/success?order_id={$orderId}",
    'line_items' => [
        [
            'price' => 'price_...',
            'quantity' => 1,
        ]
    ],
    'mode' => 'payment',
    'metadata' => [
        'order_id' => $orderId
    ]
]);

这种方式最灵活，不受Stripe API字段限制，适合已有成熟订单系统的场景。

内容的提问来源于stack exchange，提问作者kicaj