llm-wiki/raw/official-docs/stripe-resource-id-convention.md

title, source_type, url, related_branches, related_projects, tags, created

title	source_type	url	related_branches	related_projects	tags	created
official-doc / Stripe API Reference — Resource Object ID Convention & Idempotency-Key	official-doc	https://docs.stripe.com/api	feature-resource-identifier-contract	ca-skeleton	official-doc ca-skeleton api-design stripe resource-identifier idempotency	2026-05-31

official-doc / Stripe API Reference — Resource Object ID Convention & Idempotency-Key

Layer: raw/official-docs/ — Stripe 공식 API Reference 에서 추출한 object ID 형식 관례 + Idempotency-Key 구분의 원문 발췌. 검증된 요약은 /ingest 후 wiki/concepts/ 에 source-summary-template 형식으로 작성.

source_type 판정 근거: 이 문서는 Stripe 사 공식 API Reference (docs.stripe.com/api) 에서 추출. 벤더 공식 문서이므로 official-doc (official-vendor-doc strength). Stripe blog 포스트(stripe.com/blog)에서 추출한 인용은 별도 strength engineering-blog 로 표시. 두 곳을 모두 포함하며, 더 규범적인 docs 출처 기준으로 source_type=official-doc 채택.

Parent / 활용 branch

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-resource-identifier-contract	D1 (resource ID default format): opaque prefix string (ch_, cus_, pi_) 후보 근거 — Stripe 에서 object type 마다 typed prefix + opaque random string 조합 사용 확인
raw/branch-notes/feature-resource-identifier-contract	D4 (ID 생성 책임): Stripe 는 모든 object ID 를 서버가 할당. "Unique identifier for the object" 는 client 가 제어하지 않음
raw/branch-notes/feature-resource-identifier-contract	D6 (prefix 정책): Stripe typed prefix (ch_, cus_, pi_) 가 "de facto" 산업 관례. 단, Stripe 자신도 prefix 변경을 backward-compatible 로 분류하여 영구 불변 보장 아님 (중요 caveat)
raw/branch-notes/feature-resource-identifier-contract	D11 (Public ID vs Internal Sequence): Stripe 는 external-only 전략 — 공개 API 가 client 에 노출하는 유일한 식별자가 object ID. internal sequence 병행 없음 (공개 정보 기준)
raw/branch-notes/feature-resource-identifier-contract	D14 (Idempotency-Key vs Resource ID 구분): Stripe Idempotency-Key 는 client 가 생성하는 UUID, resource ID 는 server 가 할당 — 둘은 별개 개념임을 Stripe docs 가 직접 구분

출처 / Source

• 원본 URL 1: https://docs.stripe.com/api (API overview)
• 원본 URL 2: https://docs.stripe.com/api/idempotent_requests (Idempotency 설명)
• 원본 URL 3: https://docs.stripe.com/upgrades (Backward-compatible changes 정의)
• 원본 URL 4: https://docs.stripe.com/api/expanding_objects (실제 ID 예제 포함)
• 원본 URL 5: https://stripe.com/blog/idempotency (Stripe engineering blog — idempotency 설계)
• 저자 / 조직: Stripe, Inc.
• 발행일: 지속 갱신 (versioned API reference)
• 마지막 확인일: 2026-05-31

왜 저장했는지 / Why archived

Stripe API 는 typed prefix + opaque random string ID (ch_xxx, cus_xxx, pi_xxx) 의 업계 de facto 기준으로 가장 널리 인용되는 사례다. ca-skeleton 의 D1 (ID format) / D6 (prefix 정책) / D11 (external-only) / D14 (Idempotency-Key 구분) 결정에서 Stripe 관례가 "이 방식도 있다" 근거 후보로 등장하므로 원문 발췌 보관. 단, Stripe 가 prefix 변경을 backward-compatible 로 명시적으로 분류한 caveat 도 함께 보존 — 이 자료만으로 typed prefix 를 "영구 안정 표준"으로 처리하면 안 됨.

핵심 인용 / Key quotes (verbatim, 5개)

[§idempotent_requests — Idempotency-Key definition] "A client generates an idempotency key, which is a unique key that the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions. Idempotency keys are up to 255 characters long."

[§idempotent_requests — POST scope] "All POST requests accept idempotency keys. Don't send idempotency keys in GET and DELETE requests because it has no effect. These requests are idempotent by definition."

[§upgrades — Backward-compatible: opaque string format] "Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings."

[§upgrades — Backward-compatible: prefix sub-bullet] "This includes adding or removing fixed prefixes (such as ch_ on charge IDs)."

[§upgrades — ID storage guidance] "Make sure that your integration can handle Stripe-generated object IDs, which can contain up to 255 characters. For example, if you're using MySQL, store the IDs in a VARCHAR(255) COLLATE utf8_bin column (the COLLATE configuration provides case-sensitivity during lookups)."

보조 인용 (from docs.stripe.com/api/expanding_objects — 실제 ID 형식 예제):

[§expanding_objects — observed ID patterns in API responses] Charge IDs: ch_3LmzzQ2eZvKYlo2C0XjzUzJV, Customer IDs: cus_NffrFeUfNV2Hib, PaymentIntent IDs: pi_3MtwBwLkdIwHu7ix28a3tqPa

보조 인용 (from stripe.com/blog/idempotency — client-generated key 설명):

[stripe.com/blog/idempotency] "When performing a request, a client generates a unique ID to identify just that operation and sends it up to the server along with the normal payload."

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
STRIPE-C1	Stripe 는 Idempotency-Key 를 client 가 생성하는 unique key 로 정의한다. 서버는 이 키를 사용해 동일 요청의 재시도를 식별.	[§idempotent_requests] "A client generates an idempotency key, which is a unique key that the server uses to recognize subsequent retries of the same request."	official-vendor-doc	Stripe API 에서 Idempotency-Key header 를 사용하는 모든 POST 요청	Idempotency-Key 가 resource ID 와 같은 형식이어야 함을 증명하지 않음. Stripe 는 V4 UUID 를 권장하지만 형식 강제 없음
STRIPE-C2	Stripe API 의 object ID 는 opaque string 이며 prefix 를 포함한 형식 변경이 backward-compatible 로 분류된다.	[§upgrades] "Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings." + "This includes adding or removing fixed prefixes (such as ch_ on charge IDs)."	official-vendor-doc	Stripe API 에서 object ID 를 파싱하거나 prefix 에 의존하는 모든 통합	prefix 가 영구 불변임을 증명하지 않음. Stripe 는 오히려 prefix 변경이 호환 변경이라 명시. typed prefix 를 "formal standard" 로 처리하면 안 됨
STRIPE-C3	Stripe object ID 는 최대 255자까지 증가할 수 있으므로 저장 컬럼을 VARCHAR(255)로 설계해야 한다.	[§upgrades] "Make sure that your integration can handle Stripe-generated object IDs, which can contain up to 255 characters. For example, if you're using MySQL, store the IDs in a VARCHAR(255) COLLATE utf8_bin column"	official-vendor-doc	Stripe object ID 를 DB 에 저장하는 모든 시스템	Stripe 외 다른 vendor 의 ID 길이 보장을 증명하지 않음. 자체 생성 ID 의 VARCHAR 길이 정책은 별도 결정
STRIPE-C4	실제 Stripe API 응답의 ID 는 <type_prefix>_<random_alphanum> 형식이다 — Charge: ch_3LmzzQ2eZvKYlo2C0XjzUzJV, Customer: cus_NffrFeUfNV2Hib, PaymentIntent: pi_3MtwBwLkdIwHu7ix28a3tqPa.	[§expanding_objects API response examples] observed: ch_3LmzzQ2eZvKYlo2C0XjzUzJV, cus_NffrFeUfNV2Hib, pi_3MtwBwLkdIwHu7ix28a3tqPa	official-vendor-doc	Stripe API 의 실제 ID 관찰 결과 (2026-05-31 기준)	prefix 가 불변임을 증명하지 않음 (STRIPE-C2 참조). 다른 vendor 가 동일 형식을 따라야 한다는 표준을 증명하지 않음
STRIPE-C5	Idempotency-Key 는 POST 요청에만 유효. GET / DELETE 는 정의상 idempotent 이므로 key 전송이 불필요.	[§idempotent_requests] "All POST requests accept idempotency keys. Don't send idempotency keys in GET and DELETE requests because it has no effect. These requests are idempotent by definition."	official-vendor-doc	Stripe HTTP method 별 idempotency 처리 정책	모든 REST API 가 동일 정책을 따라야 함을 증명하지 않음. PATCH 요청의 idempotency 처리는 이 문서에서 명시되지 않음

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:

  • STRIPE-C1: Stripe 에서 Idempotency-Key 와 resource object ID 는 생성 주체가 다름 — Idempotency-Key 는 client, resource ID 는 server.
  • STRIPE-C2: Stripe 가 자신의 ID prefix (ch_, cus_, pi_) 를 backward-compatible change 의 예시로 사용 — 즉, Stripe 도 prefix 를 변경할 수 있다고 명시.
  • STRIPE-C4: 실제 Stripe API 응답에서 <prefix>_<random> 형식이 관찰됨.
  • STRIPE-C5: Idempotency-Key 는 POST 전용.

• 이 자료가 증명하지 않는 것:

  • Stripe typed prefix 가 RFC / ISO / IETF 등 공식 표준임을 증명하지 않음. Stripe 내부 de facto 관례.
  • typed prefix 가 영구 불변 보장임을 증명하지 않음 — 오히려 STRIPE-C2 가 변경 가능함을 명시.
  • ca-skeleton 이 tk_, usr_ 같은 prefix 를 채택해야 한다는 결론을 직접 증명하지 않음 (D6 결정 근거로 사용 가능하나 UNSUPPORTED_DECISION 잔여 있음).
  • Idempotency-Key 의 형식 (UUID v4 외 다른 형식의 허용 여부) 을 normative 하게 규정하지 않음.
  • 24시간 TTL (Stripe docs 실제 표현: "24 hours old") 이 모든 API 에서 표준임을 증명하지 않음.

• 내 프로젝트에 적용하려면 추가 확인이 필요한 것:

  • D6 (prefix 정책): typed prefix 채택 시, prefix 변경 가능성을 client SDK 에 어떻게 알릴지 versioning 전략 별도 결정 필요.
  • D11 (external-only vs dual): Stripe 가 internal sequence 를 사용하지 않는다는 직접 증거 없음 — 공개 API 에 노출되지 않을 뿐이므로 내부 DB primary key 전략은 알 수 없음. UNSUPPORTED_DECISION 잔여.
  • D14: feature-rate-limit-idempotency-contract 에서 24h TTL 정책을 별도로 결정해야 하며, 본 자료는 보조 근거.

메모 / Notes

• Stripe docs 의 ID field description 은 일관되게 "Unique identifier for the object" (단순 설명). prefix 형식의 formal spec 은 docs 어디에도 명시적으로 정의되지 않음. prefix 관례는 실제 API response 예제를 통해 관찰하는 방식으로만 확인 가능 (STRIPE-C4).
• Stripe 가 prefix 변경을 backward-compatible 로 분류한 것은 Stripe 자신도 이 형식을 영구 약속하지 않는다는 중요한 신호 — ca-skeleton 이 typed prefix 를 채택하더라도 prefix 파싱에 의존하는 로직은 두면 안 됨.
• blog.stripe.com/idempotency 문서에서 "client generates a unique ID" 표현은 idempotency key 에 대한 것이며, resource ID 를 client 가 생성한다는 뜻이 아님 (혼동 금지).
• 추가로 봐야 할 동일 출처 페이지:
  • https://docs.stripe.com/api/charges/object — id 필드 설명 (현재 페이지 접근 시 "Unique identifier for the object" 만 확인됨)
  • https://docs.stripe.com/api/error_object — error response 에서 ID 형식 확인 가능

Related / 관련

• 같은 주제 other official-doc: raw/official-docs/google-aip-148-standard-fields — Google 스타일 flat ID (typed prefix 없음, D6 비교 대상)
• 같은 주제 other official-doc: raw/official-docs/nanoid-spec — NanoID 21자 URL-safe (D1 다른 후보)
• 같은 주제 other official-doc: raw/official-docs/rfc9562-uuid — UUID v7 공식 표준 (D1 주요 후보)
• 이 자료를 인용한 wiki 요약: (미작성 — /ingest 후 생성 예정)