customer identifier, if the customer is registered in the e-shop (can be null)
Shoptet API (1.0.0)
Created in cooperation with the Ministry of Industry and Trade of the Czech Republic within the "The Country for the Future" programme.
This documentation provides information about the interface for developers who would like to gain access to Shoptet
e-shops. For more information about Shoptet, see https://www.shoptet.cz/.
The API is available in two access modes:
for "Shoptet partner” developers who create the interconnection with the services and extend the Shoptet system's functions for public usage. For more information about API and conditions, under which it can be used, see https://developers.shoptet.com/addons/.
direct private access to eshop data for eshop owner - available only for Premium Members. See https://developers.shoptet.com/premium for more information about API access.
API supports communication in JSON format. The URL for calling API requests is https://api.myshoptet.com. The API calls
(endpoints and message formats) are common for private as well as addons access, it however uses different authentication
and authorization principles.
API is made to create the supplements for the Shoptet system and uses OAuth2 authorization principles.
To access the API it is necessary to implement a web service at your side, which will communicate with our OAuth server.
In your e-shop administration, which you are using to work with our API, you must search in the API Partner section for the Access to API tab.
Here, you will find your clientID and addresses, from where you can call our OAuth server.
The work with API begins with e-shop addon installation. (The installation process can be tested in the addon detail in the Users section, where you can cause the installation for your e-shop.)
In your addon detail, in the Settings section, enter URL to gain a OAuth code. The URL must be linked to your server, where the script is prepared, which is able to gain an OAuth access token.
At this address, you will receive the HTTP request with a GET parameter code, when installing the addon, with unique value (a 255 character long string).
The code provided only has short-term validity and can be used only once. With this code, request our OAuth server to provide an OAuth access token.
Such a request shall follow within the same script that received the code.
Do not put off gaining the OAuth access token for a later time, and do not reply to our request with a 200 OK status, until you gain the OAuth access token.
The address for you to call, and an example of implementation, can be found in e-shop administration in the Access to API section.
As a response you will obtain a JSON with your OAuth access token. Save this token securely. Never send this token to the client computer, and use it only
for communication between the servers and for gaining the temporary token for access to API.
If you have successfully received an OAuth access token, your script must end with the HTTP status code “200”.
Now you have your OAuth access token, which links your addon with a specific e-shop, perhaps you would like to communicate with the e-shop via API.
From your server, call https://<eshop-address.tld>/action/ApiOAuthServer/getAccessToken address with HTTP header Authorization: Bearer <OAuth access token>.
As the reply, you will receive a JSON containing an API access token value and the token expiration time value. An example of calling can be found in e-shop administration in the Access to API section.
It is possible to request a maximum of 5 valid tokens.
The API access token will enable you to call an individual URL of our API, for example https://api.myshoptet.com/api/eshop. Send the API access token in each request in the HTTP headerShoptet-Access-Token.
You can have several valid API access tokens available at any one time. Should the validity of the API access token expire, you will receive a HTTP status code 401 and message about token expiration.
{
"data": 'null',
"errors": [
{
"errorCode": "expired-token",
"message": "Token is expired. Please ask for new one.",
"instance": "unknown"
}
]
}
If your token does not have the access right for a specific endpoint, you will obtain a reply with HTTP status code 403 Forbidden.
{
"data": 'null',
"errors": [
{
"errorCode": "invalid-token-no-rights",
"message": "Your access token \"afd..123\" has no defined rights for this resource.",
"instance": "access-token"
}
]
}
Rate limiting is at the level of server overload protection (DDoS), whereas the quantity of queries or total volume of data are unlimited.
These are therefore the limits of the maximum number of coincident active connections. A maximum of 50 from a single IP address, and a maximum of 3 connections for a single token. If the limit is exceeded, the HTTP code 429 is returned. See also Nginx configuration:
limit_conn per_ip 50;
limit_conn per_token 3;
limit_conn_status 429;Some URLs, for example for bulk operations, can have their own specific limits, which are mentioned in this documentation.
We have also prepared more detailed rules for checking the efficiency of calling your integrations using a leaky bucket algorithm.
We inform you about reaching the limits via headers X-RateLimit-Bucket-Filling (in every response), and Retry-After (only if bucket is fulfilled), e.g.
X-RateLimit-Bucket-Filling: 200/200
Retry-After: Mon, 01 Jul 2024 12:01:11 GMTFor more information, visit API Rate limiter.
Write endpoints (DELETE, PATCH, POST, PUT methods) can take longer and may be prone to two concurrent matching requests.
To avoid problems with retrying identical write requests, we have added the locking function of these requests to the application.
If you execute the same request two times in quick succession, the second request receives error response with a 423 code.
The lock is only valid for a specific called URL, for the duration of the request processing, but no longer than 5 seconds.
All JSON responses from the server have the same format, as a base.
If any of the sections is not present in the response, a null value is then received.
Example of call for addons:
curl --include \
-H 'Shoptet-Access-Token: 123456-a-123-XXXXXXXXXXXXXXXXXXXXXXXXX' \
-H 'Content-Type: application/json' \
'https://api.myshoptet.com/api/eshop'Example of call for private API access:
curl --include \
-H 'Shoptet-Private-API-Token: 123456-a-123-XXXXXXXXXXXXXXXXXXXXXXXXX' \
-H 'Content-Type: application/json' \
'https://api.myshoptet.com/api/eshop'Example of response:
HTTP/2 200
date: Fri, 13 Jul 2018 15:57:29 GMT
content-type: application/json; charset=utf-8
{
"data": {
"contactInformation": {
"eshopName": "www.domena-eshopu.cz",
"url": "https:\/\/www.domena-eshopu.cz\/",
"companyId": "28935675",
...
}
...
},
"errors": 'null'
}
The basic structure of the response in the event of an error is as follows:
{
"data": 'null',
"errors": [
{
"errorCode": "missing-access-token",
"message": "Missing access token. Please add `Shoptet-Access-Token` header to your request.",
"instance": "unknown"
}
]
}
Most of the endpoints are synchronous, i.e. your answer is provided immediately and contains the data requested. There
are however some endpoints, where either the request or the response processing takes longer time. These are implemented as
Asynchronous requests. Your request will be queued and you
receive only job identification in the response. You will be notified using a
webhook when the job is completed and your results
downloadable. Be aware, that registration of webhook job:finished is required to be able to run asynchronous requests.
If webhook is not registered, you will receive an error response with HTTP status code 403 and job won't be queued.
Webhook job:finished is also emitted when the job is failed so there is need to check the Detail of job to get the result of the job. If an error occurs during an asynchronous request, the job is automatically marked as failed 3 hours after its creation, and in this case, the job:finished webhook is not emitted.
Some attributes may be added to the new API version, or the sequence of attributes can be changed.
Your software, therefore, shall not rely on either of these.
If some attributes are renamed or removed, you will be informed in an additional
header - see also API versioning and Deprecated header + Sunset.
If you are calling some endpoint in a version that will not be supported in the future, you will receive a response with the header
X-Shoptet-Deprecated. If you detect this header within the response and its presence is logged,
you should be aware of the support termination for a specific endpoint in advance and thus have enough time for correction.
Furthermore, you shall also receive the response with aSunset header with the date when the support for this endpoint is to be terminated.
When processing the response, the client shall first detect, what response status code was received.
For GET requests for responses with 200 code, it is not necessary to explore the errors part of the response.
For PATCH/PUT requests, which can process more records at the same time and some records
are not processed successfully, these end with a 200 response code and the errors key contains info on skipped rows.
The unknown record is returned with a 404 code, etc. These responses have the error field filled in, where you can
find detailed info about the error.
The following errors might be expected:
400 - Some of the validations on item level have failed. There is no reason to retry, it will fail always.
401 - Invalid token or the token has expired (for addons access tokens). You have to ask for another one.
403 - Forbidden. The token has no rights to the endpoint called. The endpoints must be allowed for an addon and the eshop must have approved them. Valid for addons access tokens, private tokens can always access all endpoints. Can be also returned when required module for request is missing.
404 - Either the endpoint is wrong; or most commonly, an entity identifier, which is part of the URL, does not exist.
409 - Conflict - the action could not be completed for some consistency rules, such as duplicate data or relation, which would be broken.
413 - Payload too large - update requests can sometimes contain multiple entities to be amended. There is however a limit (varying for each request), how many can be specified within one request. If you breach the limit, you will get this error and nothing will be updated.
422 - Unprocessable entity - we were not able to parse the request - it does not match the expected format. Something is wrong with the request as whole, it might not be a correct JSON or it does not match the expected JSON schema. There is no reason to retry, it will always fail.
423 - Locked - for update and some read request we apply locks, usually on an URL level, which should avoid consistency problems possibly occuring from parallel updates. See chapter about locks. Retry later, try to avoid parallel update requests.
500 - General server error. Yes, this might happen to our software, too. Most commonly this is a temporary database issue and it might (but might not), work a few minutes later. We monitor all such errors and we try to analyze and fix them.
503 - System maintenance. Most commonly we move a database to another database cluster or a database migration is pending and it will be available in a few minutes. Please try later.
Some endpoints can return larger quantity of records. Such endpoints do not return the entire result, but support pagination of results.
You can page using page (int) and itemsPerPage (int) parameters. The first page has number 1. If you require a different
quantity of items per page, use the itemsPerPage parameter. CAUTION: the number of items per page can be decreased only, the default
value is maximum. The default value can be different for each endpoint.
When paging, check the total number of items, if not altered (totalCount), then the
items on pages could be shifted and some of them could be missed or processed twice.
Some endpoints return the data sections as optional, on demand. The request is done by giving the section name in the
include parameter. Part of the data is returned each time, the other section only on demand. This makes the responses smaller for those, who do not need the data
, thus saving the volume of data transmitted and shortening the time to process the request.
For example, for "Eshop Info" endpoint, you will gain basic info when simply calling [GET] /api/eshop, but payment
methods and transport options only when using [GET] /api/eshop?include=paymentMethods,shippingMethods.
More values are separated by a comma, no sequencing, no upper/lower case differentiation. Other blocks are available on demand
and each endpoint informs you which identifier to request.
For proper functionality in translations you will have to get module Foreign languages (Cizí jazyky) activated on customer e-shop. Multi-language support in API is handled by query parameter language, which can be used in whole API. If parameter is not set, default shop language is used.
Read endpoints (HTTP verb GET) will return corresponding language version of texts where applicable.
For write endpoints, first use POST endpoint to create entity and then use PATCH endpoint with corresponding language query parameter to set language fields.
Please note that in some endpoints (typically surcharge/filtering/variant parameters) you must use the identifier's currently selected language variant (which is filtered in list).
For files upload, there are Files endpoints.
The file is uploaded to a temporary storage which is not accessible publicly. The file is kept there for 7 days and then deleted.
After you upload a file, you may copy it to some API entities in their endpoints - you specify filename returned in response of upload job.
Please note that currently only images (png, jpg, gif) are allowed filetypes for file upload.
Shoptet saves the product images in their original size and then prepares several sizes for standardized usage (called
image cuts). These cuts are created in advance and saved on the disk, so they are readily available. The list of cuts is
the same for each e-shop, and each e-shop can theoretically have different cut sizes. In practice, their size is given
by the template and most templates use the same sizes. The list of provided cuts is given by
the Image cuts code list.
The /api/eshop?include=imageCuts endpoint returns the imageCuts field in the response, where each cut has the actual
size defined, and the URL base path. There are two base URLs (example for classic.shoptet.cz, cut detail):
urlPath: "https://classic.shoptet.cz/user/shop/detail/"cdnPath: "https://cdn-api.myshoptet.com/usr/classic.shoptet.cz/user/shop/detail/"
Use the urlPath in case you need an up-to-date image right now. Use the url for your backend processing and you
will retrieve the images only once. Images retrieved via urlPath are not cached. You can use image name or SEO version
of the image name - see below.
Use the cdnPath in case you want to use the image url on the frontend and users of your application will display it,
e.g. if you provide an alternative frontend, mobile application etc. The images are cached and provided with lower
latency. Use cdnName retrieved from the product detail endpoint (or similar) - see below.
Once you determine the URL based on the purpose and image cut size (for example detail for product detail, or related
for product preview), just append the filename you need. The filename can be retrieved from Product detail endpoint.
Although the e-shop is behind the content delivery network (Cloudflare CDN), API still returns the same domain. Whether
the e-shop is behind the Cloudflare CDN, you can find out from response headers (CDN-Loop: cloudflare header).
The product detail endpoint /api/products/{guid}?include=images returns the image field data.images[] in the same
sequence, as these are entered in administration. The file name name (for example 100.jpg) needs to be connected
to the URL cut and then you have complete path to the image of a given cut (size), for example
https://classic.shoptet.cz/user/shop/detail/100.jpg. You can also use seoName, which also contains a description
of the image - you will be redirected to the same image. The cdnName is intended for use with the cdnUrl only.
The fields look like: (excerpt)
"name": "106.png",
"description": "shamrock 2115611 640",
"seoName": "106_shamrock-2115611-640.png",
"cdnName": "106_shamrock-2115611-640.png?5b2a41f5"One of the images mentioned for the product can be selected as the default image for the product variant. The selected
image is in data.variants[].image item and contains the name of the image – this can be searched for in the image
list, in the name item. Should the variant have no preselected default image, the parameter image is null.
If data.variants[].isProductDefaultImage is true, then the default product image is given. If it is false, then it is the default variant image.
The item data.items[].mainImage contains the main image in order detail - this is either a default variant image,
or, if not set (or product does not have variants), the default product image is given. The structure is the same as
in product details, but not all images are given here, only the default one – representative image. The full path can
be gained by assembling the urlPath from the e-shop info and the name or seoName items, given for the order item.
Similarly, the product list gives data.products[].mainImage, which mentions the initial image for each product.
| Value | Description |
|---|---|
| orig | original image (in the original resolution) |
| big | big image (typically 1024x768 px) |
| detail | image detail (typically 360x270 px) |
| category | size for listing in category (typically 216x105 px) |
| related | size for related products (typically 100x100 px) |
| Value | Description |
|---|---|
| hidden | Hide product |
| visible | Show product |
| blocked | Cannot be ordered |
| show-registered | Show only to logged-in users |
| block-unregistered | Do not allow order to logged-out users |
| cash-desk-only | Show only in cash desk |
| detail-only | Do not show e-shop navigation |
| Value | Description |
|---|---|
| product | Product |
| bazar | Second-hand product |
| service | Service |
| gift-certificate | Gift (deprecated) |
| product-set | Product set |
| Value | Description |
|---|---|
| product | Product |
| bazar | Second-hand product |
| service | Service |
| shipping | Transportation |
| billing | Payment method |
| discount-coupon | Discount coupon |
| volume-discount | Volume discount |
| gift | Gift |
| gift-certificate | Gift certificate |
| generic-item | Non-specific item |
| product-set | Product set |
| product-set-item | Product set item |
| deposit | Deposit |
| Value | Description |
|---|---|
| default | Default |
| most-selling | Most selling first |
| cheapest | Cheapest first |
| most-expensive | Most expensive first |
| oldest | Oldest first |
| newest | Newest first |
| alphabetically | Alphabetically |
| alphabetically-desc | Alphabetically, descending |
| product-code | Per product code |
| product-code-desc | Per product code, descending |
| category-priority | Category priority |
| category-priority-desc | Category priority, descending |
| Value | Description | Identifier meaning |
|---|---|---|
| brand:create | Brand creation event | String (code) - brand unique code |
| brand:update | Brand change event | String (code) - brand unique code |
| brand:delete | Brand deleting event | String (code) - brand unique code |
| category:create | Category creation event | String (guid) of product category |
| category:update | Category change event | String (guid) of product category |
| category:delete | Category deleting event | String (guid) of product category |
| creditNote:create | Credit note creation event | Number (code) of credit note |
| creditNote:delete | Credit note deleting event | Number (code) of credit note |
| creditNote:update | Credit note change event | Number (code) of credit note |
| customer:create | New customer was created | Customer GUID |
| customer:update | Customer was updated. Throws 409 Conflict when try to register simultaneously with customer:disableOrders or customer:enableOrders | Customer GUID |
| customer:disableOrders | An event disabled the customer, and his future orders will be automatically cancelled. Throws 409 Conflict when try to register simultaneously with customer:update | Customer GUID |
| customer:enableOrders | An event enabled the customer's future orders. Throws 409 Conflict when try to register simultaneously with customer:update | Customer GUID |
| customer:import | Import of 1 and more customers was executed | Fixed string "customers" |
| customer:delete | Customer was deleted | Customer GUID |
| deliveryNote:create | Delivery note creation event | Number (code) of delivery note |
| deliveryNote:delete | Delivery note deleting event | Number (code) of delivery note |
| deliveryNote:update | Delivery note change event | Number (code) of delivery note |
| discountCoupon:create | Discount coupon creating event | String (code) - discount coupon unique code |
| discountCoupon:delete | Discount coupon deleting event | String (code) of discount coupon |
| discountCoupon:update | Discount coupon updating event | String (code) - discount coupon unique code |
| eshop:currencies | Currencies settings change event | ID of eshop |
| eshop:billingInformation | Billing information (i.e. eshop billing address) change event | ID of eshop |
| eshop:settingsInformation | Eshop settings change event. Whenever some attribute from data.settings response section of GET eshop detail change | ID of eshop |
| eshop:design | Design settings (template, colors, fonts, layout) | ID of eshop |
| eshop:mandatoryFields | Mandatory fields of customer were updated | ID of eshop |
| eshop:projectDomain | Domain of eshop was changed | ID of eshop |
| invoice:create | Invoice creation event | Number (code) of invoice |
| invoice:delete | Invoice deleting event | Number (code) of invoice |
| invoice:update | Invoice change event | Number (code) of invoice |
| job:finished | The asynchronous request was finished | Job id |
| mailingListEmail:create | E-mail addition event into the e-mail distribution list | Name (code) of e-mail distribution list |
| mailingListEmail:delete | E-mail deleting event from the e-mail distribution list | Name (code) of e-mail distribution |
| order:cancel | Order cancel event. Webhook is emitted when order status is set to canceled. Throws 409 Conflict when try to register simultaneously with order:update | Number (code) of order |
| order:create | Order creation event | Number (code) of order |
| order:delete | Order deleting event | Number (code) of order |
| order:update | Order change event. Throws 409 Conflict when try to register simultaneously with order:cancel | Number (code) of order |
| orderHistoryRemarks:change | Order history remarks have been changed. Emitted when order remark is created or deleted | Order ID |
| orderStatusesList:change | Order status list change event. Emitted when order status is created, updated or deleted | Order status ID |
| paymentMethod:change | Payment method change event | Payment method GUID |
| proformaInvoice:create | Proforma invoice creation event | Number (code) of proforma invoice |
| proformaInvoice:delete | Proforma invoice deleting event | Number (code) of proforma invoice |
| proformaInvoice:update | Proforma invoice change event | Number (code) of proforma invoice |
| proofPayment:create | Proof of payment creation event | Number (code) of proof payment |
| proofPayment:delete | Proof of payment deleting event | Number (code) of proof payment |
| proofPayment:update | Proof of payment change event | Number (code) of proof payment |
| quantityDiscount:create | Quantity discount creation event | ID of quantity discount |
| quantityDiscount:update | Quantity discount change event | ID of quantity discount |
| quantityDiscount:delete | Quantity discount deleting event | ID of quantity discount |
| shippingMethod:change | Shipping method change event | Shipping method GUID |
| shippingRequest:cancelled | Shipping request was not chosen for order delivery | shippingRequestCode associated with the cart |
| shippingRequest:confirmed | Shipping request was chosen for order delivery | shippingRequestCode associated with the cart |
| stock:movement | Stock change event | Stock ID |
| stock:inStock (*) | Stock change event - sum across all of the stocks raised above 0 (beta, see below) | Number (code) of product |
| stock:soldOut (*) | Stock change event - sum across all of the stocks reached 0 (beta, see below) | Number (code) of product |
| stock:minStockSupplyReached (*) | Stock change event - sum across all of the stocks reached minimum stock supply value, if this limit is set for product (beta, see below) | Number (code) of product |
(*) These webhooks are considered beta/experimental, for more information, please visit the X-url
These webhooks are sent when a mass change of entities is performed. The payload contains a json serialized list of IDs of changed entities.
Purpose of these webhooks is to downgrade number of requests, while i.e. administrator performs mass change of orders status at once etc.
So instead of emitting one event for every order, we emit one event for all of them.
For now, if some mass event is performed, we also sent "single" webhook event for every updated entity as usual, but it will be changed in future, so please watch release changes for more info
| Value | Description | Identifier meaning |
|---|---|---|
| category:massCreate | Mass create of product categories event | Json serialized list of string (guid) of product categories |
| category:massUpdate | Mass change of product categories event | Json serialized list of string (guid) of product categories |
| category:massDelete | Mass delete of product categories event | Json serialized list of string (guid) of product categories |
| discountCoupon:massCreate | Mass create of discount coupons event | Json serialized list of string (code) of discount coupons |
| discountCoupon:massDelete | Mass delete of discount coupons event | Json serialized list of string (code) of discount coupons |
| invoice:massUpdate | Mass change of invoices event | Json serialized list of number (code) of invoices |
| order:massCreate | Mass create of orders event | Json serialized list of number (code) of orders |
| order:massUpdate | Mass change of orders event | Json serialized list of number (code) of orders |
| quantityDiscount:massDelete | Mass delete of quantity discount event | Json serialized list of quantity discounts IDs |
| quantityDiscount:massUpdate | Mass change of quantity discount event | Json serialized list of quantity discounts IDs |
These webhooks cannot be registered via API, they are setup in Partners' Addon administration section instead.
| Value | Description |
|---|---|
| addon:suspend | The addon was suspended by the eshop or by Shoptet operations staff |
| addon:approve | The addon was approved (resumed) after it was suspended |
| addon:terminate | The addon was terminated by the eshop or by Shoptet operations staff |
| addon:uninstall | The addon was uninstalled by the eshop admin or the eshop was terminated |
See endpoint Eshop info
| Ident | Description |
|---|---|
| admin-orders-list | Listing of orders in administration |
| admin-customers-list | List of customers in administration |
| oauth | OAuth server address, used for e-shop user verification |
| Provider (identification) | Description |
|---|---|
| glami | Glami |
| heureka | Heuréka |
| zbozi | Zboží.cz |
| id | Description |
|---|---|
| 1 | COD (cz: Dobírka) |
| 2 | Wire transfer (cz: Převodem) |
| 3 | Cash (cz: Hotově) |
| 4 | Card (cz: Kartou) |
If you use Postman as an API platform for building and using APIs, we provide you a complex collection of Shoptet API.
You have 2 options how to import our postman collection (created from openApi schema - openapi.yaml ) into your postman client
Also check postman documentation for more details: Fork a collection.
Once inside the Shoptet Public API Workspace, go to the Collections tab.
Find the Shoptet API collection.
Click on the Shoptet API collection to open it.
In the collection view, click the Fork button in the top-right corner.
In the fork dialog, choose a name for your forked collection.
Select the workspace where you want to save the forked collection.
It’s recommended to check
watch original collectionto get notified about changes in the original collection.Click Fork Collection.
Navigate to the workspace where you saved the forked collection.
You’ll now find the forked Shoptet API collection under the Collections tab, ready for you to use and modify.
Now you have your own copy of the Shoptet API collection! If you want to add changes from the original collection, you can do so by click on pull changes in collection settings.
Download the openapi.yaml file from our developers repository.
Launch Postman on your desktop or in the browser.
In the top-left corner of Postman, click the Import button.
A pop-up window will appear.
Drag and drop your
openapi.yamlfile into the window, or click Upload Files and browse to the file's location.
Postman will automatically recognize the OpenAPI schema.
It will display a preview of the API schema.
Once the file is recognized, click Import.
Postman will convert the OpenAPI schema into a collection of requests, based on the defined endpoints in the
openapi.yamlfile.
After the import is successful, go to the Collections tab.
You’ll find your new collection, named after the OpenAPI schema, containing all the API requests generated from the file.
Now you can explore the API endpoints and use them directly within Postman!
Click the Shoptet API collection name.
Go to Authorization tab.
Set your access token into the
valueofShoptet-Access-Tokenkey.Go to Variables tab.
You can set
baseUrlvariable here.
Download OpenAPI description
Languages
Servers
Mock server
https://api.docs.shoptet.com/_mock/shoptet-api/openapi/
https://api.myshoptet.com/
Request
List of orders in e-shop and cash desks. Endpoint supports pagination. For default calls, it returns 20 orders,
using the parameter ?itemsPerPage=100, you can request up to 100 orders at a time. Temporarily disabled, only 20 orders per page is supported. We apologize for the inconvenience.
The list can be filtered according to status, transport, payment, date of creation, order number and customer number.
The code (code) is the order identifier. Although this is usually a number, it is necessary to take into account that this might also include
letters, dash, etc.
Query
Purchase order filtering, according to forwarder company code.
Purchase order filtering, according to date of creation. ISO 8601 format ("2017-12-12T22:08:01+0100").
Purchase order filtering, according to date of creation. ISO 8601 format ("2017-12-12T22:08:01+0100").
Purchase order filtering, according to customer e-mail. The accurate match is searched for, regardless of capitalization.
Purchase order filtering, according to customer phone. International format only (+420123456789)
Purchase order filtering, according to date of last update. ISO 8601 format ("2017-12-12T22:08:01+0100").
Purchase order filtering, according to date of last update. ISO 8601 format ("2017-12-12T22:08:01+0100").
- Mock server
https://api.docs.shoptet.com/_mock/shoptet-api/openapi/api/orders
https://api.myshoptet.com/api/orders
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://api.docs.shoptet.com/_mock/shoptet-api/openapi/api/orders?changeTimeFrom=string&changeTimeTo=string&codeFrom=string&codeTo=string&creationTimeFrom=string&creationTimeTo=string&customerGuid=string&email=string&paymentMethodGuid=string&phone=string&productCode=string&shippingCompanyCode=string&shippingGuid=string&sourceId=string&statusId=string' \
-H 'Content-Type: application/json' \
-H 'Shoptet-Access-Token: YOUR_API_KEY_HERE'OK
order number. Caution! This does not have to be just a number, it can also contain letters, a dash, etc.
global unique permanent order identifier (can be null for old orders)
data.orders[].creationTimestring or null(typeDateTime)^[0-9]{4}-[01][0-9]-[0123][0-9]T[012][0-9]:[0...required
date and time, when the order was created. ISO 8601 format.
data.orders[].changeTimestring or null(typeDateTime)^[0-9]{4}-[01][0-9]-[0123][0-9]T[012][0-9]:[0...required
date and time of the order's last change. ISO 8601 format.
flag, whether the order is from the cash desk (as opposed to the e-shop)
URL to administration leading to order detail. URL keeps the administration language settings.
price of the order
VAT value, two decimal places
total price to pay
currency code. List of available currencies within the e-shop can be found in endpoint GET /api/eshop.
price excluding tax
price including tax
currency rate of the receipt for the default currency of the shop. This value is saved together with the price and reflects the historical value valid in the instant of the order creation. If the shop changes the default currency, the value still refers to the original currency!
can be value expressed in percents or as exact money value expression (with up to two decimal places) - depends on partialPaymentType value
Response
application/json; charset=utf-8
{ "data": { "orders": [ … ], "paginator": { … } }, "errors": [ { … } ] }
Request
This endpoint enables insert the order into Shoptet, which was created in other system. You can use it for an import
from an older e-shop solution, or to transfer orders from external sales channels.
A large amount of info can be set, but for regular usage only a few attributes are needed. Values of other
attributes are added as per their default values. The detailed information can be found in the right pane, after
clicking on title "Order insertion" above (search for "Request" and "Attributes” sections).
Request is sent in JSON format in its body. Simple example (detailed example can be found in call example in right pane):
{
"data": {
"email": "foo@bar.cz",
"externalCode": "123",
"paymentMethodGuid": "6f2c8e36-3faf-11e2-a723-705ab6a2ba75",
"shippingGuid": "8921cdc1-051b-11e5-a8d3-ac162d8a2454",
"billingAddress": {
"fullName": "Jan Novák",
"street": "Rovná",
"city": "Rovina",
"zip": "12300"
},
"currency": {
"code": "CZK"
},
"items": [
{
"itemType": "product",
"code": "32/ZEL",
"vatRate": "21.00",
"itemPriceWithVat": "121.00"
},
{
"itemType": "billing",
"name": "Platba převodem",
"vatRate": "21.00",
"itemPriceWithVat": "0"
},
{
"itemType": "shipping",
"name": "PPL",
"vatRate": "21.00",
"itemPriceWithVat": "59.00"
}
]
}
}
Whether the field is mandatory, apart from the basic definition, also depends on whether the order was created via the cash desk
(cashDeskOrder: true) or via e-shop. Some fields from invoicing, delivery and contact data
are mandatory or optional, as per e-shop settings (see also e-shop administration Settings > Customers > Mandatory fields).
When the order is created, it is checked, whether the e-shop includes products with the respective code (can be suppressed with
GET parameter suppressProductChecking=true),
the products from the order are deducted from the stock (can be suppressed with the GET parameter suppressStockMovements=true), documentation is created for the order (can be suppressed with the GET parameter suppressDocumentGeneration=true), a confirmation e-mail is sent (can be suppressed with the GET parameter suppressEmailSending=true) and a webhook is executed for the new order.
**Parameters suppressProductChecking=true and suppressStockMovements=true are to be used only for orders that will not be changed or deleted in the future.
Editing or deleting such an order can damage the consistency of warehousing.**
Parameter suppressHistoricalMandatoryFields=true can be used to disable mandatory fields checks, but only for "historical"
orders (creationTime is older than 24 hours). Keep in mind even historical orders should be kept consistent and complete
as much as possible to allow their processing for statistics, volume calculations etc.
Setting the mandatory items for invoicing and the delivery address can be different between individual e-shops. The mandatory items corresponds to the settings
for ordering from the basket.
Parameters suppressHistoricalPaymentChecking and suppressHistoricalShippingChecking allow corresponding field (paymentMethodGuid and/or shippingGuid)
to be null. In that case, if an billing/shipping item is provided in items list, name field must be filled in that item.
To remove products from the stock, the shop (or product) setting as to whether the inventory can be negative or not is respected.
If a negative value is not permitted for shopping and the order cannot be covered from the current inventory, the order is not created and the API
returns an error message in the errors field.
The order's minimum size or maximum number of items as per the settings of e-shop are not checked.
The endpoint only checks the same parameters as the order detail.
The order can be inserted while using currencies setup in the eshop (see /api/eshop). The exchange rate related to the
eshop default currency is optional. If not provided, the current eshop exchange rate will be used.
For historical orders the exchange rate should be provided using the historical value of the order's creation date.
Shoptet eshops do not store historical exchange rates.
Warning: for SK and CZ different exchange rate format is used. You should use the same form as you get from the endpoint
/api/eshop. We will internally convert it to the correct format to be compatible with eshop statistics calculations.
Because of the conversion, the value of exchangeRate in the response will be different (inverse) to the one you had sent.
When entering the order, the initial welcome e-mail is always sent. Even though the order status is set differently to the initial value,
the e-mail associated with a status change is not sent, but the system welcome e-mail is (to e-shop operator and customer).
When creating the receipt (invoice, proforma invoice, delivery note) the receipt is created with the current date and the 14 days due date, even though
creationTime is given from the past.
Examples of how to work with the order and items statuses, and how to ensure the correct insertion of a discount, can be found in a
separate article at developers.shoptet.com
After the order is successfully created, you will receive a response with a 201 code and a response structure matching the order detail,
which is returned by /api/orders/<code> endpoint.
Please note following rules
code.. maxLength 10 charactersemail.. maxLength 100 charactersphone.. maxLength 32 charactersexternalCode.. maxLength 255 charactersbillingAddress.company.. maxLength 100 charactersbillingAddress.fullName.. maxLength 100 charactersbillingAddress.street.. maxLength 100 charactersbillingAddress.houseNumber.. maxLength 16 charactersbillingAddress.city.. maxLength 100 charactersbillingAddress.district.. maxLength 64 charactersbillingAddress.additional.. maxLength 64 charactersbillingAddress.zip.. maxLength 100 charactersbillingAddress.regionName.. maxLength 128 charactersbillingAddress.regionShortcut.. maxLength 16 charactersbillingAddress.companyId.. maxLength 18 charactersbillingAddress.vatId.. maxLength 16 charactersbillingAddress.taxId.. maxLength 16 charactersdeliveryAddress.company.. maxLength 255 charactersdeliveryAddress.fullName.. maxLength 64 charactersdeliveryAddress.street.. maxLength 100 charactersdeliveryAddress.houseNumber.. maxLength 16 charactersdeliveryAddress.city.. maxLength 100 charactersdeliveryAddress.district.. maxLength 64 charactersdeliveryAddress.additional.. maxLength 64 charactersdeliveryAddress.zip.. maxLength 100 charactersdeliveryAddress.regionName.. maxLength 128 charactersdeliveryAddress.regionShortcut.. maxLength 16 charactersnotes.trackingNumber.. maxLength 32 charactersitems.name.. maxLength 250 charactersitems.variantName.. maxLength 128 charactersitems.brand.. maxLength 64 charactersitems.supplierName.. maxLength 255 charactersitems.code.. maxLength 64 charactersitems.additionalField.. maxLength 255 charactersitems.amountUnit.. maxLength 16 characters
Query
Bodyapplication/jsonsuppress the generation of linked documents.
Default "false"
Example: suppressDocumentGeneration=true
suppress sending the linked information e-mails.
Default "false"
Example: suppressEmailSending=true
suppress the product existence check as per code and GUID
Default "false"
Example: suppressProductChecking=true
suppress deduction of the products from stock
Default "false"
Example: suppressStockMovements=true
set the flag that disables mandatory fields checking
Default "false"
Example: suppressHistoricalMandatoryFields=true
set the flag that paymentMethodGuid can be null
Default "false"
Example: suppressHistoricalPaymentChecking=true
Unique identifier for an e-shop order. Caution! This does not have to be just a number, it can also contain letters, a dash, etc.
order identification within the external system (mandatory, must be unique).
flag, if the order was created via the cash desk. Optional. false is the default value.
Order status. Optional. If not indicated, the default status of the order is used, as per e-shop settings. If the status definition sets the payment flag, the parameter paid is set to true. if the request also mentions paid, the paid variant has priority. If the status definition has selected the setting of item statuses, the status is also set for items. Otherwise, the initial status is the set based on e-shop defaults. If the item has status set explicitly (see below items[].statusId), the value from the item shall be used.
Order source id. Optional. If not indicated, no source will be used (null). If sourceId is positive, cashDeskOnly must also be set to true, otherwise if sourceId is negative, cashDeskOnly must be set to false, otherwise error will be returned. Current possible values of sourceId can be determined by calling the list of order sources endpoint.
customer e-mail (can be omitted only when ordering via cash desk).
phone number of the customer. Optional, if not set as mandatory item in shop settings.
customer birth date (optional, if not made mandatory by the e-shop settings).
Flag, whether the invoice was issued in VAT payer mode, or VAT non-payer mode. Optional, if not indicated, it is used as per current settings of the e-shop (only makes sense for historical orders, if e-shop changed its status form VAT payer to different or vice versa)
Payment method. Optional, for an order via cash desk or eshop order. Does not automatically generate payment item in the list of items, and does not check the consistency with payment item. Billing item type is mandatory if paymentMethodGuid is filled.
Transport method. Optional, for an order via cash desk or eshop order. Does not automatically generate transport item in the list of items, and does not check the consistency with the transport item. Shipping item type is mandatory if shippingGuid is filled.
additional information for transport, if any. typically ID of Zásilkovna branches, postal offices, etc. (optional)
One of:
additional information for transport, if any. typically ID of Zásilkovna branches, postal offices, etc. (optional)
null
additional information for transport, if any. typically ID of Zásilkovna branches, postal offices, etc. (optional)
billing method - see also Billing method. Optional.
IP address of the customer, from where the order was made
Customer GUID, if not done under known registered customer (optional).
additional notes for the order
One of:
additional notes for the order
null
additional notes for the order
stock number. Optional, the default value is the default stock, taken from e-shop settings. In Shoptet, the only alternative to the default stock is to collect in person at the shop, otherwise the default stock is used.
VAT mode, Normal is used by default, possible values: Normal, One Stop Shop*, Reverse charge, Outside the EU. Please note, that One Stop Shop value requires eshop OSS setting to be true.
- Mock server
https://api.docs.shoptet.com/_mock/shoptet-api/openapi/api/orders
https://api.myshoptet.com/api/orders
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
'https://api.docs.shoptet.com/_mock/shoptet-api/openapi/api/orders?suppressDocumentGeneration=true&suppressEmailSending=true&suppressHistoricalMandatoryFields=true&suppressHistoricalPaymentChecking=true&suppressHistoricalShippingChecking=true&suppressProductChecking=true&suppressStockMovements=true' \
-H 'Content-Type: application/json' \
-H 'Shoptet-Access-Token: YOUR_API_KEY_HERE' \
-d '{
"data": {
"creationTime": "2018-01-21T14:15:47+0100",
"code": "2024-123",
"language": "cs",
"externalCode": "X123",
"cashDeskOrder": true,
"statusId": -1,
"sourceId": -1,
"email": "foo@bar.cz",
"phone": "+420123456789",
"birthDate": "1990-01-01",
"vatPayer": true,
"paymentMethodGuid": "1b02cb8e-d7b5-11e0-9a5c-feab5ed617ed",
"shippingGuid": "1b02cb8e-d7b5-11e0-9a5c-feab5ed617ed",
"shippingDetails": {},
"paid": true,
"billingMethodCode": 2,
"clientIPAddress": "62.128.123.12",
"customerGuid": "1b02cb8e-d7b5-11e0-9a5c-feab5ed617ed",
"billingAddress": {
"company": "Smith & Smith",
"fullName": "John Doe",
"street": "Main Street",
"streetWithNr": "Main Street 123",
"houseNumber": "123",
"city": "Flat Country",
"district": "Bohemia",
"additional": "3rd floor",
"zip": "123 00",
"countryCode": "CZ",
"regionName": "Central Bohemia",
"regionShortcut": "SC",
"companyId": "123456",
"vatId": "CZ123456",
"taxId": "CZ123456"
},
"addressesEqual": true,
"deliveryAddress": {},
"notes": {},
"stockId": 1,
"currency": {
"code": "CZK",
"exchangeRate": "1.0000"
},
"vatMode": "Normal",
"items": [
{
"itemType": "product",
"name": "Large chocolate",
"variantName": "Dark chocolate",
"brand": "Willy Wonka",
"supplierName": "Dodavatel s.r.o.",
"productGuid": "1b02cb8e-d7b5-11e0-9a5c-feab5ed617ed",
"code": "123-456",
"remark": "With cubicles",
"warrantyDescription": "2 years",
"amountCompleted": "1.000",
"additionalField": "TO BALÍKOVNA, Karlínské náměstí 145/1, Karlín, 18600, Prague",
"amount": "1.000",
"amountUnit": "ks",
"weight": "100",
"priceRatio": "0.7",
"vatRate": "21.00",
"itemPriceWithVat": "121.00",
"itemPriceWithoutVat": "100.00",
"buyPriceWithVat": "121.00",
"buyPriceWithoutVat": "100.00",
"buyPriceVatRate": "21.00",
"statusId": -1,
"recyclingFeeId": 2,
"surchargeParameters": [
{
"parameterCode": "surchargeCode",
"valueIndex": "high",
"price": "21.00"
}
],
"consumptionTaxId": 1
}
]
}
}'Created
order number. Caution! This does not have to be just a number, it can also contain letters, a dash, etc.
global unique permanent order identifier (can be null for old orders)
Identification of the order in external system (or null).
data.order.creationTimestring or null(typeDateTime)^[0-9]{4}-[01][0-9]-[0123][0-9]T[012][0-9]:[0...required
date and time, when the order was created. ISO 8601 format.
data.order.changeTimestring or null(typeDateTime)^[0-9]{4}-[01][0-9]-[0123][0-9]T[012][0-9]:[0...required
date and time of the order's last change. ISO 8601 format.
customer identifier, if the customer is registered in the e-shop (can be null)
flag, whether the order is from the cash desk (as opposed to the e-shop)
flag, whether the delivery address is the same as the invoicing address
Is the tradesman a VAT payer, when purchasing? (can be null, if this is unknown)
VAT mode, for possible values see VAT modes
designation of the billing method. See also code list of billing methods.
URL to administration leading to order detail. URL keeps the administration language settings.
price of the order
VAT value, two decimal places
currency code. List of available currencies within the e-shop can be found in endpoint GET /api/eshop.
price excluding tax
price including tax
currency rate of the receipt for the default currency of the shop. This value is saved together with the price and reflects the historical value valid in the instant of the order creation. If the shop changes the default currency, the value still refers to the original currency!
can be value expressed in percents or as exact money value expression (with up to two decimal places) - depends on partialPaymentType value
flag, whether the order was paid. In addition to true a false, can also be null, if the payment status is unknown.
additional address information (or null)
tree-character ISO country code (ISO 4217)
Company registration number. (can be null)
Info, whether VAT ID has been verified, enum [unverified, verified, waiting]
Enum"unverified""verified""waiting"null
One of:
additional address information (or null)
tree-character ISO country code (ISO 4217)
all order items
product identifier of the item. At the time the order is created, it will be entered in this field, but when the product is deleted, the link will be lost (can be null)
identifier of the item code (product or variant). At the time the order is created, it will be entered in this field, but when the product is deleted, the link will be lost.
order item type (product, service...). See also Code list of order item types
product type at the time of the order (product, product-set..). See also Product type code list (can be null).
weight in kg, unpacked (can be null). 3 decimal places. Maximum value 999999.
product quantity
price coefficient. This also represents a discount (discount 10 % means priceRatio = 0.9)
the price of the item including the discount (priceRatio) and quantity (amount).
price including tax
price excluding tax
VAT value, two decimal places
purchase price of the item including the discount (priceRatio) and quantity (amount). (or possibly null)
recycling fee including category and price (or possibly null).
textual description of warranty length (can be null)
quantity of completed product
items surcharge parameters, filled in order creation. Cannot be edited.
list of specific surcharge parameters for order item detail, created from surchargeParameters, but editable in order item detail in eshop administration or via order item detail surcharge-parameters endpoint.
consumption tax of order item
Response
application/json; charset=utf-8
{ "data": { "order": { … } }, "errors": [ { … } ] }
Request
Using this endpoint, you can get list of all orders with detailed info of each order (like in Order Detail endpoint) asynchronously. See how Asynchronous requests work on our developer's portal.
The list may be filtered by date of creation and order code. The code is the order identifier. Although this is usually a number, it is necessary to take into account that this might also include letters, dash, etc.
Response will be in jsonlines format with each order taking one line of output file. One order in response has the same format as order detail response (in data attribute)
This endpoint has several sections, which are exported only when requested in the include parameter (see Requested sections).
| Include parameter | Meaning |
|---|---|
notes | Order remarks, including up to six additional fields, which can be freely used by e-shop for its individual needs. The field names can be defined in administration and this section returns their names. |
images | Order images |
shippingDetails | Transport details |
stockLocation | Position in the stock |
surchargeParameters | Item surcharge parameters |
productFlags | Item product flags |
Result file is compressed using GZIP.
Query
Optional parts of response. Available values are notes,images,shippingDetails,stockLocation,surchargeParameters.
Purchase order filtering, according to forwarder company code.
Purchase order filtering, according to date of creation. ISO 8601 format ("2017-12-12T22:08:01+0100").
Purchase order filtering, according to date of creation. ISO 8601 format ("2017-12-12T22:08:01+0100").
Purchase order filtering, according to customer e-mail. The accurate match is searched for, regardless of capitalization.
Purchase order filtering, according to customer phone. International format only (+420123456789)
Purchase order filtering, according to date of last update. ISO 8601 format ("2017-12-12T22:08:01+0100").
Purchase order filtering, according to date of last update. ISO 8601 format ("2017-12-12T22:08:01+0100").
- Mock server
https://api.docs.shoptet.com/_mock/shoptet-api/openapi/api/orders/snapshot
https://api.myshoptet.com/api/orders/snapshot
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://api.docs.shoptet.com/_mock/shoptet-api/openapi/api/orders/snapshot?changeTimeFrom=string&changeTimeTo=string&codeFrom=string&codeTo=string&creationTimeFrom=string&creationTimeTo=string&customerGuid=string&email=string&include=string&paymentMethodGuid=string&phone=string&productCode=string&shippingCompanyCode=string&shippingGuid=string&sourceId=string&statusId=string' \
-H 'Content-Type: application/json' \
-H 'Shoptet-Access-Token: YOUR_API_KEY_HERE'Response
application/json; charset=utf-8
{ "data": { "jobId": "ad24xod" }, "errors": [ { … } ] }
Templates
In the last Shoptet version, it is not possible to change the e-shop design via API. However, it is possible to include HTML codes
into previously defined places. This enables the code or link to a file containing additional CSS styles or JavaScript codes to be entered.
The same functionality is now included within the e-shop administration (/admin/html-kody/, HTML code tab).
There are 3 possible locations, where HTML codes can be inserted:
common-header- the code will be inserted into each e-shop page header (<HEAD>)common-footer- the code will be inserted into each e-shop page foot (before end</BODY>)order-confirmed- the code will be inserted in the page confirming the order (the "thank you page")
The inserted codes may come from 3 sources, and they are included in the following order:
Codes from addons (the addon defines HTML codes to be inserted for anybody, who installs the addon). If there are more of these, they are inserted progressively, the order cannot be relied upon.
Codes entered via API. Each addon can insert only one code into each location. If there are more of these addons, the codes will be inserted progressively, one after another, the order cannot be relied upon.
The code entered in the administration GUI (
/admin/html-kody/,HTML codetab).
E-mail distribution lists
The functionality is subject to module activation Mass e-mailing within the e-shop. The addon using this endpoint must therefore have this module defined as dependency.
Measure units
Allows you to access the system measure unit. These units are convertible to each other and cannot be redefined or extended. For defining/extending your own units use Units in the Settings section.
Webhooks
API endpoints for webhook servicing. It offers the possibility to read, add, change and delete the registered webhooks. Furthermore, it offers a list of notifications about invoked webhooks and their status.
The webhooks are HTTP calls, which send HTTPs calls to registered subscribers if a specific event happens,
for example creating an order. Then the information, in JSON format, is delivered to the defined URL.
{
"eshopId": 222651,
"event": "order:create",
"eventCreated": "2019-01-08T15:13:39+0100",
"eventInstance": "2018000057"
}
The meaning of individual items:
eshopId- number of the e-shop, where the event happenedevent- event which invoked the call (see code list Webhook event types)eventCreated- accurate time, when the event happenedeventInstance- reference to a specified entity - according to the context, order number, invoice number, product GUID, etc.
For more information about the function of webhooks, see https://developers.shoptet.com/webhooks/.