Naver Commerce (Smartstore) API¶

Complete API documentation for Naver Commerce (스마트스토어) integration.

Table of Contents¶

Overview
Authentication
Base URL
Endpoints
Get OAuth Token
Get Seller Account
Get Product Brands
Get Orders
Data Types
Error Handling
Rate Limiting
IP Registration
MCP Integration

Overview¶

The Naver Commerce API provides endpoints for Smartstore sellers to:

Authenticate with Naver Commerce platform
Retrieve seller account information
Search product brands
Query and filter orders

Prerequisites¶

Naver Commerce Account: Register at Naver Commerce API Center
Application Credentials: Obtain client_id and client_secret
Magic Meal Kits API Key: Required for all API calls
IP Registration: Register your server IP at Naver Commerce API Center

Authentication¶

All endpoints require two levels of authentication:

1. Magic Meal Kits API Key¶

Required for all requests:

X-API-KEY: your-magic-meal-kits-api-key

2. Naver Commerce Credentials¶

Option A: Headers (Recommended)

X-Naver-Client-ID: your-naver-client-id
X-Naver-Client-Secret: your-naver-client-secret

Option B: Query Parameters (Backward Compatible)

?client_id=your-naver-client-id&client_secret=your-naver-client-secret

Security Note: Headers are recommended as credentials won't appear in server logs, browser history, or proxy logs.

Authentication Flow¶

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Your Client    │────▶│  Magic Meal Kits │────▶│  Naver Commerce │
│                 │     │      API         │     │      API        │
└─────────────────┘     └──────────────────┘     └─────────────────┘
        │                       │                        │
        │  X-API-KEY            │  OAuth Token           │
        │  X-Naver-Client-ID    │  (auto-generated)      │
        │  X-Naver-Client-Secret│                        │
        └───────────────────────┴────────────────────────┘

Base URL¶

https://magic-meal-kits-xxxxx.run.app/api/v1

Replace xxxxx with your deployment identifier.

Endpoints¶

Get OAuth Token¶

Retrieves an OAuth2 access token from Naver Commerce API.

Endpoint¶

POST /api/v1/naver/token

Request Headers¶

Header	Required	Description
`X-API-KEY`	Yes	Magic Meal Kits API key
`X-Naver-Client-ID`	Yes*	Naver Commerce client ID
`X-Naver-Client-Secret`	Yes*	Naver Commerce client secret

*Can also be provided as query parameters

Query Parameters¶

Parameter	Type	Required	Description
`client_id`	String	No*	Naver Commerce client ID (if not in header)
`client_secret`	String	No*	Naver Commerce client secret (if not in header)
`account_id`	String	No	Account ID for SELLER type token

Example Request¶

curl -X POST "https://magic-meal-kits-xxxxx.run.app/api/v1/naver/token" \
     -H "X-API-KEY: your-api-key" \
     -H "X-Naver-Client-ID: 2z1WKQ8ely9OmnreuuYQu8" \
     -H "X-Naver-Client-Secret: \$2a\$04\$shb8Z637r8uWTPhLi9/pr."

Success Response¶

{
  "token": {
    "access_token": "AAA.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 3600,
    "token_type": "Bearer"
  }
}

Response Fields¶

Field	Type	Description
`token.access_token`	String	OAuth2 access token
`token.expires_in`	Integer	Token validity in seconds (typically 3600)
`token.token_type`	String	Token type (always "Bearer")

Error Responses¶

Missing Credentials (400)

{
  "error": "client_id and client_secret are required"
}

Invalid Credentials (500)

{
  "error": "API request failed with status 401: {\"error\":\"invalid_client\"}"
}

Get Seller Account¶

Retrieves seller account information to identify the store.

Endpoint¶

GET /api/v1/naver/account

Request Headers¶

Header	Required	Description
`X-API-KEY`	Yes	Magic Meal Kits API key
`X-Naver-Client-ID`	Yes*	Naver Commerce client ID
`X-Naver-Client-Secret`	Yes*	Naver Commerce client secret

Example Request¶

curl -X GET "https://magic-meal-kits-xxxxx.run.app/api/v1/naver/account" \
     -H "X-API-KEY: your-api-key" \
     -H "X-Naver-Client-ID: your-client-id" \
     -H "X-Naver-Client-Secret: your-client-secret"

Success Response¶

{
  "account": {
    "accountId": "seller_store_123",
    "accountUid": "uid_abc123def456",
    "grade": "POWER"
  }
}

Response Fields¶

Field	Type	Description
`account.accountId`	String	API seller ID (스토어 식별자)
`account.accountUid`	String	Unique account identifier
`account.grade`	String	Seller grade (e.g., "POWER", "BIG", "NORMAL")

Error Responses¶

Token Error (500)

{
  "error": "failed to get token: client_id and client_secret are required"
}

Account Retrieval Error (500)

{
  "error": "failed to get seller account: unexpected status code: 401"
}

Get Product Brands¶

Search for product brands by name.

Endpoint¶

GET /api/v1/naver/product-brands

Request Headers¶

Header	Required	Description
`X-API-KEY`	Yes	Magic Meal Kits API key
`X-Naver-Client-ID`	Yes*	Naver Commerce client ID
`X-Naver-Client-Secret`	Yes*	Naver Commerce client secret

Query Parameters¶

Parameter	Type	Required	Description
`name`	String	Yes	Brand name to search

Example Request¶

curl -X GET "https://magic-meal-kits-xxxxx.run.app/api/v1/naver/product-brands?name=Samsung" \
     -H "X-API-KEY: your-api-key" \
     -H "X-Naver-Client-ID: your-client-id" \
     -H "X-Naver-Client-Secret: your-client-secret"

Success Response¶

{
  "brands": [
    {
      "id": 12345,
      "name": "Samsung Electronics"
    },
    {
      "id": 12346,
      "name": "Samsung Display"
    }
  ]
}

Response Fields¶

Field	Type	Description
`brands`	Array	List of matching brands
`brands[].id`	Integer	Brand ID
`brands[].name`	String	Brand name

Edge Cases¶

No Results

{
  "brands": []
}

Empty Search Term

{
  "brands": []
}

Get Orders¶

Retrieves product orders with optional filtering by date range, status, and pagination.

Endpoint¶

GET /api/v1/naver/order

Request Headers¶

Header	Required	Description
`X-API-KEY`	Yes	Magic Meal Kits API key
`X-Naver-Client-ID`	Yes*	Naver Commerce client ID
`X-Naver-Client-Secret`	Yes*	Naver Commerce client secret

Query Parameters¶

Parameter	Type	Required	Default	Description
`from`	String	No	10 days ago	Start date (YYYY-MM-DD format)
`to`	String	No	Now	End date (YYYY-MM-DD format)
`status`	String	No	All	Comma-separated order statuses
`range_type`	String	No	`PAYED_DATETIME`	Date range type
`page`	Integer	No	1	Page number
`page_size`	Integer	No	10	Items per page

Status Values¶

Status	Korean	Description
`PAYMENT_WAITING`	결제대기	Order placed, waiting for payment
`PAYED`	결제완료	Payment completed, before dispatch
`DELIVERING`	배송중	In delivery
`DELIVERED`	배송완료	Delivery completed
`PURCHASE_DECIDED`	구매확정	Purchase confirmed by customer
`CANCELED`	취소	Order canceled
`RETURNED`	반품	Return completed
`EXCHANGED`	교환	Exchange completed
`CANCELED_BY_NOPAYMENT`	미결제취소	Canceled due to non-payment

Range Type Values¶

Type	Description
`PAYED_DATETIME`	Filter by payment date (default)
`ORDERED_DATETIME`	Filter by order date
`DISPATCHED_DATETIME`	Filter by dispatch date
`PURCHASE_DECIDED_DATETIME`	Filter by purchase decision date
`CLAIM_REQUESTED_DATETIME`	Filter by claim request date
`CLAIM_COMPLETED_DATETIME`	Filter by claim completion date

Example Requests¶

Basic Request (Last 10 Days)

curl -X GET "https://magic-meal-kits-xxxxx.run.app/api/v1/naver/order" \
     -H "X-API-KEY: your-api-key" \
     -H "X-Naver-Client-ID: your-client-id" \
     -H "X-Naver-Client-Secret: your-client-secret"

With Date Range

curl -X GET "https://magic-meal-kits-xxxxx.run.app/api/v1/naver/order?from=2025-01-01&to=2025-01-24" \
     -H "X-API-KEY: your-api-key" \
     -H "X-Naver-Client-ID: your-client-id" \
     -H "X-Naver-Client-Secret: your-client-secret"

With Status Filter

curl -X GET "https://magic-meal-kits-xxxxx.run.app/api/v1/naver/order?status=PAYED,DELIVERING" \
     -H "X-API-KEY: your-api-key" \
     -H "X-Naver-Client-ID: your-client-id" \
     -H "X-Naver-Client-Secret: your-client-secret"

With Pagination

curl -X GET "https://magic-meal-kits-xxxxx.run.app/api/v1/naver/order?page=2&page_size=50" \
     -H "X-API-KEY: your-api-key" \
     -H "X-Naver-Client-ID: your-client-id" \
     -H "X-Naver-Client-Secret: your-client-secret"

Full Example with All Parameters

curl -X GET "https://magic-meal-kits-xxxxx.run.app/api/v1/naver/order?\
from=2025-01-01&\
to=2025-01-24&\
status=PAYED,DELIVERING,DELIVERED&\
range_type=PAYED_DATETIME&\
page=1&\
page_size=100" \
     -H "X-API-KEY: your-api-key" \
     -H "X-Naver-Client-ID: your-client-id" \
     -H "X-Naver-Client-Secret: your-client-secret"

Success Response¶

{
  "orders": {
    "timestamp": "2025-01-24T10:30:00+09:00",
    "traceId": "abc123def456",
    "data": {
      "contents": [
        {
          "orderId": "2025012412345678",
          "status": "PAYED"
        },
        {
          "orderId": "2025012412345679",
          "status": "DELIVERING"
        }
      ],
      "pagination": {
        "totalPages": 5,
        "currentPage": 1,
        "totalElements": 48,
        "pageSize": 10
      }
    }
  }
}

Response Fields¶

Field	Type	Description
`orders.timestamp`	String	Response timestamp (ISO 8601)
`orders.traceId`	String	Request trace ID for debugging
`orders.data.contents`	Array	List of orders
`orders.data.contents[].orderId`	String	Order ID
`orders.data.contents[].status`	String	Order status
`orders.data.pagination.totalPages`	Integer	Total number of pages
`orders.data.pagination.currentPage`	Integer	Current page number
`orders.data.pagination.totalElements`	Integer	Total number of orders
`orders.data.pagination.pageSize`	Integer	Items per page

Error Responses¶

Invalid Date Format (400)

{
  "error": "invalid 'from' date format, use YYYY-MM-DD"
}

Invalid Date Range (400)

{
  "error": "invalid 'to' date format, use YYYY-MM-DD"
}

Token Error (500)

{
  "error": "failed to get token: client_id and client_secret are required"
}

API Error (500)

{
  "error": "unexpected status code: 400, response body: {\"message\":\"Invalid parameter\"}"
}

Edge Cases¶

No Orders Found

{
  "orders": {
    "timestamp": "2025-01-24T10:30:00+09:00",
    "traceId": "abc123def456",
    "data": {
      "contents": [],
      "pagination": {
        "totalPages": 0,
        "currentPage": 1,
        "totalElements": 0,
        "pageSize": 10
      }
    }
  }
}

Date Range Exceeds 6 Months

{
  "error": "unexpected status code: 400, response body: {\"message\":\"Query period cannot exceed 6 months\"}"
}

Data Types¶

Order Status Flow¶

결제대기 (PAYMENT_WAITING)
    │
    ▼
결제완료 (PAYED) ──────────────────┐
    │                              │
    ▼                              ▼
배송중 (DELIVERING)          취소요청 ─▶ 취소 (CANCELED)
    │                              │
    ▼                              ▼
배송완료 (DELIVERED)         반품요청 ─▶ 반품 (RETURNED)
    │                              │
    ▼                              ▼
구매확정 (PURCHASE_DECIDED)  교환요청 ─▶ 교환 (EXCHANGED)

Claim Status Types¶

Status	Korean	Description
`CANCEL_REQUEST`	취소요청	Cancel requested by customer
`CANCELING`	취소진행중	Cancel in progress
`CANCEL_DONE`	취소완료	Cancel completed
`CANCEL_REJECT`	취소거부	Cancel rejected by seller
`RETURN_REQUEST`	반품요청	Return requested
`EXCHANGE_REQUEST`	교환요청	Exchange requested

Error Handling¶

HTTP Status Codes¶

Code	Meaning	Description
`200`	OK	Request successful
`400`	Bad Request	Invalid parameters
`401`	Unauthorized	Invalid or missing API key
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server error or Naver API error

Error Response Format¶

{
  "error": "Error message description"
}

Common Errors¶

Error	Cause	Solution
`client_id and client_secret are required`	Missing credentials	Add X-Naver-Client-ID and X-Naver-Client-Secret headers
`invalid 'from' date format`	Wrong date format	Use YYYY-MM-DD format
`API request failed with status 401`	Invalid Naver credentials	Verify client_id and client_secret
`unexpected status code: 429`	Rate limit exceeded	Reduce request frequency
`GW.IP_NOT_ALLOWED`	IP not registered	Register IP at Naver Commerce API Center

Rate Limiting¶

Naver Commerce API Limits¶

Type	Limit
General queries	10 requests/second
Bulk queries	5 requests/second
Query period	Maximum 6 months

Best Practices¶

Implement exponential backoff for 429 errors
Cache token responses (valid for 1 hour)
Batch requests when possible
Use pagination for large result sets

IP Registration¶

Requirement¶

Naver Commerce API requires IP registration for security.

Item	Details
Max IPs	3 per application
Region	Korea only (domestic IPs)
Registration	Naver Commerce API Center

Registration Path¶

커머스API센터 > 내 스토어 애플리케이션 > 애플리케이션 선택 > 수정 > API호출 IP

Cloud Deployment Note¶

If using cloud services (AWS, GCP, etc.): - Cloud Run / Lambda have dynamic IPs - Consider using NAT Gateway for static IP - Some cloud IPs may be blocked even in Korea region

MCP Integration¶

Available Tools¶

The Naver Commerce API is also available via MCP (Model Context Protocol):

Tool	Description
`naver_get_orders`	Query orders with filters
`naver_get_account`	Get seller account info
`naver_get_brands`	Search product brands

Usage¶

/mcp?tools=naver

MCP Tool Parameters¶

naver_get_orders¶

{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "from": "2025-01-01",
  "to": "2025-01-24",
  "status": "PAYED,DELIVERING",
  "page": 1,
  "page_size": 50
}

naver_get_account¶

{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret"
}

naver_get_brands¶

{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "name": "Samsung"
}

References¶

Changelog¶

Version	Date	Changes
1.0.0	2025-01-24	Initial release
1.1.0	2025-01-24	Added header-based authentication
1.2.0	2025-01-24	Extended order query parameters