GET API Usage Guide

CAFE24 API provides various methods to retrieve data. This guide explains how to utilize 7 parameter types available for GET requests.

---

1️⃣ Adding Search Conditions

Search conditions can be added by appending parameters to the endpoint. Use the & separator to combine multiple conditions.

Examples

# Query products with price >= 1000 from a specific brand
GET https://yourmall.cafe24api.com/api/v2/products?brand_code=B000000A&price_min=1000

# Query products by date range (YYYY-MM-DD)
GET https://yourmall.cafe24api.com/api/v2/products?created_start_date=2024-01-03&created_end_date=2024-02-03

# Query by date+time range (ISO 8601)
GET https://yourmall.cafe24api.com/api/v2/products?updated_start_date=2024-01-03T14:01:26+09:00&updated_end_date=2024-02-03T14:01:26+09:00

Code Examples

// Node.js
const response = await axios.get('/api/v2/admin/products', {
  params: {
    brand_code: 'B000000A',
    price_min: 1000,
    price_max: 50000,
    status: 'active'
  }
});

# Python
params = {
    'brand_code': 'B000000A',
    'price_min': 1000,
    'created_start_date': '2024-01-03'
}
response = requests.get(url, params=params)

---

2️⃣ Searching Multiple Values with Commas

Use commas (,) to search for multiple values simultaneously (maximum 100 items). Comma-separated search conditions work as OR conditions.

Examples

# Query specific product numbers (11 OR 12 OR 13)
GET https://yourmall.cafe24api.com/api/v2/products?product_no=11,12,13

# Combining multiple conditions
GET https://yourmall.cafe24api.com/api/v2/products?product_no=11,12,13&product_code=P000000X,P000000W

Code Examples

// Node.js
const productNos = [11, 12, 13];
const response = await axios.get('/api/v2/admin/products', {
  params: {
    product_no: productNos.join(',')
  }
});

# Python
product_nos = [11, 12, 13]
params = {'product_no': ','.join(map(str, product_nos))}
response = requests.get(url, params=params)

⚠️ Note: Maximum 100 items, OR condition, no spaces

---

3️⃣ Multi-Shop Information Retrieval

Use the shop_no parameter to retrieve information from a specific multi-shop. If not specified, it returns information from the default (first) shopping mall.

Examples

# Query products from shop #2
GET https://yourmall.cafe24api.com/api/v2/products?shop_no=2

# Default shopping mall (shop_no omitted)
GET https://yourmall.cafe24api.com/api/v2/products

Code Examples

// Node.js - Iterate through all shops
async function getAllShopsProducts() {
  const allProducts = [];
  for (let shopNo = 1; shopNo <= 5; shopNo++) {
    try {
      const response = await axios.get('/api/v2/admin/products', {
        params: { shop_no: shopNo }
      });
      allProducts.push({ shop_no: shopNo, products: response.data });
    } catch (error) {
      break; // Shop doesn't exist
    }
  }
  return allProducts;
}

---

4️⃣ Detail Retrieval vs Single Item Retrieval

You can retrieve detailed information by specifying the resource ID.

Method	URL	Returned Data
Detail Retrieval	GET /products/128	More information
Single Item Retrieval	GET /products?product_no=128	Basic information

Examples

# Detail retrieval - includes more information
GET https://yourmall.cafe24api.com/api/v2/admin/products/128

# Single item retrieval - basic information only
GET https://yourmall.cafe24api.com/api/v2/admin/products?product_no=128

Code Examples

// Node.js
// Detail retrieval
const detail = await axios.get(`/api/v2/admin/products/${productNo}`);

// Single item retrieval
const info = await axios.get('/api/v2/admin/products', {
  params: { product_no: productNo }
});

---

5️⃣ Pagination

Use limit and offset parameters to retrieve data in pages.

Parameter	Description	Example
limit	Number of items to retrieve at once	100
offset	Number of items to skip (starts from 0)	200

Calculation Formula

Page Number = P (starts from 1)
limit = L
offset = (P - 1) * L

Example) Retrieve page 3 (limit=100)
offset = (3 - 1) * 100 = 200

Examples

# First 100 items
GET https://yourmall.cafe24api.com/api/v2/admin/products?limit=100

# Items 201-300 (page 3)
GET https://yourmall.cafe24api.com/api/v2/admin/products?limit=100&offset=200

Code Examples

// Node.js - Retrieve all data
async function getAllProducts() {
  const allProducts = [];
  let offset = 0;
  const limit = 100;

  while (true) {
    const response = await axios.get('/api/v2/admin/products', {
      params: { limit, offset }
    });

    const products = response.data.resource;
    if (products.length === 0) break;

    allProducts.push(...products);
    offset += limit;
  }

  return allProducts;
}

# Python - Page-based retrieval
def get_products_page(page, limit=100):
    offset = (page - 1) * limit
    response = requests.get(url, params={'limit': limit, 'offset': offset})
    return response.json()['resource']

---

6️⃣ Retrieving Specific Fields

Use the fields parameter to selectively retrieve only the fields you need.

Examples

# Retrieve only product name and product number
GET https://yourmall.cafe24api.com/api/v2/admin/products?fields=product_name,product_no

# Retrieve multiple fields
GET https://yourmall.cafe24api.com/api/v2/admin/products?fields=product_no,product_name,price,inventory_qty

Response Example

{
  "resource": [
    {
      "product_no": 128,
      "product_name": "Sample Product"
    }
  ]
}

Code Examples

// Node.js
const fields = ['product_no', 'product_name', 'price'];
const response = await axios.get('/api/v2/admin/products', {
  params: { fields: fields.join(',') }
});

Benefits

• Network bandwidth savings
• Improved processing speed
• Memory efficiency
• Sensitive data filtering

---

7️⃣ Retrieving Sub-Resources

Use the embed parameter to retrieve related sub-resources together.

Examples

# Include variants and inventories when querying products
GET https://yourmall.cafe24api.com/api/v2/admin/products/570?embed=variants,inventories

# Include product information when querying orders
GET https://yourmall.cafe24api.com/api/v2/admin/orders/123?embed=products,shipping

Response Example

{
  "resource": {
    "product_no": 570,
    "product_name": "Sample Product",
    "variants": [
      {"variant_no": 1, "option_name": "Color", "option_value": "Red"}
    ],
    "inventories": [
      {"warehouse_name": "Main", "quantity": 100}
    ]
  }
}

Code Examples

// Node.js
const response = await axios.get(`/api/v2/admin/products/${productNo}`, {
  params: { embed: 'variants,inventories,categories' }
});

const product = response.data.resource;
console.log('Variants:', product.variants);
console.log('Inventories:', product.inventories);

embed vs Separate Queries

Item	Using embed	Separate Queries
API Calls	1 time	N+1 times
Performance	Fast	Slow
Response Size	Large	Small

---

🎯 Best Practices

1. Optimizing Condition Combinations

# ✅ Good example - Retrieve only needed data in one request
GET /products?status=active&fields=product_no,product_name,price&limit=100

# ❌ Bad example - Retrieve all data then filter
GET /products

2. Error Handling

async function safeGetData(endpoint, params) {
  try {
    const response = await axios.get(endpoint, { params });
    return response.data.resource;
  } catch (error) {
    if (error.response?.status === 404) {
      return null; // Resource not found
    } else if (error.response?.status === 422) {
      console.error('Invalid parameters:', error.response.data);
    }
    throw error;
  }
}

3. URL Encoding

// ✅ Automatic encoding (recommended)
const params = {
  product_name: '상품명',
  category: '카테고리'
};
axios.get(url, { params }); // axios handles encoding automatically

// ❌ Manual encoding (not recommended)
const url = `/products?name=${encodeURIComponent('상품명')}`;

4. Performance Optimization

// ✅ Retrieve only necessary fields
const params = {
  fields: 'product_no,product_name,price',
  limit: 100
};

// ✅ Solve N+1 problem with embed
const params = {
  embed: 'variants,inventories',
  fields: 'product_no,product_name,variants,inventories'
};

// ✅ Utilize conditions as much as possible
const params = {
  status: 'active',
  price_min: 10000,
  created_start_date: '2024-01-01',
  limit: 50
};

---

📊 Parameter Combination Examples

Complex Query Example

# Paginated query of specific fields for active products within a price range
GET /api/v2/admin/products?status=active&price_min=10000&price_max=50000&fields=product_no,product_name,price&limit=100&offset=0

// Node.js complex query
const response = await axios.get('/api/v2/admin/products', {
  params: {
    status: 'active',
    price_min: 10000,
    price_max: 50000,
    created_start_date: '2024-01-01',
    fields: 'product_no,product_name,price,created_date',
    limit: 100,
    offset: 0,
    shop_no: 1
  },
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  }
});

---

⚠️ Precautions

1. URL Encoding: Korean characters and special characters must be encoded
2. Date Format: ISO 8601 format recommended (YYYY-MM-DDTHH:MM:SS+09:00)
3. Comma Limit: Maximum 100 items
4. Offset Performance: Large offset values can cause performance degradation
5. Check API Documentation: Each API supports different parameters

---

📚 Related Documents

• OAuth 2.0 Authentication Guide
• API Status Code Guide
• CAFE24 API Official Documentation

---

💡 Summary

Feature	Parameter	Example
Search Conditions	param=value	status=active
Multiple Values	param=v1,v2,v3	product_no=11,12,13
Multi-Shop	shop_no=N	shop_no=2
Detail Retrieval	/resource/{id}	/products/128
Pagination	limit=N&offset=M	limit=100&offset=200
Specific Fields	fields=f1,f2	fields=product_no,name
Sub-Resources	embed=r1,r2	embed=variants,inventories