{"id":648,"date":"2019-04-04T10:24:45","date_gmt":"2019-04-04T08:24:45","guid":{"rendered":"https:\/\/developers.shoptet.cz\/?page_id=648"},"modified":"2025-09-22T13:35:19","modified_gmt":"2025-09-22T11:35:19","slug":"correct-api-usage","status":"publish","type":"page","link":"https:\/\/developers.shoptet.com\/correct-api-usage\/","title":{"rendered":"Correct API usage"},"content":{"rendered":"<h2 id=\"when-preparing-an-add-on\">When preparing an add-on<\/h2>\n<p>It is advisable to think in advance about what data you actually need and at what intervals. Many data sets can be obtained efficiently using snapshots without the need to download everything repeatedly, which would unnecessarily burden both your and our hardware resources. At the same time, it is important to distinguish which data needs to be monitored regularly and which can be checked less frequently, for example, using webhooks.<\/p>\n<h2 id=\"follow-updates-and-changes-in-the-documentation-api-release-news-\">Follow updates and changes in the documentation (API release news)<\/h2>\n<p><strong>The API may change<\/strong>, and it is important to regularly follow updates and news in the documentation (<a href=\"https:\/\/developers.shoptet.com\/category\/api\">API release news<\/a>). We announce all updates and any BC (backward compatibility) changes well in advance, but it is crucial to keep track of these updates to avoid potential issues caused by lack of information.<\/p>\n<h2 id=\"use-webhooks\">General considerations<\/h2>\n<p>Please keep in mind that the API is designed as a &#8220;gateway&#8221; into the Administration for our partners. It is not intended nor designed for public frontend use. There are several limiting factors such as response time, rate-limiter and so on. If you want to use data provided by the API in any kind of resource-intensive setting, caching or other optimizations should be considered and\/or consulted.<\/p>\n<h2 id=\"use-webhooks\">Use webhooks<\/h2>\n<p>Webhooks regularly send information and, in case of failure, attempt to deliver the notification several more times. However, if some errors occur and notifications do not reach you, it is always a good idea to check whether there are issues with data retrieval. You should have a backup solution in the form of change downloads. We recommend regular integration checks, such as once a day, to verify that everything is working correctly.<\/p>\n<p><strong>Also, don\u2019t forget to check the content of received data \u2013 for example, if a webhook reports an order change, but the actual status of the order hasn\u2019t changed, it could be a duplicate notification that does not need processing. Implement control mechanisms to prevent repeated processing of the same data and ensure that this data is consistently verified.<\/strong><\/p>\n<h2 id=\"work-with-list-endpoints-snapshots-\">Work with list endpoints (snapshots)<\/h2>\n<p>In addition to order details, product details, etc., endpoints also provide lists with basic information. Therefore, it is not always necessary to look up everything in order<br \/>\ndetails, for example \u2013 you can obtain data directly from the order list (<a href=\"https:\/\/api.docs.shoptet.com\/shoptet-api\/openapi\/orders\/getlistofallorders\">List of all orders<\/a>), saving time and reducing API load.<\/p>\n<p>Snapshot endpoints are optimized for batch queries, minimizing the need for individual detail requests. Their processing is <a href=\"https:\/\/developers.shoptet.com\/asynchronous-requests\/\">asynchronous<\/a> \u2013 upon calling, you receive a <code>jobId<\/code> in the request, and after successful processing, you need to call the system endpoint for <a href=\"https:\/\/api.docs.shoptet.com\/shoptet-api\/openapi\/job-endpoints\/getjobdetail\">job details<\/a>.<\/p>\n<p><strong>To trigger asynchronous requests, you must have the <code>job:finished<\/code> webhook registered.<\/strong> If it is not registered, you will receive an error response with status code 403, and the task will not be added to the queue.<\/p>\n<p>The <code>job:finished<\/code> webhook is also emitted when a task fails, so it is necessary to check the <a href=\"https:\/\/api.docs.shoptet.com\/shoptet-api\/openapi\/section\/basic-principles\/server-response-format#tag\/job-endpoints\/getjobdetail\">job details<\/a> to obtain the task result. If an error occurs during an asynchronous request, the task is automatically marked as failed 3 hours after its creation. In such cases, the <code>job:finished<\/code> webhook is not emitted.<\/p>\n<p><strong>Currently, the following snapshots are available for these entities:<\/strong><\/p>\n<ul>\n<li><a href=\"https:\/\/api.docs.shoptet.com\/shoptet-api\/openapi\/products\/getlistofallproducts\">List of all products<\/a><\/li>\n<li><a href=\"https:\/\/api.docs.shoptet.com\/shoptet-api\/openapi\/price-lists\/getlistofallpricelistdetails\">List of all price list details<\/a><\/li>\n<li><a href=\"https:\/\/api.docs.shoptet.com\/shoptet-api\/openapi\/orders\/getlistofallorders\">List of all orders<\/a><\/li>\n<li><a href=\"https:\/\/api.docs.shoptet.com\/shoptet-api\/openapi\/invoices\/getlistofallinvoices\">List of all invoices<\/a><\/li>\n<li><a href=\"https:\/\/api.docs.shoptet.com\/shoptet-api\/openapi\/proforma-invoices\/getlistofallproformainvoices\">List of all proforma invoices<\/a><\/li>\n<li><a href=\"https:\/\/api.docs.shoptet.com\/shoptet-api\/openapi\/credit-notes\/getlistofallcreditnotes\">List of all credit notes<\/a><\/li>\n<li><a href=\"https:\/\/api.docs.shoptet.com\/shoptet-api\/openapi\/delivery-notes\/getlistofalldeliverynotes\">List of all delivery notes<\/a><\/li>\n<li><a href=\"https:\/\/api.docs.shoptet.com\/shoptet-api\/openapi\/proof-payments\/getlistofallproofpayments\">List of all proof payments<\/a><\/li>\n<li><a href=\"https:\/\/api.docs.shoptet.com\/shoptet-api\/openapi\/customers\/getlistofallcustomers\">List of all customers<\/a><\/li>\n<li><a href=\"https:\/\/api.docs.shoptet.com\/shoptet-api\/openapi\/discount-coupons\/getlistofalldiscountcoupons\">List of all discount coupons<\/a><\/li>\n<li><a href=\"https:\/\/api.docs.shoptet.com\/shoptet-api\/openapi\/articles\/getlistallarticles\">List of all articles<\/a><\/li>\n<\/ul>\n<h2 id=\"use-the-include-parameter-and-filters\">Use the include parameter and filters<\/h2>\n<p>Some endpoints contain so-called <strong>include parameters<\/strong> (e.g., <a href=\"https:\/\/api.docs.shoptet.com\/shoptet-api\/openapi\/products\/createproduct\">Product insertion<\/a>) in the URL, which extend the response of individual calls and enrich them with additional necessary information. This is especially useful when creating data, as it eliminates the need to call the details of, for example, a newly created product\u2014the data is available immediately within a single call.<\/p>\n<p>Some endpoints also support filtering for easier item search, allowing you to avoid requesting an entire dataset when you only need a specific portion. Don\u2019t be afraid to use filters!<\/p>\n<h2 id=\"update-data-in-batches\">Update data in batches<\/h2>\n<p>Several of our <code>POST<\/code> and <code>PATCH<\/code> endpoints allow processing multiple entities within a single request \u2013 therefore, try to send the maximum number of changes at once. Sending a single request with 20 changes is faster than 20 separate requests with one change each. This approach not only speeds up your update process but also reduces API load and minimizes bucket drops in the rate limiter.<\/p>\n<p>Currently available batch updates:<\/p>\n<ul>\n<li><a href=\"https:\/\/api.docs.shoptet.com\/shoptet-api\/openapi\/products\/productbatchupdate\">Product update BATCH<\/a><\/li>\n<li><a href=\"https:\/\/api.docs.shoptet.com\/shoptet-api\/openapi\/products\/updateproductcategorybatch\">Product category BATCH update<\/a><\/li>\n<li><a href=\"https:\/\/api.docs.shoptet.com\/shoptet-api\/openapi\/brands\/createbrandbatch\">BATCH creation of brands<\/a><\/li>\n<\/ul>\n<h2 id=\"use-change-endpoints\">Use change endpoints<\/h2>\n<p>For many endpoints, there are also <a href=\"https:\/\/api.docs.shoptet.com\/shoptet-api\/openapi\/section\/last-changes\">change endpoints<\/a>, meaning you don\u2019t need to download orders every five minutes. Retrieve them at longer intervals and, in the meantime, use endpoints that handle changes (changes endpoints). This can also be combined with webhooks\u2014rather than making repeated requests, simply track changes and download only new data.<\/p>\n<p><strong>However, it is crucial to approach received data with skepticism\u2014not all changes may be relevant. Verify that you are not dealing with duplicate data you have already retrieved in the past, and ensure that certain fields do not contain unexpected values.<\/strong><\/p>\n<h2 id=\"use-the-access-token-correctly\">Use the access token correctly<\/h2>\n<p>When installing an add-on, it is enough to confirm that you have stored the token and request only the necessary data once it is correctly installed and everything is functioning properly. If you perform multiple steps at once and an installation error occurs, you may reach the token usage limit. In that case, you must wait 30 minutes before you can attempt the installation again.<\/p>\n<p>If you are unsure about the installation, let us know\u2014we can review the entire installation process and assist you in running it correctly.<\/p>\n<h2 id=\"process-requests-in-a-queue\">Process requests in a queue<\/h2>\n<p>When retrieving various types of data via requests, consider the method of querying and subsequent processing. It benefits both parties if data is processed in a queue rather than running everything at once.<\/p>\n<p><strong>For example, instead of making parallel calls to multiple endpoints, use batch processing and distribute requests efficiently.<\/strong><\/p>\n<p>Monitor status codes<br \/>\nErrors can sometimes occur in the API, which are reported via status codes.<\/p>\n<p>Codes <code>5xx<\/code> indicate an issue or unexpected behavior on our side.<br \/>\nCodes <code>4xx<\/code> are caused by incorrect request calls\u2014this includes exceeding API limits, which returns the error <code>429 Too Many Requests<\/code>.<br \/>\nIt is always a good idea to check for these status codes and, if they appear, pay close attention to them.<\/p>\n<p><strong>If you encounter recurring errors, analyze them and adjust API calls based on the recommendations in the documentation.<\/strong><\/p>\n<h2 id=\"use-caching\">Use caching<\/h2>\n<p>Proper API usage relies on working with downloaded data. Even if you limit full data downloads and rely on changes and webhooks, some data does not need to be retrieved multiple times a day. These requests can have longer intervals.<\/p>\n<p><strong>For example, category lists and basic product parameters change infrequently, so it is advisable to cache them for an extended period.<\/strong><\/p>\n<h2 id=\"rate-limiter\">Rate Limiter<\/h2>\n<p>To protect the server from overload (e.g., DDoS attacks), rate limiting is implemented. This means restricting the maximum number of simultaneous active connections:<\/p>\n<ul>\n<li>A maximum of 50 from a single IP address.<\/li>\n<li>A maximum of 3 connections per token.<\/li>\n<\/ul>\n<p>If the limit is exceeded, an HTTP <code>429<\/code> error is returned.<\/p>\n<p>To monitor the efficiency of your API calls, the <a href=\"https:\/\/api.docs.shoptet.com\/shoptet-api\/openapi\/section\/basic-principles\/leaky-bucket\">leaky bucket<\/a> algorithm is used. We notify you of reaching limits using the headers <code>X-RateLimit-Bucket-Filling<\/code> (in each response) and <code>Retry-After<\/code> (only when the bucket is full).<\/p>\n<p><strong>We recommend monitoring these headers and optimizing query intervals based on their fill levels.<\/strong><\/p>\n<h2 id=\"log-log-log-\">Log, log, log!<\/h2>\n<p>As Shoptet API evolves and new features and modifications are released, there may be situations where an endpoint behaves slightly differently than expected.<br \/>\nIn such cases, both you and we will save time if you send us detailed logs.<\/p>\n<p><strong>In general, logging more information is better than logging less. We recommend logging both <code>request<\/code> and <code>response<\/code>.<\/strong> The more data you provide us, the faster we can detect potential inconsistencies and assist you.<\/p>\n<h2 id=\"don-t-hesitate-to-request-new-features\">Don\u2019t hesitate to request new features<\/h2>\n<p>If you need to retrieve specific information from the API and a relevant endpoint or value is missing, let us know. If certain endpoints are entirely absent, overusing other available endpoints or using them for unintended purposes is not a solution\u2014it may lead to unnecessary API limit issues.<\/p>\n<p>Don\u2019t hesitate to reach out!<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Tips on how to carefully access and use Shoptet API resources.<\/p>\n","protected":false},"author":26,"featured_media":0,"parent":230,"menu_order":11,"comment_status":"closed","ping_status":"closed","template":"","meta":{"footnotes":""},"class_list":["post-648","page","type-page","status-publish","hentry"],"yoast_head":"<!-- This site is optimized with the Yoast SEO plugin v24.7 - https:\/\/yoast.com\/wordpress\/plugins\/seo\/ -->\n<title>Correct API usage - Shoptet Developers<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/developers.shoptet.com\/correct-api-usage\/\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Correct API usage - Shoptet Developers\" \/>\n<meta property=\"og:description\" content=\"Tips on how to carefully access and use Shoptet API resources.\" \/>\n<meta property=\"og:url\" content=\"https:\/\/developers.shoptet.com\/correct-api-usage\/\" \/>\n<meta property=\"og:site_name\" content=\"Shoptet Developers\" \/>\n<meta property=\"article:publisher\" content=\"https:\/\/www.facebook.com\/shoptet\" \/>\n<meta property=\"article:modified_time\" content=\"2025-09-22T11:35:19+00:00\" \/>\n<meta property=\"og:image\" content=\"https:\/\/developers.shoptet.com\/wp-content\/uploads\/2026\/02\/1200x630_en.png\" \/>\n\t<meta property=\"og:image:width\" content=\"1200\" \/>\n\t<meta property=\"og:image:height\" content=\"630\" \/>\n\t<meta property=\"og:image:type\" content=\"image\/png\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:site\" content=\"@Shoptet\" \/>\n<meta name=\"twitter:label1\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data1\" content=\"7 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\/\/developers.shoptet.com\/correct-api-usage\/\",\"url\":\"https:\/\/developers.shoptet.com\/correct-api-usage\/\",\"name\":\"Correct API usage - Shoptet Developers\",\"isPartOf\":{\"@id\":\"https:\/\/developers.shoptet.com\/#website\"},\"datePublished\":\"2019-04-04T08:24:45+00:00\",\"dateModified\":\"2025-09-22T11:35:19+00:00\",\"breadcrumb\":{\"@id\":\"https:\/\/developers.shoptet.com\/correct-api-usage\/#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/developers.shoptet.com\/correct-api-usage\/\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/developers.shoptet.com\/correct-api-usage\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/developers.shoptet.com\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Addons\",\"item\":\"https:\/\/developers.shoptet.com\/addons\/\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Documentation\",\"item\":\"https:\/\/developers.shoptet.com\/api\/documentation\/\"},{\"@type\":\"ListItem\",\"position\":4,\"name\":\"Correct API usage\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/developers.shoptet.com\/#website\",\"url\":\"https:\/\/developers.shoptet.com\/\",\"name\":\"Shoptet Developers\",\"description\":\"Offer your service to [projectCount] e-shops driven by\u00a0Shoptet\",\"publisher\":{\"@id\":\"https:\/\/developers.shoptet.com\/#organization\"},\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/developers.shoptet.com\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"en-US\"},{\"@type\":\"Organization\",\"@id\":\"https:\/\/developers.shoptet.com\/#organization\",\"name\":\"Shoptet s.r.o.\",\"url\":\"https:\/\/developers.shoptet.com\/\",\"logo\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/developers.shoptet.com\/#\/schema\/logo\/image\/\",\"url\":\"https:\/\/developers.shoptet.com\/wp-content\/uploads\/2019\/10\/Sni\u0301mek-obrazovky-2019-10-29-v-15.17.38.png\",\"contentUrl\":\"https:\/\/developers.shoptet.com\/wp-content\/uploads\/2019\/10\/Sni\u0301mek-obrazovky-2019-10-29-v-15.17.38.png\",\"width\":486,\"height\":174,\"caption\":\"Shoptet s.r.o.\"},\"image\":{\"@id\":\"https:\/\/developers.shoptet.com\/#\/schema\/logo\/image\/\"},\"sameAs\":[\"https:\/\/www.facebook.com\/shoptet\",\"https:\/\/x.com\/Shoptet\",\"https:\/\/www.instagram.com\/shoptet.cz\/\",\"https:\/\/cz.linkedin.com\/company\/shoptet\",\"https:\/\/www.youtube.com\/channel\/UCrmFOFsJ7Nd3viUS_Kf5jsg\"]}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Correct API usage - Shoptet Developers","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/developers.shoptet.com\/correct-api-usage\/","og_locale":"en_US","og_type":"article","og_title":"Correct API usage - Shoptet Developers","og_description":"Tips on how to carefully access and use Shoptet API resources.","og_url":"https:\/\/developers.shoptet.com\/correct-api-usage\/","og_site_name":"Shoptet Developers","article_publisher":"https:\/\/www.facebook.com\/shoptet","article_modified_time":"2025-09-22T11:35:19+00:00","og_image":[{"width":1200,"height":630,"url":"https:\/\/developers.shoptet.com\/wp-content\/uploads\/2026\/02\/1200x630_en.png","type":"image\/png"}],"twitter_card":"summary_large_image","twitter_site":"@Shoptet","twitter_misc":{"Est. reading time":"7 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/developers.shoptet.com\/correct-api-usage\/","url":"https:\/\/developers.shoptet.com\/correct-api-usage\/","name":"Correct API usage - Shoptet Developers","isPartOf":{"@id":"https:\/\/developers.shoptet.com\/#website"},"datePublished":"2019-04-04T08:24:45+00:00","dateModified":"2025-09-22T11:35:19+00:00","breadcrumb":{"@id":"https:\/\/developers.shoptet.com\/correct-api-usage\/#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/developers.shoptet.com\/correct-api-usage\/"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/developers.shoptet.com\/correct-api-usage\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/developers.shoptet.com\/"},{"@type":"ListItem","position":2,"name":"Addons","item":"https:\/\/developers.shoptet.com\/addons\/"},{"@type":"ListItem","position":3,"name":"Documentation","item":"https:\/\/developers.shoptet.com\/api\/documentation\/"},{"@type":"ListItem","position":4,"name":"Correct API usage"}]},{"@type":"WebSite","@id":"https:\/\/developers.shoptet.com\/#website","url":"https:\/\/developers.shoptet.com\/","name":"Shoptet Developers","description":"Offer your service to [projectCount] e-shops driven by\u00a0Shoptet","publisher":{"@id":"https:\/\/developers.shoptet.com\/#organization"},"potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/developers.shoptet.com\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-US"},{"@type":"Organization","@id":"https:\/\/developers.shoptet.com\/#organization","name":"Shoptet s.r.o.","url":"https:\/\/developers.shoptet.com\/","logo":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/developers.shoptet.com\/#\/schema\/logo\/image\/","url":"https:\/\/developers.shoptet.com\/wp-content\/uploads\/2019\/10\/Sni\u0301mek-obrazovky-2019-10-29-v-15.17.38.png","contentUrl":"https:\/\/developers.shoptet.com\/wp-content\/uploads\/2019\/10\/Sni\u0301mek-obrazovky-2019-10-29-v-15.17.38.png","width":486,"height":174,"caption":"Shoptet s.r.o."},"image":{"@id":"https:\/\/developers.shoptet.com\/#\/schema\/logo\/image\/"},"sameAs":["https:\/\/www.facebook.com\/shoptet","https:\/\/x.com\/Shoptet","https:\/\/www.instagram.com\/shoptet.cz\/","https:\/\/cz.linkedin.com\/company\/shoptet","https:\/\/www.youtube.com\/channel\/UCrmFOFsJ7Nd3viUS_Kf5jsg"]}]}},"_links":{"self":[{"href":"https:\/\/developers.shoptet.com\/wp-json\/wp\/v2\/pages\/648","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/developers.shoptet.com\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/developers.shoptet.com\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/developers.shoptet.com\/wp-json\/wp\/v2\/users\/26"}],"replies":[{"embeddable":true,"href":"https:\/\/developers.shoptet.com\/wp-json\/wp\/v2\/comments?post=648"}],"version-history":[{"count":24,"href":"https:\/\/developers.shoptet.com\/wp-json\/wp\/v2\/pages\/648\/revisions"}],"predecessor-version":[{"id":4554,"href":"https:\/\/developers.shoptet.com\/wp-json\/wp\/v2\/pages\/648\/revisions\/4554"}],"up":[{"embeddable":true,"href":"https:\/\/developers.shoptet.com\/wp-json\/wp\/v2\/pages\/230"}],"wp:attachment":[{"href":"https:\/\/developers.shoptet.com\/wp-json\/wp\/v2\/media?parent=648"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}