API basic guide

cafe24 API is based on a shopping mall platform and is provided in the RESTful format for easy and convenient use.

This guide provides the basic information for usage of the API.

The cafe24 API overview

The cafe24 platform API is provided to developers of the App Store and third-party solution providers to provide services in conjunction with the cafe24 shopping mall platform.

The cafe24 API is a RESTful architecture that provides an authentication system based on the Oauth V2, standard HTTP Request Method, resource-predictable endpoint URL, and error messaging based on HTTP code.

The cafe24 API overview
Term Description
API API stands for Application Programming Interface. The cafe24 API is an interface that enables intercommunication in standardized regulation between the shopping mall platform, application, service and library.
It is provided in the RESTful format in which communication is enabled based on set regulations (interface, parameter, etc.).
It consists of the Admin API and Front API. The Front API is comprised of APIs available for call without an authentication.
Entity The cafe24 shopping mall API provides separate resources for each entity.
Each entity represents a unit of resource managed by the shopping mall.
Sub Entity

A sub entity refers to the entity created by separating the attributes with N attributes within the entity.
A sub entity cannot be viewed, registered or updated by itself, and must always be used in the URL with its parent entity included.


- Example of use

Incorrect example

GET https://{{mallid}}.cafe24api.com/api/v2/options


Good example

GET https://{{mallid}}.cafe24api.com/api/v2/products/{#id}/options

Since a sub entity belongs to the parent entity, creation / deletion of a parent entity results in creation / deletion of the sub entity.

Relational Entity

A relational entity is a representation of the relationship between semantically related entities, and is created for the use of a more semantic API.
A relational entity is not part of a particular entity, but it can be represented semantically as "entity belonging to ~~~" (the customer‘s shopping cart, features of the product that the customer likes).
A relational entity, unlike a sub entity, does not belong to another entity and is in a comparable relationship.


- Example of use

Incorrect example

GET https://{{mallid}}.cafe24api.com/api/v2/admin/wishes/{#id}

GET https://{{mallid}}.cafe24api.com/api/v2/admin/products/{#id}/wishes

Since relational entities do not form vertical relationships with each other, a creation / update / deletion / lookup does not make any impact.

Endpoint

Meaning of the method and URL that can call an API.
The methods (POST, GET, PUT, DELETE) of the endpoint define the action of the corresponding API, whereas the URL of the endpoint cognitively represents the action of the corresponding API.


- Example of use: when registering a product entity

POST https://{{mallid}}.cafe24api.com/api/v2/admin/products

Request
parameters
Request parameters are the values ​​that must be sent together when calling an API.
The attributes of the entity can be defined when adding, registering or updating search conditions.
HTTP header The HTTP header contains meta information that describes the request to the web server.
API requests must include an access token in the HTTP header (only for Admin API calls).
In response, the HTTP header will return various meta information, including the API request limit value.

Request / Response format

The Request and Response format of the cafe24 API supports the JSON Format.

Request example

curl -X POST \
  '{endpoint_url}' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -d '{ .... }'

Normal response example

{
    "request": {
        "key": "value",
        "key": "value"
        }
}

Normal response example

{
    "error": {
        "code": "Error code",
        "message": "Error message",
        "more_info": {
        }
    }
}

To protect your privacy, the cafe24 API only supports the HTTPS protocol.
The format for dates is provided in ISO_8601 format : YYYY-MM-DDTHH:MM:SS+09:00

Method type

The cafe24 supports to create, read, update and delete for each resource and the API are available using the standard HTTP method.

Method type
Classification Description
POST Creates an entity.
GET Reads the information of the entity.
PUT Updates the entity.
DELETE Deletes the entity.

Front API and Admin API

Depending on the endpoint, you can call the Front API and the Admin API, respectively.

1. Front API

The Front API is suitable for public information (merchandise display information) or shopping mall customers to view their information or create posts.
The Front API is limited in some respects to the Admin API.

Example of use

https://{{mallid}}.cafe24api.com/api/v2/sampleapi

2. Admin API

The Admin API is suitable for shopping mall managers to view, create, update and delete shopping mall information.
The Admin API can view most of the information of the entity and can only be used if qualified for an Oauth 2.0-style authentication.

Example of use

https://{{mallid}}.cafe24api.com/api/v2/admin/sampleapi

How to use API lookup

The cafe24 API provides various ways to view the data.
The following explains how you can invoke various data using various parameters in the API query.

1. Adding search conditions

In the API query, parameters can be added to the endpoint for search conditions.
Search conditions can be added using the ‘&’ delimiter when searching under a number of conditions.
If you want to search for ranges such as start and end dates, you can still search using the ‘&’ delimiter.

Example) If you want to search for products that cost over KRW1,000 within a particular brand

GET https://{{mallid}}.cafe24api.com/api/v2/products?brand_code=B000000A&price_min=1000

2. Searching with multiple conditions in a parameter

A number of values can be simultaneously searched using a comma (,) when supported by the API.
The search condition added by a comma (,) is an OR condition and all values ​​corresponding to the search condition are searched.

Example) When querying information of a product containing item codes 11, 12, and 13

GET https://{{mallid}}.cafe24api.com/api/v2/products?product_no=11,12,13

3. Multi-shopping mall information query

If you specify a particular shop number in an API query, you can query information from the corresponding multi-shopping mall.
When a specific shop number is not designated, the information of the first shopping mall (basic shopping mall) is queried.

Example) How to enter parameters

GET https://{{mallid}}.cafe24api.com/api/v2/products?shop_no=2

4. Detailed query and single item query

Most entities are available for query by specifying the entity ID to the URL.
Only one entity can be queried in a detailed query, whereas more entries will be returned in a list query.

Example) How to run a detailed query for product number 128

GET https://{{mallid}}.cafe24api.com/api/v2/admin/products/128

In the list query, a single item can be retrieved by using the parameter as shown in the example, but in this case, the same information as the list query is retrieved since this case represents a single item query inside the list query.

Example) When you query product number 128 using parameters

GET https://{{mallid}}.cafe24api.com/api/v2/admin/products?product_no=128

5. Pagination

Not all results may be queried when there are too many items to be displayed in the list query.
If you want to see more results at once, you can use the 'limit' parameter to increase the number of query results.
If the 'limit' parameter is not used, the query will be conducted only based on the default value of 'limit.'

Example) View 100 products at a time

GET https://{{mallid}}.cafe24api.com/api/v2/admin/products?limit=100

The number of queries that can be extended with the 'limit' parameter can only be modified up to the 'maximum value' defined for each API.
If not all data can be retrieved based on the 'maximum limit value,' the 'offset' parameter can be used.

Example) Querying from the 201st to the 300th product

GET https://{{mallid}}.cafe24api.com/api/v2/admin/products?limit=100&offset=201

6. Field parameters

When you want to see particular values out ​​of the API‘s query values, you can query these values ​​using the field parameter.

Example) Querying only the product name and product number parameters when viewing the products

GET https://{{mallid}}.cafe24api.com/api/v2/admin/products?fields=product_name,product_no

7. Embed parameters

If you need to display a sub-entity (e.g item, inventory) belonging to a product at the time of the product search, you can use the 'embed' parameter to display the data of the sub-entity together.
The 'embed' parameters are only available in APIs that support them.

Example) Displaying inventory and item data together when querying goods

GET https://{{mallid}}.cafe24api.com/api/v2/admin/products?embed=variants,inventories

API request limit policy

The cafe24 API works with the "Leaky Bucket" algorithm. The Leaky Bucket algorithm effectively limits the number of unusually large API requests for performance whereas it does not restrict the routine API requests.
The cafe24 APIs stack API requests in the Bucket. API requests are restricted after the Bucket becomes full 10 times in each shopping mall.
The bucket is decreased once every second, and more API calls as much as it is decreased can be made.

 

- If your app calls the API once every second, you can continue to use the API call without any restrictions.
- If there are more than 10 calls within 1 second, it displays the 429 error (Too Many Requests).

 

You can avoid 429 errors by checking the X-Api-Call-Limit in the header.
You can see how many API calls have been made at the store and how much Bucket space is left.

Example) Checking the X-Api-Call-Limit in the header

X-Api-Call-Limit : 1/10
This value decreases every second. If the value was ‘9/10,’ it shall decrease to ‘6/10’ in 3 seconds.