Skip to main content

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.

MethodURLReturned Data
Detail RetrievalGET /products/128More information
Single Item RetrievalGET /products?product_no=128Basic 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.

ParameterDescriptionExample
limitNumber of items to retrieve at once100
offsetNumber 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​

ItemUsing embedSeparate Queries
API Calls1 timeN+1 times
PerformanceFastSlow
Response SizeLargeSmall

🎯 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​

💡 Summary​

FeatureParameterExample
Search Conditionsparam=valuestatus=active
Multiple Valuesparam=v1,v2,v3product_no=11,12,13
Multi-Shopshop_no=Nshop_no=2
Detail Retrieval/resource/{id}/products/128
Paginationlimit=N&offset=Mlimit=100&offset=200
Specific Fieldsfields=f1,f2fields=product_no,name
Sub-Resourcesembed=r1,r2embed=variants,inventories