Guidelines for Integrating Third-Party Algorithms on the Tracking Page?

Introduction

If you require refined operations and possess some development capabilities, 17TRACK supports you in using your own recommendation algorithm to achieve personalized product recommendations. We will request the API address you provide and display the product information in the product recommendation section of the tracking page. Below are the specific integration process guidelines.

Integration Steps

- Configure Tracking Page
- Provide the API address; you need to implement this API service using our integration method to return the required product information for recommendation.

API Integration

3.1 Basic Information

Item	Content	Remarks
API Address	Provided by you, filled in the brand tracking page editor	We will perform a basic connectivity check on this address
Protocol	Http
Request Format	JSON	Currently, only JSON transmission is supported
Response Format	JSON	Currently, only JSON transmission is supported

3.2 Authentication

You need to provide an API that supports anonymous access. If security is needed, please open a whitelist to support our access.

3.3 Interface Integration

We will call the API you provide. We have defined the request parameters and the desired response content. You need to integrate according to the defined request input and output.

3.3.1 Request Method

POST

3.3.2 Request Parameters

- Request Example

curl --location 'https://example.com' \
--header 'x-shopify-domian: example.myshopify.com' \
--header 'Content-Type: application/json' \
--data '{
    "shop_name": "example.myshopify.com",
    "limit": 10,
    "currency": "USD",
    "ids": ["323000"]
}'

{
    "shop_name": "example.myshopify.com",
    "limit": 10, //maximum of 10 items
    "currency": "USD",
    "ids": ["323000"]
}

- Description of the request

Field	Name	Type	Required	Description
shop_name	Store Name	String	Yes	Full domain name of the Shopify store
limit	Return Quantity	Num	Yes	Maximum number of products to display, currently 10
currency	Currency	String	Yes	Current currency code of the store
ids	SKU ID	String Array	No	All SKU IDs under the order

3.3.3 Response Parameters

- Response Example
- Normal Response

{
    "code": "200",
    "message": "",
    "data": [
        {
            "product_id": "7635574000000",
            "product_title": "17TRACK DEMO PRODUCT",
            "price": "120.00",
            "url": "https://17TRACK.com/products/a2568?variant=1001",
            "image": "https://cdn.shopify.com/s/foo.jpg",
            "currency": "USD",
            "currency_symbol": "$",
            "discount_type": "fixed_amount",
            "discount_value": "80",
            "discount_price": "96.00"
        }
    ]   
}

- Error Response

{
    "code": "500"
    "data": null
    "message": "request too fast"
}

- Response Description

Field	Name	Type	Required	Description	Example
product_id	Product ID	String	Yes	Unique Product ID in Shopify store	7635574000000
product_title	Product Title	String	Yes	Product title	17TRACK DEMO PRODUCT
price	SKU Price	String	Yes	Product price (Shopify price)	120
url	Product URL	String	Yes	Product URL	https://17TRACK.com/products/a2568?variant=1001
image	Main Image	String	Yes	Main image of the product variant	https://cdn.shopify.com/s/foo.jpg
currency	Currency Code	String	Yes	Currency	USD
currency_symbol	Currency Symbol	String	Yes	Currency symbol	$
discount_type	Discount Type	String	No	Shopify discount value_type	fixed_amount / percentage
discount_value	Discount Value	String	No	Discount value. Will be concatenated with discount_type (e.g., if discount type is percentage and value is 88, it becomes 88%)	fixed_amount: 80
discount_price	Discounted Price	String	No	Price after discount	96

3.3.4 Response Codes
- We will handle the response codes from the customer API accordingly.

Response Code	Description	Handling Method
200	Request successful	Normal display of request results
401	Unauthorized	Do not display
403	Access restricted	Do not display. Typically due to rate limiting
404	Not found	Do not display
500	Request failed	Do not display
Others	Request failed	Do not display

Updated on: 27/06/2024