닫기
  • Admin API

  • Front API

  • D.Collection API

  • Cafe24 Analytics API (Beta)

    For more details, select a category below.

    Welcome to Open API. Developers can use APIs provided by Cafe24 to develop and publish apps on Cafe24 Store.

    • img
      Admin API

      Retrieve, create, update, and delete data of stores, including product, customer information, and board data.

      Go to

    • img
      Front API

      You can retrieve the information of a product added to a store, or use the [Add to cart] feature.

      Go to

    • img
      D.Collection API

      Develop a service that allows users to boost sales of stores by retrieving store and product data that are part of the D.Collection program.

      Go to

    • img
      Cafe24 Analytics API (Beta)

      With Cafe24 Analytics API, you can develop a service that provides store merchants with customer behavior data for their online store.

      바로가기

    non-print

    Admin API

    Introduction

    Cafe24 API

    Cafe24 Shopping Mall API is an API provided to app store join developers and third-party solution providers to provide services related to shopping malls.

    Cafe24 API is a RESTful architecture that provides OAuth 2.0 based authentication system, a standard HTTP request method, a predictable endpoint URL, and an HTTP code based error message.

    API Diagram

    Check out the overall structure of Cafe24 API through the diagram that describes the relations between resources.

    Request/Response Format

    • API request and response support JSON format.

    • For privacy protection purposes, Cafe 24 API only supports HTTPS protocol.

    • Dates properties are provided in the ISO_8601 format. : YYYY-MM-DDTHH:MM:SS + 09:00

    Request Example (search)
    Request Example (register/modify)
    Right response example
    {
        "resource": {
            "key": "value",
            "key": "value"
         }
    }
    Error response example
    {
        "error": {
            "code": "error code",
            "message": "error message",
            "more_info": {
            }
        }
    }

    Method

    Each resources support Create, Read, Update, and Delete and API can be used by using standard HTTP method.

    • POST : Create the resource.

    • GET: Read data the resource.

    • PUT : Modify(Update) the resource.

    • DELETE : Delete (delete) the resource.

    Admin API Intro

    The Admin API is suitable for the shopping mall administrator to query, create, modify, and delete information in the shopping mall. The Admin API can get almost every information of resource and available only after pass Oauth 2.0 authentication.

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

    API Status Code

    Code Case Solutions
    200 When GET success, PUT success, DELETE success
    201 When POST success
    207 When status is vary as requested multiple objects. Checks the error status of each object and deal with errors according to its status.
    400 Server does not understand request
    1) Wrong Content-Type declaration
    2) Application/type is not json
    Check for the "Content-Type" is application/json when request.
    400 When not use URL Encoded character in API Request URL Check whether API request URL has URL encoded character.
    401 1) When Access Token is missing
    2) When Access Token is wrong
    3) When Access Token is expired
    4) Unrecognizable client
    Check whether the Access Token is granted and used via valid process.
    401 client_id is missing when using Front API Check whether using valid client_id.
    403 1) Access Token does not include Scope authority
    2) Access forbidden for Front API
    Check the Scope of API or setting of shopping mall whether you have the authority for request API.
    403 Not a https protocol Check whether request protocol is https.
    403 Shopping mall has not been upgraded to a 'New product' mall Shopping mall has to be upgraded to a 'New product' mall in order to use API.
    403 (Admin API) App has been deleted from the shopping mall. Install again after check whether the App is installed at the shopping mall.
    403 (Front API) App has been deleted from the shopping mall. Install again after check whether the App is installed at the shopping mall.
    404 1) When requested wrong API URL
    2) When cannot found resource
    3) When missing {#id}
    Check the API reference for errors in URL.
    409 The requested resource already exists request data to be corrected.
    422 When requested value is unprocessible with API reference
    1) Missing necessary parameter
    2) Not same with API reference
    Check the API reference for whether omitted necessary parameter or put a wrong value.
    429 When client requested over than Bucket volume Request later in a while for not exceed maximum request.
    500 Internal server error or unknown error A temporary error has occurred. Please try again.
    503 Server is unavailable Please contact to developer center.
    503 Server is unavailable. Cannot use API right now Please contact to developer center.
    504 Timeout Response timeout due to a temporary error. Please try again later.

    How to use GET API

    Cafe24 API provides several ways to get the data.

    The following describes the different ways to recall data using various parameters when inquiring an API.

    1. Add search conditions

    You can use search conditions by adding parameters to an endpoint.

    If you want to use multiple search conditions, separate them with ampersands (&).

    You can also specify a date and time if it is supported by the API you are using.

    Add search conditions
    E.g. When searching for products of which price is KRW 1,000 or higher in a certain brand
    GET https://{mallid}.cafe24api.com/api/v2/products?brand_code=B000000A&price_min=1000
    
    E.g. When searching for products by specifying the date range in which they were added
    GET https://{mallid}.cafe24api.com/api/v2/products?created_start_date=2018-01-03&created_end_date=2018-02-03
    
    E.g. When searching for products by specifying the date range in which they were edited
    GET https://{mallid}.cafe24api.com/api/v2/products?updated_start_date=2018-01-03T14:01:26+09:00&updated_end_date=2018-02-03T14:01:26+09:00

    2. Use commas to search for more than one item

    Use commas to search for data for more than one item. (You can search for up to 100 items in one query.)

    The search conditions separated by commas are OR conditions; You can view all data corresponding to the conditions.

    Use commas to search for more than one item
    E.g. When searching for products by specifying their product numbers
    GET https://{mallid}.cafe24api.com/api/v2/products?product_no=11,12,13
    
    E.g. When searching for products by specifying their product numbers and product codes
    GET https://{mallid}.cafe24api.com/api/v2/products?product_no=11,12,13&product_code=P000000X,P000000W

    3. View multi-language store information

    You can search for the information of a localized store by specifying its multi-language store number.

    If you don't, the information of the default store will be shown.

    View multi-language store information
    E.g. When searching for products in a certain localized store
    GET https://{mallid}.cafe24api.com/api/v2/products?shop_no=2

    4. Retrieve single item & details

    You can retrieve the details of a resource by specifying its ID.

    You can only search for the details of one single product in one query

    but you can retrieve more details than when you search for multiple products.

    Retrieve single item & details
    E.g. When retrieving the details of a product by specifying its product number
    GET https://{mallid}.cafe24api.com/api/v2/admin/products/128
    
    
    E.g. When retrieving the details of one single product by specifying its product number
    GET https://{mallid}.cafe24api.com/api/v2/admin/products?product_no=128

    5. Pagination

    If there are too many results, you define the number of details returned in one response with the "limit" parameter.

    If you are not able to view all details with the maximum value of the "limit" parameter, you can use the "offset" parameter.

    Pagination
    E.g. When paging the details of 100 products at a time
    GET https://{mallid}.cafe24api.com/api/v2/admin/products?limit=100
    
    
    E.g. When retrieving details from the 201st to the 300th product
    GET https://{mallid}.cafe24api.com/api/v2/admin/products?limit=100&offset=200

    6. Retrieve specific items

    Use the "fields" parameter to view specific details

    Retrieve specific items
    E.g. When retrieving the product name and product name only
    GET https://{mallid}.cafe24api.com/api/v2/admin/products?fields=product_name,product_no

    7. View sub-resources

    If supported by the API you are using, you can search for the data for sub-resources with the "embed" parameter.

    View sub-resources
    E.g. When searching for the variants and stock of a product
    GET https://{mallid}.cafe24api.com/api/v2/admin/products/570?embed=variants,inventories

    API Limit

    Cafe 24 API works with the "Leaky Bucket" algorithm. The Leaky Bucket algorithm has the effect of limiting the number of API requests that are abnormally high for performance purposes, but also allowing the use of routine API requests without restriction.

    Cafe 24 API stacks API requests in the dock. Bucket is limited to API calls when up to "Request Limit" per shopping mall are filled. The Bucket is decreased twice per second and can be recalled as a decrease.

    • If the app calls the API twice a second, you can continue to use the API calls without restriction.

    • If more than "Request Limit" calls are generated momentarily within a second, return the 429 error (too many requests).

    • If more than 10 requests per second are made from the same IP address of an online store, the requests may be considered abnormal or malicious.

    You can avoid the 429 error by checking the X-Api-Call-Limit with the header. You can see how many APIs have been ordered from the shopping mall, and how many Buckets are left.

    X-Api-Call-Limit : 1/40

    Versioning

    Past Versions are provided in date format to support APIs that are not compatible with Version yyyy-mm-dd

    User may define which version to use by setting value in the custom header "X-Cafe24-Api-Version". Without this value set, API version will follow version set in the app setup.

    App version can be found in below path.

    • Developer Center (sign-in) > Apps > App setup > "Version settings" underneath "App credentials"

    A version is valid for 1 year since the release of the latest version.

    In case your version get expired, oldest version currently valid will be used instead.

    Example (request)

    Authentication

    Get Authentication Code

    When requesting a token to be issued, the code used can not be reused and expires one minute after the code is issued.

    • {mallid} : Enter the appropriate shopping mall ID.

    • {client_id} : Enter the client_id of the app created in the developer center.

    • {state} : The value entered above is returned as a value to prevent modulation.

    • {redirect_anI} : Enter the Redirect URL for the app created by the developer center.

    • {script} : You can enter the privileges of the resource server to access the access token.

    To receive an access token, you must request a cotton access code. The access code is used if the client is in the form of a Web application.

    Example (request)
    GET 'https://{mallid}.cafe24api.com/api/v2/oauth/authorize?response_type=code&client_id={client_id}&state={state}&redirect_uri={redirect_uri}&scope={scope}'
    Example (response)
    HTTP/1.1 302 Found
    Location: {redirect_uri}?code={authorize_code}&state={state}

    Get Access Token

    You can get a user token to actually call up the API using the issued authentication code.

    • {mallid} : Enter the corresponding shopping mall ID.

    • {client_id} : Enter the client_id of the app created in the developer center.

    • {client_secret} : Enter the client_secret for the app created at the developer center.

    • {code} : Enter the issued code.

    • {redirect_anI} : Enter the Redirect URL for the app created by the developer center.

    access_token : This is the approach token used by clients to access the resource server.

    refresh_token : This token is used to reissue after the approach token expires.

    Example (request)
    Example (response)
    HTTP/1.1 200 OK
    {
        "access_token": "0iqR5nM5EJIq..........",
        "expires_at": "2021-03-01T14:00:00.000",
        "refresh_token": "JeTJ7XpnFC0P..........",
        "refresh_token_expires_at": "2021-03-15T12:00:00.000",
        "client_id": "BrIfqEKoPxeE..........",
        "mall_id": "yourmall",
        "user_id": "test",
        "scopes": [
            "mall.read_order",
            "mall.read_product",
            "mall.read_store",
            "...etc...",
        ],
        "issued_at": "2021-03-01T12:00:00.000"
    }

    Get Access Token using refresh token

    The approach token is unavilable after two hours after issued. After the approach token has expired, it must be reissued before the resource server can be accessed. If you have already received the approach token, you can re-issue it using refresh_token.

    The refresh token is valid for two weeks. If you request it before refresh token is finished, it is returned with the updated access token. You can not use the old refresh token after it has expired.

    You can get a user token to actually call up the API using the issued authentication code.

    • {mallid} : Enter the corresponding shopping mall ID.

    • {domain} : Enter the domain of the shopping mall.

    • {Client_id} : Enter the client_id of the app created by the developer center.

    • {client_secret} : Enter the client_secret of the app created by the developer center.

    • {refresh_token} : Enter the refresh_token received when the token was issued.

    access_token : Used as access token when clients access resource servers.

    refresh_token : This token is used to reissue after the approach token expires.

    Example (request)
    Example (response)
    HTTP/1.1 200 OK
    {
        "access_token": "21EZes0dGSfN..........",
        "expires_at": "2021-03-01T15:50:00.000",
        "refresh_token": "xLlhWztQHBik............",
        "refresh_token_expires_at": "2021-03-15T13:50:00.000",
        "client_id": "BrIfqEKoPxeE..........",
        "mall_id": "yourmall",
        "user_id": "test",
        "scopes": [
            "mall.read_order",
            "mall.read_product",
            "mall.read_store",
            "...etc...",
        ],
        "issued_at": "2021-03-01T13:50:00.000"
    }

    REST API

    Front API

    Introduction

    Cafe24 API

    Cafe24 Shopping Mall API is an API provided to app store join developers and third-party solution providers to provide services related to shopping malls.

    Cafe24 API is a RESTful architecture that provides OAuth 2.0 based authentication system, a standard HTTP request method, a predictable endpoint URL, and an HTTP code based error message..

    Front API Intro

    Front API is suitable for public information(displayed product information) or for customer to get their own information or write at a board. Front API is limited for some informations compare to Admin API.

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

    API Diagram

    Check out the overall structure of Cafe24 API through the diagram that describes the relations between resources.

    Request/Response Format

    • API request and response support JSON format.

    • For privacy protection purposes, Cafe 24 API only supports HTTPS protocol.

    • Dates properties are provided in the ISO_8601 format. : YYYY-MM-DDTHH:MM:SS + 09:00

    Request Example (search)
    Request Example (register/modify)
    Right response example
    {
      "resource": {
          "key": "value",
          "key": "value"
       }
    }
    Error response example
    {
      "error": {
          "code": "error code",
          "message": "error message",
          "more_info": {
          }
      }
    }

    API Status Code

    Code Case Solutions
    200 When GET success, PUT success, DELETE success
    201 When POST success
    207 When status is vary as requested multiple objects. Checks the error status of each object and deal with errors according to its status.
    400 Server does not understand request
    1) Wrong Content-Type declaration
    2) Application/type is not json
    Check for the "Content-Type" is application/json when request.
    400 When not use URL Encoded character in API Request URL Check whether API request URL has URL encoded character.
    401 1) When Access Token is missing
    2) When Access Token is wrong
    3) When Access Token is expired
    4) Unrecognizable client
    Check whether the Access Token is granted and used via valid process.
    401 client_id is missing when using Front API Check whether using valid client_id.
    403 1) Access Token does not include Scope authority
    2) Access forbidden for Front API
    Check the Scope of API or setting of shopping mall whether you have the authority for request API.
    403 Not a https protocol Check whether request protocol is https.
    403 Shopping mall has not been upgraded to a 'New product' mall Shopping mall has to be upgraded to a 'New product' mall in order to use API.
    403 (Admin API) App has been deleted from the shopping mall. Install again after check whether the App is installed at the shopping mall.
    403 (Front API) App has been deleted from the shopping mall. Install again after check whether the App is installed at the shopping mall.
    404 1) When requested wrong API URL
    2) When cannot found resource
    3) When missing {#id}
    Check the API reference for errors in URL.
    409 The requested resource already exists request data to be corrected.
    422 When requested value is unprocessible with API reference
    1) Missing necessary parameter
    2) Not same with API reference
    Check the API reference for whether omitted necessary parameter or put a wrong value.
    429 When client requested over than Bucket volume Request later in a while for not exceed maximum request.
    500 Internal server error or unknown error A temporary error has occurred. Please try again.
    503 Server is unavailable Please contact to developer center.
    503 Server is unavailable. Cannot use API right now Please contact to developer center.
    504 Timeout Response timeout due to a temporary error. Please try again later.

    How to use GET API

    Cafe24 API provides several ways to get the data.

    The following describes the different ways to recall data using various parameters when inquiring an API.

    1. Add search conditions

    You can use search conditions by adding parameters to an endpoint.

    If you want to use multiple search conditions, separate them with ampersands (&).

    You can also specify a date and time if it is supported by the API you are using.

    Add search conditions
    E.g. When searching for products of which price is KRW 1,000 or higher in a certain brand
    GET https://{mallid}.cafe24api.com/api/v2/products?brand_code=B000000A&price_min=1000
    
    E.g. When searching for products by specifying the date range in which they were added
    GET https://{mallid}.cafe24api.com/api/v2/products?created_start_date=2018-01-03&created_end_date=2018-02-03
    
    E.g. When searching for products by specifying the date range in which they were edited
    GET https://{mallid}.cafe24api.com/api/v2/products?updated_start_date=2018-01-03T14:01:26+09:00&updated_end_date=2018-02-03T14:01:26+09:00

    2. Use commas to search for more than one item

    Use commas to search for data for more than one item. (You can search for up to 100 items in one query.)

    The search conditions separated by commas are OR conditions; You can view all data corresponding to the conditions.

    Use commas to search for more than one item
    E.g. When searching for products by specifying their product numbers
    GET https://{mallid}.cafe24api.com/api/v2/products?product_no=11,12,13
    
    E.g. When searching for products by specifying their product numbers and product codes
    GET https://{mallid}.cafe24api.com/api/v2/products?product_no=11,12,13&product_code=P000000X,P000000W

    3. View multi-language store information

    You can search for the information of a localized store by specifying its multi-language store number.

    If you don't, the information of the default store will be shown.

    View multi-language store information
    E.g. When searching for products in a certain localized store
    GET https://{mallid}.cafe24api.com/api/v2/products?shop_no=2

    4. Retrieve single item & details

    You can retrieve the details of a resource by specifying its ID.

    You can only search for the details of one single product in one query

    but you can retrieve more details than when you search for multiple products.

    Retrieve single item & details
    E.g. When retrieving the details of a product by specifying its product number
    GET https://{mallid}.cafe24api.com/api/v2/admin/products/128
    
    
    E.g. When retrieving the details of one single product by specifying its product number
    GET https://{mallid}.cafe24api.com/api/v2/admin/products?product_no=128

    5. Pagination

    If there are too many results, you define the number of details returned in one response with the "limit" parameter.

    If you are not able to view all details with the maximum value of the "limit" parameter, you can use the "offset" parameter.

    Pagination
    E.g. When paging the details of 100 products at a time
    GET https://{mallid}.cafe24api.com/api/v2/admin/products?limit=100
    
    
    E.g. When retrieving details from the 201st to the 300th product
    GET https://{mallid}.cafe24api.com/api/v2/admin/products?limit=100&offset=200

    6. Retrieve specific items

    Use the "fields" parameter to view specific details

    Retrieve specific items
    E.g. When retrieving the product name and product name only
    GET https://{mallid}.cafe24api.com/api/v2/admin/products?fields=product_name,product_no

    7. View sub-resources

    If supported by the API you are using, you can search for the data for sub-resources with the "embed" parameter.

    View sub-resources
    E.g. When searching for the variants and stock of a product
    GET https://{mallid}.cafe24api.com/api/v2/admin/products/570?embed=variants,inventories

    API Limit

    Cafe 24 API works with the "Leaky Bucket" algorithm. The Leaky Bucket algorithm has the effect of limiting the number of API requests that are abnormally high for performance purposes, but also allowing the use of routine API requests without restriction.

    Cafe 24 API stacks API requests in the dock. Bucket is limited to API calls when up to "Request Limit" per shopping mall are filled. The Bucket is decreased twice per second and can be recalled as a decrease.

    • If the app calls the API twice a second, you can continue to use the API calls without restriction.

    • If more than "Request Limit" calls are generated momentarily within a second, return the 429 error (too many requests).

    • If more than 10 requests per second are made from the same IP address of an online store, the requests may be considered abnormal or malicious.

    You can avoid the 429 error by checking the X-Api-Call-Limit with the header. You can see how many APIs have been ordered from the shopping mall, and how many Buckets are left.

    X-Api-Call-Limit : 1/40

    Versioning

    Past Versions are provided in date format to support APIs that are not compatible with Version yyyy-mm-dd

    User may define which version to use by setting value in the custom header "X-Cafe24-Api-Version". Without this value set, API version will follow version set in the app setup.

    App version can be found in below path.

    • Developer Center (sign-in) > Apps > App setup > "Version settings" underneath "App credentials"

    A version is valid for 1 year since the release of the latest version.

    In case your version get expired, oldest version currently valid will be used instead.

    Example (request)

    REST API

    D.Collection API

    Introduction

    D.Collection API

    D.Collection APIs can only be used by Cafe24-approved partners for developing marketing and ad services to help users increase sales in their Cafe24 store.

    Information obtain through the APIs cannot be used for unauthorized purposes.

    Cafe24 uses the Basic Auth based authentication system, the standard HTTP request method, easy-to-understand endpoint URLs, and HTTP code-based error messages for its D.Collection APIs.

    Request/Response Format

    • API request and response support JSON format.

    • For privacy protection purposes, Cafe 24 API only supports HTTPS protocol.

    • Dates properties are provided in the ISO_8601 format. : YYYY-MM-DDTHH:MM:SS + 09:00

    • We follow ISO_4217 format for payment currency codes.

    Request Example (search)
    Right response example
    {
      "resource": {
          "key": "value",
          "key": "value"
       }
    }
    Error response example
    {
      "error": {
          "code": "error code",
          "message": "error message",
          "more_info": {
          }
      }
    }

    Method

    Each resources support Create, Read, Update, and Delete and API can be used by using standard HTTP method.

    • GET : Read data the resource.

    D.Collection API Intro

    Develop a service that allows users to boost sales of stores by retrieving store and product data that are part of the D.Collection program.

    example
    Retrieve a store : https://dcollection-api.cafe24.com/api/shops
    Retrieve a product : https://dcollection-api.cafe24.com/api/products?dcollection_product_category={dcollection_product_category}

    API Status Code

    Code Case Solutions
    200 When GET success
    401 1) When you call APIs without an Access Token
    2) When an Access Token is invalid
    3) If a client who requested for verification has invalid permission
    Check whether the request was made with a valid Access Token.
    404 1) When you call the wrong API URL
    2) When the resource cannot be found
    Check the API documentation to see if there are any errors in the endpoint URL.
    422 When the retrieve or process request values are not the same as the specifications.
    2) Invalid input value in the required field.
    Check the API documentation to see if any required parameters are missing or if you input invalid values.
    429 API calls from the client side have exceeded the limit. (40 times per minute.) Try again later to reset the API request limits.
    500 Internal server error, unknown error Contact us via Cafe24 Developers.
    503 Currently the server is down Contact us via Cafe24 Developers.
    504 Request timeout A temporary error has occurred, causing response delays. Please try again later.

    How to use GET API

    D.Collection API provides several ways to get the data.

    The following describes the different ways to recall data using various parameters when inquiring an API.

    1. Add search conditions

    You can use search conditions by adding parameters to an endpoint.

    If you want to use multiple search conditions, separate them with ampersands (&).

    You can also specify a date and time if it is supported by the API you are using.

    Add search conditions
    E.g. Retrieve a store with a specific name
    GET https://dcollection-api.cafe24.com/api/shops?shop_name=nelly
    
    E.g. Retrieve a store with a specific name and properties
    GET https://dcollection-api.cafe24.com/api/shops?shop_name=nelly&shop_properties=hartebeest
    
    E.g. Retrieve products under a specific category
    GET https://dcollection-api.cafe24.com/api/products?dcollection_product_category=C200802
    
    E.g. Retrieve products under a specific category and a store name
    GET https://dcollection-api.cafe24.com/api/products?dcollection_product_category=C200802&shop_name=안다르

    2. Use commas to search for more than one item

    Use commas to search for data for more than one item. (You can search for up to 100 items in one query.)

    The search conditions separated by commas are OR conditions; You can view all data corresponding to the conditions.

    Use commas to search for more than one item
    E.g. Retrieve stores with specific names
    GET https://dcollection-api.cafe24.com/api/shops?shop_name=nelly,reseda
    
    E.g. Retrieve products under a specific category or specific product names
    GET https://dcollection-api.cafe24.com/api/products?dcollection_product_category=C200802&product_name=안다르,에어쿨링

    3. Pagination

    If there are too many results, you define the number of details returned in one response with the "limit" parameter.

    If you are not able to view all details with the maximum value of the "limit" parameter, you can use the "offset" parameter.

    Pagination
    E.g. When paging the details of 100 stores at a time
    GET https://dcollection-api.cafe24.com/api/shops?limit=100
    
    E.g. When paging the details of 100 products at a time
    GET https://dcollection-api.cafe24.com/api/products?dcollection_product_category=C200802&limit=100
    
    E.g. When retrieving details from the 201st to the 300th store
    GET https://dcollection-api.cafe24.com/api/shops?limit=100&offset=200
    
    E.g. When retrieving details from the 201st to the 300th product
    GET https://dcollection-api.cafe24.com/api/products?dcollection_product_category=C200802&limit=100&offset=200

    API Limit

    D.Collection APIs use Laravel throttle middleware to limit the API calls to 40 times per minute per IP.

    A count will be deducted per request, and if your requests exceeds 40 times within a minute, then you will receive a 429 error (Too Many Requests Error).

    Check the X-RateLimit–Limit and the X-RateLimit–Remaining in the Header to avoid 429 errors.

    X-Api-Call-Limit : 1/40

    D.Collection API

    Cafe24 Analytics API (Beta)

    Introduction

    Cafe24 Analytics API (Beta)

    To develop a data provision service, you can use Cafe24 Analytics API to retrieve online customer data. Please note that prior approval from Cafe24 is required to access this API.

    Please use any information obtained through this API only for the approved channels, media platforms, or purposes. Any other use is strictly prohibited.

    Data before 2023 is based on data from EC Admin > Statistics > Access Statistics. Data after 2023 is based on data from EC Admin > Statistics > Cafe24 Analytics.

    Cafe24 Analytics API provides an OAuth 2.0-based authentication system, standard HTTP request methods, predictable endpoint URLs, and HTTP status code-based error messages.

    Request/Response Format

    • API requests and responses support JSON format.
    • To protect personal information, Cafe24 Analytics API only supports HTTPS protocol.

    • Date attribute format is ISO_8601 E.g. YYYY-MM-DDTHH:MM:SS+09:00

    Request sample (GET)
    Sample result
    {
      "resource": {
          "key": "value",
          "key": "value"
       }
    }
    Failure response sample
    {
      "error": {
          "code": "error code",
          "message": "error message",
          "more_info": {
          }
      }
    }

    Method

    Each resource supports "Read,” and you can use it by utilizing standard HTTP methods.

    • GET: You can retrieve (Read) the corresponding resource information.

    Cafe24 Analytics API Intro

    Cafe24 Analytics API is designed to retrieve customer behavior data for online stores. It can retrieve nearly all customer behavior data and can only be accessed by users authenticated through a separate OAuth 2.0 authentication process.

    Example
    Page view : https://ca-api.cafe24data.com/visitors/pageview?mall_id=몰아이디&shop_no=1&start_date=2023-02-01&end_date=2023-02-10
    Visitor : https://ca-api.cafe24data.com/visitors/view?mall_id=몰아이디&shop_no=1&start_date=2023-02-01&end_date=2023-02-10

    API Status Code

    Code Case Troubleshooting
    200 GET is successful
    401 1) API was called without an access token
    2) Access token is invalid
    3) Access Token is expired
    4) Client is unknown
    Check if the access token was obtained through a valid issuance process.
    401 "client_id" is not entered. Check if "client_id" is valid.
    403 Access token is valid, but the user does not have the required scope permissions. Check the API scopes or store settings to ensure that you have the necessary permissions to call this API.
    403 Not a HTTPS protocol Check if you used HTTPS method to call this API.
    404 1) Wrong API URL was called
    2) Resource cannot be found
    3) {#id} is missing
    Refer to the API documentation to make sure that the correct endpoint URL has been used for the API call.
    422 Retrieve or Process request has different values than the specifications

    1) Required parameters are missing
    2) Entered parameters are not the same as the ones in the specifications
    Refer to the API documentation to make sure that all required parameters are included and that the entered values are valid according to the specifications.
    429 Client's API requests have consumed all tokens in the bucket. Wait a moment and try again, make sure not to exceed the maximum allowed number of API requests.
    500 Internal server errors, unknown errors A temporary error has occurred, try again later.
    503 Server is down Contact us through Cafe24 Developers.
    503 Server is down, API cannot be used Contact us through Cafe24 Developers.
    504 Request timeout (Timeout) A temporary error has occurred and response is being delayed, try again later.

    How to use GET API

    Cafe24 Analytics API offers various methods to retrieve data, and the following describes how to call data in various ways using different parameters.

    1. Adding search parameters

    You can add parameters to an endpoint to search with multiple conditions.

    If you want to search multiple conditions, use "&" as a delimiter.

    Adding search parameters
    E.g. Retrieve the page view count for a specific store within a specified time range.
    GET https://ca-api.cafe24data.com/visitors/pageview?mall_id=nelly&start_date=2023-01-01&end_date=2023-02-01
    
    E.g. Retrieve the visitor count for a specific store by domain within a specified time range.
    GET https://ca-api.cafe24data.com/visitpaths/domains?mall_id=nelly&start_date=2023-01-01&end_date=2023-02-01
    
    E.g. Retrieve the sales amount and quantity for a specific store by product within a specified time range.
    GET https://ca-api.cafe24data.com/products/sales?mall_id=nelly&start_date=2023-01-01&end_date=2023-02-01
    
    E.g. Retrieve the count of customers who placed an order, count of orders, and sales amount by the hour for a specific store within a specified time range.
    GET https://ca-api.cafe24data.com/sales/times?mall_id=nelly&start_date=2023-01-01&end_date=2023-02-01

    2. Pagination

    By default, the API retrieves 100 search results.

    If there are more results to be retrieved, you can use the "offset" parameter to retrieve an additional 100 results per request.

    Pagination
    E.g. Retrieve search result items (1-100)
    GET https://ca-api.cafe24data.com/visitors/pageview?mall_id=nelly&start_date=2023-01-01&end_date=2023-02-01
    
    E.g. Retrieve search result items (101-200)
    GET hhttps://ca-api.cafe24data.com/visitors/pageview?mall_id=nelly&start_date=2023-01-01&end_date=2023-02-01&offset=100
    
    E.g. Retrieve search result items (201-300)
    GET hhttps://ca-api.cafe24data.com/visitors/pageview?mall_id=nelly&start_date=2023-01-01&end_date=2023-02-01&offset=200
    
    E.g. Retrieve search result items (301-400)
    GET hhttps://ca-api.cafe24data.com/visitors/pageview?mall_id=nelly&start_date=2023-01-01&end_date=2023-02-01&offset=300

    API Limit

    CA API uses "Token Bucket" algorithm.

    Tokens are added to the bucket at a "fixed rate," and each request for a resource consumes one token from the bucket. If the bucket is empty, request will be limited. One token will be added to the bucket every two seconds.

    • If an app makes calls API at a rate of once every two seconds, it can continue to use the API without any limitations.
    • If the number of calls made "exceeds the call limit" in one second, 429 error (Too Many Requests) will be returned.

    To avoid 429 errors, you can check how many tokens are left in the bucket by looking at the "x-ratelimit-remaining" field in the Response Header under Header.

    Response Header
    > X-RateLimit-Remaining: 9
    > X-RateLimit-Requested-Tokens: 1
    > X-RateLimit-Burst-Capacity: 10
    > X-RateLimit-Replenish-Rate: 2

    Authentication

    Access token can be used as a token issued by the shopping mall (EC Admin API).

    Get Authentication Code

    The code used to obtain a token is not reusable, and expires one minute after the issuance.

    • {mallid}: Enter store ID.

    • {client_id}: Enter "client_id" generated for your app on Cafe24 Developers.

    • {state}: To prevent tampering, enter a value that will be returned along with the code.

    • {redirect_uri}: Enter Redirect URL generated for your app on Cafe24 Developers.

    • {scope}: Specify the permissions for the resource servers that you want to access with the access token.

    To obtain an access token, you must request an access code first. The access code is for client-side web applications. Request the access cod on a web browser not through cURL.

    Request Copy
    GET 'https://{mallid}.cafe24api.com/api/v2/oauth/authorize?response_type=code&client_id={client_id}&state={state}&redirect_uri={redirect_uri}&scope={scope}'
    Sample result
    HTTP/1.1 302 Found
    Location: {redirect_uri}?code={authorize_code}&state={state}

    Get Access Token

    With the access code, you can get a user token (Access token, Refresh token) to call the API.

    • {mallid}: Enter store ID.

    • {client_id}: Enter client_id generated for your app on Cafe24 Developers.

    • {client_secret}: Enter "client_secret" generated for your app on Cafe24 Developers.

    • {code}: Enter the obtained code.

    • {redirect_uri}: Enter "Redirect URL" generated for your app on Cafe24 Developers.

    access_token: This token is used by the client to access the resource servers.

    refresh_token: This token is used to obtain a new access token after the previous one has expired.

    Request sample
    Sample result
    HTTP/1.1 200 OK
    {
        "access_token": "0iqR5nM5EJIq..........",
        "expires_at": "2021-03-01T14:00:00.000",
        "refresh_token": "JeTJ7XpnFC0P..........",
        "refresh_token_expires_at": "2021-03-15T12:00:00.000",
        "client_id": "BrIfqEKoPxeE..........",
        "mall_id": "yourmall",
        "user_id": "test",
        "scopes": [
            "mall.analytics",
            "...etc...",
        ],
        "issued_at": "2021-03-01T12:00:00.000"
    }

    Get Access Token using refresh token

    Access token expires two hours after the issuance. Once expired, you need to obtain a new access token using the refresh token to continue accessing the resource servers. If you have obtained an access token, you can use "refresh_token" to renew it.

    Refresh token is valid for 2 weeks. If you make a request before the refresh token is expired, both renewed access token and new refresh token will be returned. The existing refresh token will no longer be valid.

    With the access code, you can get a user token (Access token, Refresh token) to call the API.

    • {mallid}: Enter store ID.

    • {domain}: Enter store domain.

    • {client_id}: Enter "client_id" generated for your app on Cafe24 Developers.

    • {client_secret}: Enter "client_secret" generated for your app on Cafe24 Developers.

    • {refresh_token}: Enter token "refresh_token" obtained while getting an access token.

    access_token: This token is used by the client to access the resource servers.

    refresh_token: This token is used to obtain a new access token after the previous one has expired.

    Request sample
    Sample result
    HTTP/1.1 200 OK
    {
        "access_token": "21EZes0dGSfN..........",
        "expires_at": "2021-03-01T15:50:00.000",
        "refresh_token": "xLlhWztQHBik............",
        "refresh_token_expires_at": "2021-03-15T13:50:00.000",
        "client_id": "BrIfqEKoPxeE..........",
        "mall_id": "yourmall",
        "user_id": "test",
        "scopes": [
            "mall.analytics",
            "...etc...",
        ],
        "issued_at": "2021-03-01T13:50:00.000"
    }

    Cafe24 Analytics API

    Top