# Kurly — Kurly Logistics Services (KLS) Open API

> Kurly (컬리, legally The Farmers Front) is a Korean online grocery and commerce company, best known
> for Market Kurly and its dawn-delivery (샛별배송) model. Kurly Logistics Services (KLS) opens that
> logistics network to contracted shipper clients (화주사) as a B2B Open API covering fulfillment
> (물류대행), delivery agency (배송대행) via the Kurly Nextmile network, and shared delivery tracking.
> Access is contract-gated: credentials are issued only after IP allowlist registration. There is no
> public sandbox, no self-service signup, and — by stated policy — no webhooks.

Generated by the API Evangelist enrichment pipeline on 2026-07-19 from Kurly's own developer center.

## APIs

- [KLS Authentication](https://developers.kurly.com/docs/api/인증/토큰-발급): Exchange clientId and
  secretKey for a Bearer access token (POST /auth/token).
- [KLS Fulfillment (물류대행)](https://developers.kurly.com/docs/api/물류대행): Goods master, inbound
  receiving, inventory and ledgers, outbound orders and fulfillment plans. 24 operations.
- [KLS Delivery Agency (배송대행)](https://developers.kurly.com/docs/api/배송대행): Order register,
  lookup and cancel against Kurly's delivery network, delivery-policy lookup, and bulk waybill print
  data. 7 operations.
- [KLS Delivery Tracking (배송추적)](https://developers.kurly.com/docs/api/배송추적): Tracking status
  and event history by carrier and waybill number. Shared across both services.

## Docs

- [KLS Developer Center](https://developers.kurly.com/): Docusaurus-based developer center, Korean only.
- [Service introduction](https://developers.kurly.com/docs/intro): What KLS covers and how the three
  service families relate.
- [Authentication](https://developers.kurly.com/docs/auth): IP allowlist registration, credential
  issuance, and Bearer token usage.
- [FAQ](https://developers.kurly.com/docs/faq): Test-environment access policy, the no-push/polling
  policy, and how to request endpoints that do not exist yet.
- [Changelog](https://developers.kurly.com/changelog): Dated, tagged release notes, 1.0.0 (2025-08-08)
  through 1.3.12 (2026-06-30).
- [Fulfillment goods policy guide](https://developers.kurly.com/docs/guide/물류대행/goods/상품-정책-가이드)
- [Fulfillment inbound policy guide](https://developers.kurly.com/docs/guide/물류대행/inbound/입고-정책-가이드):
  Inbound status flow, cancellation window, and exception-report policy.
- [Delivery agency integration guide](https://developers.kurly.com/docs/guide/배송대행/배송대행-연동-가이드):
  requestKey semantics, D+1 delivery window, grouping and delivery-type rules.
- [Self-printed waybill guide](https://developers.kurly.com/docs/guide/배송대행/운송장-자체-출력-가이드)
- [Delivery tracking integration guide](https://developers.kurly.com/docs/guide/배송추적/배송-추적-API-연동-가이드):
  The nine tracking states, their codes, and their ordering.

## Specs and artifacts

These are API Evangelist artifacts in this repository. The OpenAPI documents are a faithful
reconstruction from Kurly's published reference — paths, methods, summaries and response statuses are
Kurly's; request/response schemas render client-side on Kurly's site and are not reproduced.

- openapi/kurly-kls-fulfillment-openapi.yml — 24 operations
- openapi/kurly-kls-delivery-agency-openapi.yml — 7 operations
- openapi/kurly-kls-delivery-tracking-openapi.yml — 1 operation
- openapi/kurly-kls-auth-openapi.yml — 1 operation
- authentication/kurly-authentication.yml — Bearer scheme and credential issuance
- conventions/kurly-conventions.yml — idempotency, pagination, batching, error envelope, polling
- errors/kurly-error-codes.yml — error envelope and the DA-prefixed delivery-agency codes
- vocabulary/kurly-vocabulary.yml — tracking states, inbound statuses, grouping and delivery types
- data-model/kurly-data-model.yml — entity graph across the three domains
- lifecycle/kurly-lifecycle.yml — versioning, breaking-change history, deprecation posture
- changelog/kurly-changelog.yml — all 16 published releases
- rate-limits/kurly-rate-limits.yml — 429 signalling and batch caps
- sandbox/kurly-sandbox.yml — gated test-environment access requirements
- conformance/kurly-conformance.yml — standards posture
- security/kurly-domain-security.yml — TLS, HSTS, DNS security probe
- well-known/kurly-well-known.yml — verified absence of .well-known documents
- mcp/kurly-mcp.yml — candidate MCP tool surface derived from the operations
- skills/ — four packaged agent skills for the marquee flows
- overlays/ — OpenAPI overlays carrying the API Evangelist enhancements

## Integration notes for agents

- **Access is gated.** clientId/secretKey are issued by Kurly after the shipper submits an outbound
  IP allowlist via Google Form; issuance takes up to 5 business days. There is no self-service signup.
- **Idempotency matters and is per-domain.** Delivery-agency order registration uses a body field
  `requestKey` (max 50 chars, unique per shipper, never reusable, server-generated if omitted).
  Inbound receiving registration uses an `X-Idempotency-Key` header with `X-Timestamp`. Retries must
  reuse the same key; generating a new one causes duplicate registration.
- **No webhooks, by policy.** Kurly states KLS does not push data to external systems and recommends
  periodic polling.
- **Partial success is normal.** SKU registration and bulk order register/cancel return 200 with
  per-item failures inside the body. Never infer success from the status code alone.
- **Bulk caps.** 20 items for bulk order register/cancel, 50 keys for by-request-keys lookup.
- **Rate limiting is signalled but unquantified.** 429 applies across all APIs; no numeric limits and
  no rate-limit headers are published.
- **Documentation is Korean only.**

## Company

- [Kurly](https://www.kurly.com): Market Kurly consumer commerce site.
- [KLS console](https://kls.kurly.com): Kurly Logistics Services shipper portal.
- [Kurly tech blog](https://helloworld.kurly.com): 컬리 기술 블로그.
- [GitHub](https://github.com/thefarmersfront): Kurly's GitHub organisation (no KLS SDKs published).
- Contact: logistics-dev@kurlycorp.com