Overview​

The REST Admin API is used to provide access to store data for your app.

Before accessing the REST Admin API, your app must obtain Store Authorization, and obtain an accessToken.

Store authorization​

Store authorization is divided into Private App Authorization, Custom App Authorization, and Public App Authorization.

Custom and Public apps adopt OAuth2 authorization. After successful authorization, you can obtain an accessToken that includes any specified authorized scopes.

Custom and Public apps​

You can obtain an accessToken for Custom and Public apps through OAuth2 authorization which have an expiration time of 10 hours.

• You need to check if the accessToken is about to expire, and before it expires, you need to call the Refresh Token interface to refresh the accessToken.
• After the accessToken is refreshed, the original accessToken will not be invalidated for 5 minutes.
• When your app wants to revoke the store authorization, you need to call the Cancel Authorization interface to revoke the authorization.
• Once the authorization is revoked, the original accessToken will immediately become invalid.

Private apps​

To obtain an accessToken for a Private app, head to the store admin.

It has an expiration time of 3 years.

• Before it expires, you will receive an accessToken expiration email reminder.
• You will then need to refresh the accessToken from within the store admin.
• After the accessToken is refreshed, the original accessToken will not be invalidated for 30 minutes.
• When your app wants to revoke the store authorization, you need to go to the store admin and delete the app for the original accessToken to become invalid.

Version selection​

The Admin REST API maintains 8 versions by sliding time frames.

You can refer to the Version Description aand select the appropriate version for calling in the upper right corner of the page.

Different versions of the ADMIN REST API request URLs will have a version number.

For example, the request URL for calling Batch Query Products in version v20230901 is: https://goodgoods.myshopline.com/admin/openapi/v20230901/products/products.json, where v20230901 is the version number.

API invocations​

Once you have successfully obtained an accessToken after authorization and selected the desired API version, you can invoke the Admin REST API in your program.

For example, to call the Batch Query Products in version 20230901.

Request​

curl --location --request GET 'https://goodgoods.myshopline.com/admin/openapi/v20230901/products/products.json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhcHBLZXkiOiI2MWUxYWQ2YWJkYmFhYmYzZTdkODRmZjcxYzQzODQwMWY3NjA4MzhjIiwic2VsbGVySWQiOiIyMDAwMjA4MDAwIiwic3RvcmVJZCI6IjE2Mjg1MDQwODE0MDEiLCJ2ZXJzaW9uIjoiVjIiLCJkb21haW4iOiJodHRwczovL3NsLW9wZW4tc2cubXlzaG9wbGluZS5jb20iLCJ0aW1lc3RhbXAiOjE2ODQyMjM3OTExNzMsImlzcyI6Inlzb3VsIiwiZXhwIjoxNzc4ODMxNzkxfQ.XDxdUIWu8yrNtAhINW9GAYEneJSOdwUqyFgNel0Q-'

The accessToken is: eyJhbGciOiJIUzUxMiJ9.eyJhcHBLZXkiOiI2MWUxYWQ2YWJkYmFhYmYzZTdkODRmZjcxYzQzODQwMWY3NjA4MzhjIiwic2VsbGVySWQiOiIyMDAwMjA4MDAwIiwic3RvcmVJZCI6IjE2Mjg1MDQwODE0MDEiLCJ2ZXJzaW9uIjoiVjIiLCJkb21haW4iOiJodHRwczovL3NsLW9wZW4tc2cubXlzaG9wbGluZS5jb20iLCJ0aW1lc3RhbXAiOjE2ODQyMjM3OTExNzMsImlzcyI6Inlzb3VsIiwiZXhwIjoxNzc4ODMxNzkxfQ.XDxdUIWu8yrNtAhINW9GAYEneJSOdwUqyFgNel0Q-

Response(Request succeeded)​

{
  "products": [
    {
      "image": {
        "src": "https://d2n979dmt31clo.cloudfront.net/image/store/3300003249/1609823068438/9d058cfacb8e42299460086d9",
        "alt": "alt",
        "id": "5785060242207917075"
      },
      "body_html": "product description",
      "images": [
        {
          "src": "https://d2n979dmt31clo.cloudfront.net/image/store/3300003249/1609823068438/9d058cfacb8e42299460086d9",
          "alt": "alt",
          "id": "5785060242207917075"
        }
      ],
      "created_at": "",
      "template_path": "templates/products/detail.json",
      "handle": "product-handle",
      "variants": [
        {
          "inventory_quantity": "99",
          "image": {
            "src": "https://d2n979dmt31clo.cloudfront.net/image/store/3300003249/1609823068438/9d058cfacb8e42299460086d9",
            "alt": "alt",
            "id": "5785060242207917075"
          },
          "required_shipping": true,
          "compare_at_price": "99",
          "taxable": true,
          "option5": "",
          "weight": "0.2",
          "title": "Red/L",
          "inventory_policy": "deny",
          "weight_unit": "kg",
          "inventory_item_id": "5785060242375689228",
          "price": "90",
          "product_id": "16057850264845250791280282",
          "option3": "",
          "option4": "",
          "inventory_tracker": true,
          "option1": "Red",
          "id": "18057850264851626133510282",
          "option2": "",
          "position": "1",
          "sku": "S000000001",
          "barcode": "T0000001"
        }
      ],
      "title": "product title",
      "tags": "IPHONE, APPLE",
      "published_scope": "web",
      "product_type": "NORMAL",
      "updated_at": "",
      "vendor": "Apple",
      "subtitle": "Subtitle",
      "options": [
        {
          "product_id": "16057850264845250791280282",
          "values": [
            null
          ],
          "values_images": "{ \"Red\" : \"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3\" }",
          "name": "Color",
          "id": "16158068291703878544960282"
        }
      ],
      "id": "16057850264845250791280282",
      "published_at": "",
      "product_behavior": "RISK,HIDDEN",
      "product_category": "Electronic products",
      "status": "active"
    }
  ]
}

Response(Request failed)​

HTTP/1.1 401 Unauthorized
{
  "errors": "ACCESS_TOKEN is expired!"
}

When a response fails, the error code will be returned through the HTTP status.

You can refer to HTTP Status Code to determine whether you need to retry the request based on different HTTP status codes.

Note:

• When you are making a paginated query, you can refer to the Pagination Mechanism.
• The time fields in both the request and response follow the ISO-8601 standard. In the response, you need to convert them to your business’s corresponding time zone.
• You can also use the "iana_timezone" field returned by the Shop Information Query API for the conversion.

Rate Limiting​

We impose limitations on your requests in the following scenarios:

• The shop is frozen, closed, or the plan has expired.
• Your request frequency exceeds our rate control limits.