API Usage

API Public Info

Public Request Parameters

Parameter Name	Type	Required	Parameter Location	Parameter Value	Description
Access-Token	`String`	Yes	Header	Bx-_5aV eXNwl-4AB98s5xLV yg0fNzGf MuTpqtlBA	Used to authenticate API requests. Obtain an access token from the Access Token Guide. Pass it in the `Authorization` header for every request.
Content-Type	`String`	Yes	Header	`application` `/json`	Indicates the media type of the request body. It tells the server how to parse the request and the client how to interpret the response. For more details, visit Content-Type.

Public Response Feilds

Parameter Name	Type	Mandatory	Parameter Location	Example Value	Description
error	String	No	Response Body	`{ "error": "store is not active" }`	Indicates an error encountered during the process. This field typically appears when the Access Token is missing or invalid. Example: `{ "error": "store is not active" }`.
errors	Array	No	Response Body	`{ "errors"["No Context"] }`	A list of errors that occurred during the request processing. Example: `{ "errors": [ "No Context" ] }`.
Request-Id	String	Yes	Header	Bx-_5aV eXNwl-4AB98s5xLV yg0fNzGf MuTpqtlBA	A unique identifier for each request. It helps in identifying and debugging specific requests.

Restful URL

Once you have obtained the Access Token for your application, you can construct RESTful API requests to access Shoplazza’s APIs. The request URL must include the version number to correctly identify which API version you need, using the following format:

RESTful API URL： https://{shopdomain}.myshoplaza.com/openapi/{ version }/{ endpoint }.json

For example, the following URL calls version 2020-01：

RESTful API URL： https://{shopdomain}.myshoplaza.com/openapi/2020-01/products.json

Noted

All endpoints are only accessible via HTTPS.

The base domain is formatted as https://{shopdomain}.myshoplazza.com, where {shopdomain} represents your store’s unique domain.

When using the “Try out” feature in this document, {shopdomain} is pre-filled with a testing store provided by Shoplazza for ease of navigation.

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 {shopdomain} with your store’s domain and {token} with the access token you generated in the Authentication section.
Request:

curl -X GET \
  https://{shopdomain}.stg.myshoplaza.com/openapi/2022-01/orders/10234136520598611512 \-H 'Content-Type: application/json' \-H 'Access-Token: {token}'

Response Example：

{
    "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:

Assume you are fetching a list of users through an API endpoint. The first API call might return a response 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:

Fetch the first set of results: GET /users
Fetch the second set of results: GET /users?cursor=abc123
Fetch the third set of results: GET /users?cursor=def456
Fetch the previous set of results 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 items' IDs

Through URL or web

To retrieve a Product ID, navigate to the “All Products” section, locate the product you need, and click into its details. You will find the Product ID in two places:

Next to the “Basic Information” section.
Within the product’s URL in your browser’s address bar.

For other entities like Orders or Customers, the ID can similarly be found.

In the URL when you view the entity’s details.
On the specific entity’s detailed information page within the interface.

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 to retrieve the product ID. This method also works for "Customers", "Orders" and so on.