Sign in
< Back to CIC Studio Top

API-related Information - Shopify

This article contains the following information related to APIs.

  • API Version
  • Handling Pagination 
  • Handling Throttling
  • Custom Entities 
  • Handling Errors

API Version

The Shopify API version is 2024-10. 

For more information on Shopify API versioning: https://shopify.dev/concepts/about-apis/versioning

Handling Pagination 

When you send a request to Shopify, the response body returns the first page of results, and the response header returns links to the next page and the previous page of results (if applicable). You can use the links in the response header to iterate through the pages of results.

Link headers use the following syntax:

"<https://{shop}.myshopify.com/admin/api/{version}/products.json?page_info={page_info}&limit={limit}>; rel={next}, <https://{shop}.myshopify.com/admin/api/{version}/products.json?page_info={page_info}&limit={limit}>; rel={previous}"

The link header includes a rel parameter, where relation-types describe the relation of the linked page to the current page of results. The value can either be previous or next.

The URL in the link header can include up to two parameters:

  • page_info: A unique ID used to access a certain page of results. The page_info parameter can't be modified and must be used exactly as it appears in the link header URL.
  • limit: The maximum number of results to show on the page.

For more information on Shopify pagination requests: https://shopify.dev/tutorials/make-paginated-requests-to-rest-admin-api

Step: In the Integration Project implemented, after the step in which the Business Process from the Connector Project is called, add a new step called Connector Response Header Parser that will retrieve header information.

mceclip0.png

Sample Response Headers: 

{"X-Sorting-Hat-ShopId": [
"27577286735"
],
"X-ShardId": [
"78"
],
"X-Stats-ApiClientId": [
"3187439"
],
"Server": [
"cloudflare"
],
"X-Shopify-Stage": [
"production"
],
"X-Request-ID": [
"b8589d39-2325-4fa0-8521-5e41fc21cca9"
],
"Server-Timing": [
"cfRequestDuration;dur=421.999931"
],
"X-ShopId": [
"27577286735"
],
"X-Stats-ApiPermissionId": [
"196426989647"
],
"HTTP_X_SHOPIFY_SHOP_API_CALL_LIMIT": [
"1/40"
],
"X-Permitted-Cross-Domain-Policies": [
"none"
],
"X-Stats-UserId": [
""
],
"X-Shopify-Shop-Api-Call-Limit": [
"1/40"
],
"Referrer-Policy": [
"origin-when-cross-origin"
],
"X-Frame-Options": [
"DENY"
],
"Strict-Transport-Security": [
"max-age=7889238"
],
"X-Shopify-API-Version": [
"2023-01"
],
"X-XSS-Protection": [
"1; mode=block; report=/xss-report?source%5Baction%5D=index&source%5Bapp%5D=Shopify&source%5Bcontroller%5D=admin%2Forders&source%5Bsection%5D=admin_api&source%5Buuid%5D=b8589d39-2325-4fa0-8521-5e41fc21cca9"
],
"X-Dc": [
"gcp-asia-southeast1,gcp-us-central1,gcp-us-central1"
],
"Content-Type": [
"application/json; charset=utf-8"
],
"Transfer-Encoding": [
"chunked"
],
"CF-RAY": [
"7a740b925c641d9d-BLR"
],
"X-Shopify-API-Deprecated-Reason": [
"https://shopify.dev/changelog/property-deprecations-in-the-admin-api-order-and-lineitem-resource"
],
"X-Content-Type-Options": [
"nosniff"
],
"Connection": [
"keep-alive"
],
"X-Download-Options": [
"noopen"
],
"Date": [
"Mon, 13 Mar 2023 11:47:58 GMT"
],
"CF-Cache-Status": [
"DYNAMIC"
],
"NEL": [
"{\"success_fraction\":0.01,\"report_to\":\"cf-nel\",\"max_age\":604800}"
],
"X-Sorting-Hat-PodId": [
"78"
],
"Vary": [
"Accept-Encoding"
],
"alt-svc": [
"h3=\":443\"; ma=86400, h3-29=\":443\"; ma=86400"
],
"Link": [
"<https://ambikatest.myshopify.com/admin/api/2023-01/orders.json?limit=3&page_info=eyJzdGF0dXMiOiJvcGVuIiwibGFzdF9pZCI6NDkxMzk4MjIxMDEyNywibGFzdF92YWx1ZSI6IjIwMjMtMDMtMTMgMTE6Mzg6MjQuNzQ4NjExIiwiZGlyZWN0aW9uIjoibmV4dCJ9>; rel=\"next\""
]
}

Once you retrieve that page_info value:

example: 
eyJzdGF0dXMiOiJvcGVuIiwibGFzdF9pZCI6NDkxMzk4MjIxMDEyNywibGFzdF92YWx1ZSI6IjIwMjMtMDMtMTMgMTE6Mzg6MjQuNzQ4NjExIiwiZGlyZWN0aW9uIjoibmV4dCJ9

...as part of the response from the Connector Response Header Parser step in your Business Process, you can use this value to pass as a query parameter to iterate through the pages of results.

mceclip1.png

Handling Throttling

REST Admin API rate limits:

Calls to the REST Admin API are governed by request-based limits, which means you should consider the total number of API calls your app makes. In addition, there are resource-based rate limits and throttles.

Limits are calculated using the leaky bucket algorithm. All requests that are made after rate limits have been exceeded are throttled and an HTTP 429 Too Many Requests error is returned. Requests succeed again after enough requests have emptied out of the bucket. You can see the current state of the throttle for a store by using the rate limits header.

The bucket size and leak rate properties determine the API’s burst behavior and request rate. Requests are measured per-app, per-store.

The default settings are as follows:

  • Bucket size: 40 requests/app/store
  • Leak rate: 2/second

If the bucket size is exceeded, then an HTTP 429 Too Many Requests error is returned. The bucket empties at a leak rate of two requests per second. To avoid being throttled, you can build your app to average two requests per second. The throttle is a pass or fail operation. If there is available capacity in your bucket, then the request is executed without queueing or processing delays. Otherwise, the request is throttled.

There is an additional rate limit for GET requests. When the value of the page parameter results in an offset of over 100,000 of the requested resource, a 429 Too Many Requests error is returned. For example, a request to GET /admin/collects.json?limit=250&page=401 would generate an offset of 100,250 (250 x 401 = 100,250) and return a 429 response.

For more information on Shopify rate limits, please see: https://shopify.dev/concepts/about-apis/rate-limits#rest-admin-api-rate-limits

How to retrieve Throttling information from Clarify Connector

In the Integration Projected implemented, after the step in which the Business process from the Connector Project is called, add a new step called Connector Response Header Parser that will retrieve header information such as X-Shopify-Shop-Api-Call-Limit and Retry-After

mceclip2.png

Sample Response headers:

{
"X-Sorting-Hat-ShopId": [
"27577286735"
],
"X-ShardId": [
"78"
],
"X-Stats-ApiClientId": [
"3187439"
],
"Server": [
"cloudflare"
],
"X-Shopify-Stage": [
"production"
],
"X-Request-ID": [
"b8589d39-2325-4fa0-8521-5e41fc21cca9"
],
"Server-Timing": [
"cfRequestDuration;dur=421.999931"
],
"X-ShopId": [
"27577286735"
],
"X-Stats-ApiPermissionId": [
"196426989647"
],
"HTTP_X_SHOPIFY_SHOP_API_CALL_LIMIT": [
"1/40"
],
"X-Permitted-Cross-Domain-Policies": [
"none"
],
"X-Stats-UserId": [
""
],
"X-Shopify-Shop-Api-Call-Limit": [
"1/40"
],
"Referrer-Policy": [
"origin-when-cross-origin"
],
"X-Frame-Options": [
"DENY"
],
"Strict-Transport-Security": [
"max-age=7889238"
],
"X-Shopify-API-Version": [
"2023-01"
],
"X-XSS-Protection": [
"1; mode=block; report=/xss-report?source%5Baction%5D=index&source%5Bapp%5D=Shopify&source%5Bcontroller%5D=admin%2Forders&source%5Bsection%5D=admin_api&source%5Buuid%5D=b8589d39-2325-4fa0-8521-5e41fc21cca9"
],
"X-Dc": [
"gcp-asia-southeast1,gcp-us-central1,gcp-us-central1"
],
"Content-Type": [
"application/json; charset=utf-8"
],
"Transfer-Encoding": [
"chunked"
],
"CF-RAY": [
"7a740b925c641d9d-BLR"
],
"X-Shopify-API-Deprecated-Reason": [
"https://shopify.dev/changelog/property-deprecations-in-the-admin-api-order-and-lineitem-resource"
],
"X-Content-Type-Options": [
"nosniff"
],
"Connection": [
"keep-alive"
],
"X-Download-Options": [
"noopen"
],
"Date": [
"Mon, 13 Mar 2023 11:47:58 GMT"
],
"CF-Cache-Status": [
"DYNAMIC"
],
"NEL": [
"{\"success_fraction\":0.01,\"report_to\":\"cf-nel\",\"max_age\":604800}"
],
"X-Sorting-Hat-PodId": [
"78"
],
"Vary": [
"Accept-Encoding"
],
"alt-svc": [
"h3=\":443\"; ma=86400, h3-29=\":443\"; ma=86400"
],
"Link": [
"<https://ambikatest.myshopify.com/admin/api/2023-01/orders.json?limit=3&page_info=eyJzdGF0dXMiOiJvcGVuIiwibGFzdF9pZCI6NDkxMzk4MjIxMDEyNywibGFzdF92YWx1ZSI6IjIwMjMtMDMtMTMgMTE6Mzg6MjQuNzQ4NjExIiwiZGlyZWN0aW9uIjoibmV4dCJ9>; rel=\"next\""
]
}

Custom Entities 

To work with custom fields, install a third-party app (plugin) via the Shopify App store.

  1. Go to the Shopify Admin portal.
  2. Go to Apps.
  3. Click on Visit the Shopify App Store.
  4. Search for the app Metafields Guru and add in it your Shopify account.
  5. Now use the Metafields APIs in the Shopify Connector project.

    For creating a new metafield for a Shop resource, use CreateMetafields.bps.

    mceclip5.png

    For more information on the Shopify Metafield API, refer to: https://shopify.dev/docs/api/admin-rest#client_libraries

  6. Go to the Products page and navigate into a particular product.
  7. Go to More Actions -> Edit Metafields.

    You will be able to see the added metafield in step 5 on this screen.

  8. Navigate to Online Store -> Themes.
  9. Against the current theme section, select Edit Code.

    mceclip8.png

  10. Search for the product.liquid file
  11. Add the below code at the bottom and save the changes. 
    {% assign global = product.metafields.{namespace} %}

    {% assign key = '{key}' %}

    <p>Washing instructions: {{ {namespace}.{key} }}.</p>
  12. Once done, you can click on the Preview button to check the metafields on the store UI.

Handling Errors

When the Shopify Connector Business Process's API call is successful (returning status code between 200 & 300), the BP task will pass and return response payload.  (Note: the task is marked as completed in the Admin Console perspective/Auditor View). 

Or

When the Shopify Connector Business Process's API call fails (response status code not between 200 & 300), then the BP task fails without returning any response payload. (Note: the task is marked as failed; the error payload is returned from Shopify, and stack traces are logged in the Admin Console perspective/Auditor View).

Or

When the Shopify Connector Business Process's API call execution fails (which can be an internal error such as payload parse issue), then the BP task fails without returning any response payload. (Note: the task is marked as failed; the error payload is returned from Shopify, and stack traces are logged in the Admin Console perspective/Auditor View).

Below are some error codes for Shopify REST Admin APIs :

Error Code Description
400 Bad Request The request was not understood by the server, generally due to bad syntax or because the Content-Type header was not correctly set to application/json.

This status is also returned when the request provides an invalid code parameter during the OAuth token exchange process.
401 Unauthorized The necessary authentication credentials are not present in the request or are incorrect.
402 Payment Required The requested shop is currently frozen. The shop owner needs to log in to the shop's admin and pay the outstanding balance to unfreeze the shop.
403 Forbidden The server is refusing to respond to the request. This is generally because you have not requested the appropriate scope for this action.
404 Not Found The requested resource was not found but could be available again in the future.
406 Not Acceptable The requested resource is only capable of generating content not acceptable according to the Accept headers sent in the request.
422 Unprocessable Entity The request was well-formed but contains semantical errors. The response body will provide more details in the errors or error parameters.
423 Locked The requested shop is currently locked. Shops are locked if they repeatedly exceed their API request limit, or if there is an issue with the account, such as a detected compromise or fraud risk. Contact support if your shop is locked.
429 Too Many Requests The request was not accepted because the application has exceeded the rate limit. See the API Call Limit documentation for a breakdown of Shopify's rate-limiting mechanism.
500 Internal Server Error An internal error occurred in Shopify. Please post to the API & Technology forum so that Shopify staff can investigate.
501 Not Implemented The requested endpoint is not available on that particular shop, for example, requesting access to a Plus-specific API on a non-Plus shop. This response may also indicate that this endpoint is reserved for future use.
503 Service Unavailable The server is currently unavailable. Check the status page for reported service outages.
504 Gateway Timeout The request could not complete in time. Try breaking it down into multiple smaller requests.

For more information on Shopify API response codes, please visit: https://shopify.dev/concepts/about-apis/response-codes

Related articles

Comments

0 comments

Please sign in to leave a comment.