주문 라이프사이클

**주문(order)은 결제를 감싸는 단위이고, 각 주문에는 실제로 발급·전달되는 선물을 나타내는 주문 아이템(order item)**이 들어 있습니다. 둘은 서로 별개의 상태를 가집니다.

주문 상태

상태	의미
`COMPLETED`	결제 완료; 주문이 이행 중이거나 이행됨
`PAYMENT_PENDING`	결제 완료 대기 중
`PAYMENT_EXPIRED`	기한 내 결제가 완료되지 않아 주문이 이행되지 않음
`CANCELLED`	주문 취소됨

선불 잔액으로 결제하는 API 주문은 일반적으로 생성 즉시 COMPLETED가 됩니다.

주문 아이템 상태

상태	의미
`PENDING`	아직 전달 전 — 발급 진행 중이거나, 수신자의 전달 정보 입력을 기다리는 중 (수신자 직접 입력 플로우)
`COMPLETED`	발급·전달 완료
`CANCELLED`	취소됨

주문 추적하기

현재 웹훅은 제공되지 않습니다 — 주문 조회 API를 폴링해 진행 상황을 추적하세요:

단건: GET /v1/orders/{id}
일괄 대사(reconciliation): GET /v1/orders + 필터(order_item_status=PENDING, 날짜 범위, external_reference_id 등). 이 엔드포인트는 page와 element_size(최대 500)가 필수입니다 — 예: GET /v1/orders?order_item_status=PENDING&page=0&element_size=100.

실전 가이드:

대부분의 디지털 주문은 수 초에서 수 분 안에 완료됩니다. 적당한 간격(처음 몇 분은 30–60초, 이후 백오프)으로 폴링하고 요청 제한을 지키세요.
수신자 직접 입력 플로우의 아이템은 수신자가 수락하거나 링크가 만료될 때까지 며칠씩 PENDING일 수 있습니다. 오래 PENDING이라고 실패로 간주하지 말고 delivery.recipient.acceptance.expiry_date를 확인하세요.
대사 작업에는 SodaGift 주문 ID만 저장하기보다 본인이 부여한 external_reference_id 값으로 GET /v1/orders를 필터링하는 방식을 권장합니다.

⚠️
상태 필터를 걸고 페이징할 때: page.total_size는 order_item_status 필터를 반영하지 않습니다 — 이 값으로 페이지 수를 계산하지 마세요. page.result_size는 필터를 반영하므로, 응답 행 수가 element_size보다 적어질 때까지 page를 올려가며 순회하세요.

📘
ON_SALE이라고 즉시 발급이 보장되지는 않습니다. 주문 생성은 카탈로그 노출 상태만 확인하고 공급사 실시간 재고는 보지 않습니다 — 공급사 재고가 없으면 주문은 200으로 접수되고 아이템은 PENDING에 머물 수 있습니다. 시점이 중요한 발송이라면 실시간 확인을 하는 GET /v1/products/{id}/availability를 먼저 호출하세요.

주문 취소

기프트 카드 주문은 최종 확정입니다 — 한번 생성되면 취소할 수 없습니다. 주문 전에 상품·금액·수신자를 다시 확인하고, 재시도가 중복 주문을 만들지 않도록 항상 external_reference_id를 전달하세요. 연동은 먼저 샌드박스에서 테스트하세요.