PARTNER_APP 결제 주문의 품목명이 "기본"으로만 기록됩니다 — update-line-items 사용 가능 여부와 권장 연동 방식 문의

[제이크]

안녕하세요. 토스플레이스 프론트 플러그인(requestPayment 연동)을 개발·운영 중입니다.
결제 주문의 품목명 기록 방식과 관련해 Open API 사용 방법을 문의드립니다.

■ 현상

• 플러그인에서 requestPayment를 호출하면 토스 측에서 주문이 자동 생성되고,
  orderKey / orderNumber에는 당사 주문번호가 그대로 기록됩니다.
• 이렇게 생성된 주문(source = PARTNER_APP)은 lineItems[].item.title이
  예외 없이 "기본"으로만 기록됩니다.
• 같은 매장에서 토스포스로 판매한 주문(source = TERMINAL_POS / POS)은
  실제 상품명이 정상 기록됩니다.

당사 시스템에는 판매 상품명이 모두 있어, 이를 토스 주문 데이터에 반영해
매출 내역·영수증에서 실제 판매 상품을 확인할 수 있도록 하고 싶습니다.
(결제 승인·취소·정산 금액은 건드리지 않고, 품목 정보만 다루는 것이 목적입니다.)

■ 확인해 본 것

• 조회 계열(GET /merchants/{merchantId}, /order/orders, /catalog/items)은 정상 동작합니다.
• PUT /api-public/openapi/v1/merchants/{merchantId}/order/orders/{orderId}/update-line-items 는
  403 {"errorCode":"4030","reason":"해당 기능에 대한 접근 권한이 없습니다"} 로 응답합니다.
  존재하지 않는 orderId로 호출해도 동일하게 403이라, 주문 상태가 아니라
  앱 권한 단계에서 막히는 것으로 보고 있습니다.
• 이 엔드포인트는 Swagger 스펙(Open API 2026-09-15)에는 있지만
  연동 가이드의 Order API 목차에는 없습니다.

■ 질문

(Q1) update-line-items는 정식으로 사용 가능한 기능입니까?
사용 가능하다면 어떤 앱에 열려 있고, 별도 신청이 필요합니까?

(Q2) 이 API는 이미 orderState = COMPLETED인 주문에도 사용할 수 있습니까?
PARTNER_APP 결제는 승인 직후 COMPLETED로 기록되기 때문에 중요한 부분입니다.
완료된 주문의 품목 변경이 불가하다면, 결제 전에 주문을 먼저 생성하는 방식만이
유일한 경로인지도 알려주세요.

(Q3) PARTNER_APP 결제로 자동 생성되는 주문과, Open API(주문 생성)로 만든 주문은 어떤 관계가 됩니까?
- 동일한 orderKey로 주문을 먼저 생성하면, 이후 requestPayment 결제가 그 주문에 연결됩니까?
아니면 별도 주문이 새로 생성됩니까?
- 문서에 「이미 존재하는 주문과 값이 중복될 경우 주문 생성이 거부돼요」라고 되어 있어
자동 생성과 충돌할 가능성이 걱정됩니다.

(Q4) 위 목적(PARTNER_APP 결제 건에 실제 상품명 기록)에 토스플레이스가 권장하는 연동 방식이 있습니까?
결제 경로라 시행착오로 확인하기 어려워, 권장 방식이 있다면 그에 맞춰 개발하겠습니다.

같은 문제를 겪으셨거나 방법을 아시는 분도 의견 주시면 감사하겠습니다.

[토스플레이스-개발자센터]

안녕하세요. 토스플레이스 개발자센터입니다.

문의하신 프론트 결제 주문의 상품명 변경에 대해 안내 드립니다.

1. update-line-items 사용 권한과 4030 오류

update-line-items는 공개된 주문 내역 변경 API이며, 주문 생성 API 사용 권한이 부여된 앱에서 사용할 수 있습니다. 조회 API 사용 권한과는 별도로 확인이 필요합니다.

전달해 주신 4030(해당 기능에 대한 접근 권한이 없습니다) 오류는 해당 앱의 주문 생성 API 권한 부여 여부를 먼저 확인해야 합니다.

다만 권한이 부여되더라도 Open API의 주문 생성 API로 만든 주문만 변경할 수 있습니다. 프론트 결제로 자동 생성된 PARTNER_APP 주문은 변경 대상이 아닙니다. 주문 내역 변경 가이드

2. 결제 완료 주문의 변경 여부

이번 주문은 COMPLETED 상태 여부에 앞서 프론트 결제로 생성된 PARTNER_APP 주문이라는 점이 제한 사항입니다. 결제 전에 변경 API를 호출하는 것만으로 이 제한이 해소되지는 않습니다.

3. 주문 사전 생성 후 프론트 결제 연결

프론트 Payment API에는 기존 주문 ID를 지정하는 항목이 없습니다. Open API의 orderKey와 프론트의 paymentKey를 동일하게 설정해도, 미리 생성한 주문에 결제가 연결되지 않습니다. 따라서 동일한 식별자로 주문과 결제를 연결하는 방식은 권장하지 않습니다.

4. 실제 상품명 기록 방법

현재 프론트 Payment API에는 상품명·품목 목록을 전달하는 항목이 없습니다. 따라서 현재 제공되는 API만으로 프론트 결제 주문의 상품명을 실제 상품명으로 지정하거나 변경하는 방식은 지원되지 않습니다. 프론트 결제 가이드

솔루션사 시스템에서 상품정보와 결제 결과를 연결해 관리할 수는 있으나, 이 방식이 토스 매출 내역이나 영수증의 상품명을 변경하는 것은 아닙니다.