Restful URL
After you have obtained the Access-Token for the application, you can construct RESTful requests to access the Shoplazza APIs.
The request URL must include the version number to correctly identify which version of the API you need, in the following format:
RESTful API URL： https://{your_store_slug}.myshoplaza.com/openapi/{ version }/{ endpoint }.json
For example, the following URL calls version 2020-01：
RESTful API URL： https://{your_store_slug}.myshoplaza.com/openapi/2020-01/products.json
Noted
All endpoints are only accessible via HTTPS and are located at https://{your_store_slug}.myshoplaza.com, which your_store_slug is the given store domain.
While using the "Try out" feature in this document, the your_store_slug is pre-filled with developer, which is a testing store provided by Shoplazza for you to easily navigated with.
The Example of Restful API Call
The following curl request retrieves information by using the Collection API and the GET /openapi/2022-01/collections endpoint. Replace {shop} with your store’s domain and {token} with the access token you generated in the Authentication section.
Request:
curl -X GET \
https://{shop}.stg.myshoplaza.com/openapi/2022-01/orders/10234136520598611512 \-H 'Content-Type: application/json' \-H 'Access-Token: {token}'
Response：
{
"order": {
"id": "10234136520598611512",
"note": null,
"number": "qwePCN74683zxc",
"financial_status": "partially_refunded",
"status": "finished",
"cancel_reason": null,
"payment_method": "cod",
"fulfillment_status": "finished",
"discount_code": "",
"discount_applications": "[]",
"customer_note": "",
"landing_site": "https://xz01.testinfo.org/products/1womens-open-toe-block-heel-sandals-44093040?st=",
"buyer_accepts_marketing": true,
"currency": "USD",
"total_price": "52.00",
"total_discount": "0.00",
"total_tax": "3.47",
"total_shipping": "12.00",
"sub_total": "40.00",
"code_discount_total": "0.00",
"line_item_discount_total": "0.00",
"tags": "",
"created_at": "2024-04-17T02:23:18Z",
"updated_at": "2024-04-17T02:30:00Z",
"canceled_at": null,
"customer_deleted_at": null,
"deleted_at": null,
"placed_at": "2024-04-17T02:23:30Z",
"total_refund_price": "40.00",
"total_refund_tax": "3.47",
"total_refund_discount": "0.00",
"refund_status": "general",
"total_tip_received": "0.00",
"browser_ip": "38.98.39.155",
"source": "https://xz01.testinfo.org/products/1womens-open-toe-block-heel-sandals-44093040?st=",
"last_landing_url": "https://xz01.testinfo.org/products/mario-and-luigi-5d-diy-diamond-painting-kits-full-round-drill-wall-decor-crafts-827624-8u80?st=",
"email_status": "waiting",
"recovery_status": "waiting",
"total_paid": "52.00",
"source_name": {
"data": "Others",
"created_at": "2023-11-20T08:35:37Z"
},
"last_referrer_show": {
"data": "Others",
"created_at": "2024-01-25T03:02:59Z"
},
"shipping_line": {
"name": "低于100件收费"
},
"customer": {
"id": "952fdb08-fcbf-489f-9c46-d63a4656796c",
"email": "[email protected]",
"first_name": "ss",
"last_name": "ss",
"phone": "+1 419 877 1231",
"created_at": "2022-03-31T08:04:29Z",
"updated_at": "2024-04-17T02:23:28Z",
"orders_count": 1382,
"total_spent": "11002335716.77"
},
"shipping_address": {
"first_name": "z",
"last_name": "z",
"address1": "Los Angeles World Airports 1 World Way, 11-F4, 11-F4",
"address2": "11-F4",
"phone": "",
"city": "Los Angeles",
"zip": "90045",
"province": "California",
"country": "United States",
"company": "",
"latitude": null,
"longitude": null,
"name": "z z",
"country_code": "US",
"province_code": "US-CA",
"phone_area_code": "",
"email": "[email protected]",
"area": "",
"extra_info": null
},
"billing_address": {
"first_name": "z",
"last_name": "z",
"address1": "Los Angeles World Airports 1 World Way, 11-F4, 11-F4",
"address2": "11-F4",
"city": "Los Angeles",
"zip": "90045",
"province": "California",
"country": "United States",
"company": "",
"latitude": null,
"longitude": null,
"name": "z z",
"country_code": "US",
"province_code": "US-CA",
"email": "*@shoplazza.com",
"area": "",
"phone": ""
},
"payment_line": {
"payment_channel": "cod",
"payment_method": "cod",
"transaction_no": null,
"merchant_id": "",
"merchant_email": ""
},
"payment_lines": [
{
"payment_channel": "cod",
"payment_method": "cod",
"transaction_no": null,
"merchant_id": "",
"merchant_email": "",
"paid_total": "52.00"
}
],
"line_items": [
{
"id": "934c0e31-8631-4be9-b941-e44aaf29aa04",
"product_id": "235e3142-a1e4-4ad8-a123-4d35923cf018",
"variant_id": "dccfbe01-d56f-4db7-bd0f-3fd6b251420d",
"variant_title": "XS-MOOD INDIGO",
"product_title": "Whole Hearted Long Sleeve UPF 50 Rashguard - Mood Indigo",
"product_handle": "whole-hearted-long-sleeve-upf-50-rashguard-8",
"quantity": 1,
"note": "",
"fulfillment_status": "finished",
"sku": "195718119233",
"weight_unit": "kg",
"vendor": "mysite",
"product_url": "/products/whole-hearted-long-sleeve-upf-50-rashguard-8",
"compare_at_price": "0.00",
"image": "//img.staticdj.com/e88de92f622f9aec9df7480258ec4c4e.jpeg",
"price": "40.00",
"total": "40.00",
"weight": "0.00",
"properties": [
{
"name": "SIZE",
"value": "XS"
},
{
"name": "COLOR",
"value": "MOOD INDIGO"
}
],
"custom_properties": null,
"refund_quantity": 1,
"refund_total": "40.00",
"base_price": "0.00",
"discount_applications": "[]"
}
],
"fulfillments": [
{
"id": "73f34dae-145a-4cfe-ad14-c01ac30be5a5",
"order_id": "10234136520598611512",
"status": "finished",
"tracking_company": "Yamato Japan",
"tracking_number": "3123123",
"tracking_company_code": "DJ-10004",
"created_at": "2024-04-17T02:24:43Z",
"updated_at": "2024-04-17T02:24:47Z",
"line_items": [
{
"id": "934c0e31-8631-4be9-b941-e44aaf29aa04",
"product_id": "235e3142-a1e4-4ad8-a123-4d35923cf018",
"variant_id": "dccfbe01-d56f-4db7-bd0f-3fd6b251420d",
"variant_title": "XS-MOOD INDIGO",
"product_title": "Whole Hearted Long Sleeve UPF 50 Rashguard - Mood Indigo",
"product_handle": "whole-hearted-long-sleeve-upf-50-rashguard-8",
"quantity": 1,
"note": "",
"fulfillment_status": "finished",
"sku": "195718119233",
"weight_unit": "kg",
"vendor": "mysite",
"product_url": "/products/whole-hearted-long-sleeve-upf-50-rashguard-8",
"compare_at_price": "0.00",
"image": "//img.staticdj.com/e88de92f622f9aec9df7480258ec4c4e.jpeg",
"price": "40.00",
"total": "40.00",
"weight": "0.00",
"properties": [
{
"name": "SIZE",
"value": "XS"
},
{
"name": "COLOR",
"value": "MOOD INDIGO"
}
],
"custom_properties": null,
"refund_quantity": 1,
"refund_total": "40.00",
"taxable": true,
"requires_shipping": true,
"shipping_quantity": 1
}
]
}
],
"gift_card_total": "0.00",
"shipping_tax_total": "0.00",
"product_tax_included": true,
"refer_info": "{\"$latest_referrer\":\"\",\"$latest_search_keyword\":\"未取到值_直接打开\",\"$latest_traffic_source_type\":\"直接流量\",\"address_check\":true,\"client_id\":\"1700464859962485\",\"country\":\"US\",\"customer_session\":\"14a27819-89cf-4903-9f6b-f36564e5396e\",\"domain\":\"xz01.testinfo.org\",\"fbc\":\"\",\"fbp\":\"\",\"inventory_deduction\":\"order_paid\",\"ip\":\"38.98.39.155\",\"session_id\":\"1712823353598296\",\"source\":\"buy_now\",\"user_agent\":\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36\"}",
"additional_total": "0.00",
"additional_prices": [],
"logistics_code": "",
"config": {
"page_type": "single",
"requires_shipping": true,
"checkout_business_type": 0,
"product_tax_included": true,
"checkout_template_type": 2,
"market_setting": {
"primary_market_lang": "en-US",
"market_lang": "en-US",
"market_id": "241006370139150330",
"market_currency": "USD",
"market_currency_symbol": {
"code": "USD",
"val": "$",
"left": "$",
"right": ""
},
"market_base_id": "",
"market_base_currency": "USD",
"market_base_currency_symbol": {
"code": "USD",
"val": "$",
"left": "$",
"right": ""
},
"primary_market_id": "241006370139150330",
"primary_market_currency": "USD",
"primary_market_currency_symbol": {
"code": "USD",
"val": "$",
"left": "$",
"right": ""
},
"market_price_setting": {
"local_currency_enabled": false,
"custom_rate_enabled": false,
"custom_rate": 0,
"rate": 1,
"back_rate": 1,
"actual_rate": 1,
"base_to_local": 0,
"local_to_base": 0,
"adjust": 0,
"price_round_enabled": false
},
"market_country": "US"
}
}
}
}
If your application calls a version that is no longer supported, it will return a 404 status upon the request call.
Cursor Pagination
"Cursor" pagination, also known as "keyset" pagination, is a method where you use a pointer (the cursor) to navigate through your results rather than the more traditional "offset/limit" method. The primary advantage of cursor-based pagination is its ability to efficiently paginate through large datasets without the performance pitfalls that can come with offset-based approaches.
In many APIs in Shoplazza, you'll receive a "cursor" value indicating how to retrieve the next set of results. The inclusion of a "pre_cursor" suggests the ability to navigate back to previous sets of results as well.
Here's a simple example:
Let's assume you have an API endpoint for fetching a list of users. The first time you hit the endpoint, the response might look something like this:
{"data": [
{"id": 1, "name": "Alice"},
{"id": 2, "name": "Bob"},...
],"cursor": "abc123","pre_cursor": null
}
To fetch the next set of results, you'd use the cursor value (in this case, "abc123").
If you later navigate to another page and receive a response like:
{"data": [
{"id": 101, "name": "Zack"},
{"id": 102, "name": "Zoe"},...
],"cursor": "def456","pre_cursor": "abc123"
}
You can use the cursor value ("abc123") to go back and fetch the previous set of results.
To use these cursors, you typically pass them as query parameters to your API request. For instance:
- To get the first set: GET /users
- To get the second set: GET /users?cursor=abc123
- To get the third set: GET /users?cursor=def456
- To get the previous set while you are on the second set: GET /users?pre_cursor=abc123 (The exact implementation may vary depending on the API.)
This is just a conceptual example; the specifics will vary based on the API's implementation. Always refer to the API documentation for exact usage details.
How to retrieve IDs
In Shoplazza Admin API, there are two easy ways you can retrieve item IDs
Through URL or web
Taking Product ID in this exmaple, you will simply just need to go to "All products" and find the product you want to retrieve the ID, and click into it, you will find the related product ID in besides "Basic information" also in the URL, for other terms such as "Orders", "Customers", you can find the ID either in the URL or in the webpages by navigating to the detail info page.
Through List API
{
"cursor": "MjAyMS0wNy0wOVQwMToxNzowNFojN2JiMWUwMTUtMDVhMi00Yzk0LWIxNDktMTE1MDEzYmEwODEz",
"pre_cursor": "MjAyMy0wNS0zMFQwNzozNzoyNVojYmIyZjJhMDgtYzdkNi00MTMzLTkzNmYtNWIzMDgxOGNhYmUz",
"products": [
{
"id": "c1d5b2a3-fab1-4e26-8582-75d3b2677042",
"title": "aasd",
"brief": "asd",
"description": "asd",
"published": false,
"requires_shipping": false,
"taxable": false,
"tags": "",
"vendor": "asd",
"vendor_url": "asd",
"inventory_quantity": 123,
"published_at": null,
"created_at": "2022-01-10T06:11:45Z",
"updated_at": "2022-01-10T06:11:45Z",
"note": "asd",
"seo_title": "asd",
"seo_description": "asd",
"seo_keywords": "asd",
"handle": "asd-bkpq",
"has_only_default_variant": false,
"inventory_tracking": false,
"inventory_policy": "continue",
"need_variant_image": false,
"spu": "asd",
"fake_sales": 123,
"display_fake_sales": false,
"image": {
"src": "//cdn.shoplazza.com/shirt.png",
"width": 100,
"height": 100,
"alt": "",
"path": "shirt.png"
},
"images": [
{
"id": "fe0ae4b6-cb7b-4d1c-a7f0-727750b73d16",
"product_id": "c1d5b2a3-fab1-4e26-8582-75d3b2677042",
"position": 1,
"src": "//cdn.shoplazza.com/shirt.png",
"width": 100,
"height": 100,
"alt": "",
"created_at": "2022-01-10T06:11:45Z",
"updated_at": "2022-01-10T06:11:45Z"
}
],
"options": [
{
"id": "b5109277-0daa-42f5-afa3-1bb609d13199",
"product_id": "c1d5b2a3-fab1-4e26-8582-75d3b2677042",
"position": 1,
"name": "qwe",
"values": [
"qwe"
]
}
],
"variants": [
{
"id": "8ecc0550-fb48-4860-9bb3-9b85e3c2b44a",
"product_id": "c1d5b2a3-fab1-4e26-8582-75d3b2677042",
"image_id": "",
"created_at": "2022-01-10T06:11:45Z",
"updated_at": "2022-01-10T06:11:45Z",
"title": "qwe",
"option1": "qwe",
"option2": "",
"option3": "",
"image": null,
"position": 1,
"compare_at_price": "132.00",
"price": "123.00",
"sku": "asd",
"barcode": "asd",
"note": "asd",
"inventory_quantity": 123,
"weight": "123",
"weight_unit": "kg",
"cost_price": "120.00"
}
]
}
]
}
Retrieving IDs from various list API is always an Option, in this case, we use Product List API (https://www.shoplazza.dev/reference/product_list) to retrieve the product ID. This method also works for "Customers", "Orders" and so on.