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.

Basic principles

How to call API

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.

For Addons

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"
        }
    ]
}

For private API access (Premium)

You can create API access tokens simply in the eshop administration. Send them in the request header Shoptet-Private-API-Token.

You can automatically access all API endpoints.

Rate limiting

Rate limiting is only 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.

Locks

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.

API versioning

Current version of API: v1.0

The client must send a Content-Type header with value of application/vnd.shoptet.v1.0,

where v1.0 is the API version supported by the client. If there is any change in the API, then we are trying to make it

reverse compatible, therefore it is not necessary to regularly update your connection after each change in our interface.

The version is the same for all endpoints described here.

Server response format

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/vnd.shoptet.v1.0' \
   '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/vnd.shoptet.v1.0' \
   'https://api.myshoptet.com/api/eshop'

Example of response:


HTTP/2 200

date: Fri, 13 Jul 2018 15:57:29 GMT

content-type: application/vnd.shoptet.v1.0+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

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.

Status codes

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.

Paging

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.

Section on demand

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.

Translations

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).

Files

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.

Product images

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.

Code lists

Image cuts

ValueDescription
origoriginal image (in the original resolution)
bigbig image (typically 1024x768 px)
detailimage detail (typically 360x270 px)
categorysize for listing in category (typically 216x105 px)

Product visibility

ValueDescription
hiddenHide product
visibleShow product
blockedCannot be ordered
show-registeredShow only to logged-in users
block-unregisteredDo not allow order to logged-out users
cash-desk-onlyShow only in cash desk
detail-onlyDo not show e-shop navigation

Product types

ValueDescription
productProduct
bazarSecond-hand product
serviceService
gift-certificateGift (deprecated)
product-setProduct set

Types of order items

ValueDescription
productProduct
bazarSecond-hand product
serviceService
shippingTransportation
billingPayment method
discount-couponDiscount coupon
volume-discountVolume discount
giftGift
gift-certificateGift certificate
generic-itemNon-specific item
product-setProduct set
product-set-itemProduct set item
depositDeposit

Sorting of products in category

ValueDescription
defaultDefault
most-sellingMost selling first
cheapestCheapest first
most-expensiveMost expensive first
oldestOldest first
newestNewest first
alphabeticallyAlphabetically
alphabetically-descAlphabetically, descending
product-codePer product code
product-code-descPer product code, descending
category-priorityCategory priority
category-priority-descCategory priority, descending

Webhook event types

ValueDescriptionIdentifier meaning
brand:createBrand creation eventString (code) - brand unique code
brand:updateBrand change eventString (code) - brand unique code
brand:deleteBrand deleting eventString (code) - brand unique code
creditNote:createCredit note creation eventNumber (code) of credit note
creditNote:deleteCredit note deleting eventNumber (code) of credit note
creditNote:updateCredit note change eventNumber (code) of credit note
customer:createNew customer was createdCustomer GUID
customer:updateCustomer was updated. Throws 409 Conflict when try to register simultaneously with customer:disableOrders or customer:enableOrdersCustomer GUID
customer:disableOrdersAn event disabled the customer, and his future orders will be automatically cancelled. Throws 409 Conflict when try to register simultaneously with customer:updateCustomer GUID
customer:enableOrdersAn event enabled the customer's future orders. Throws 409 Conflict when try to register simultaneously with customer:updateCustomer GUID
customer:importImport of 1 and more customers was executedFixed string "customers"
customer:deleteCustomer was deletedCustomer GUID
deliveryNote:createDelivery note creation eventNumber (code) of delivery note
deliveryNote:deleteDelivery note deleting eventNumber (code) of delivery note
deliveryNote:updateDelivery note change eventNumber (code) of delivery note
eshop:currenciesCurrencies settings change eventID of eshop
eshop:billingInformationBilling information (i.e. eshop billing address) change eventID of eshop
eshop:designDesign settings (template, colors, fonts, layout)ID of eshop
eshop:mandatoryFieldsMandatory fields of customer were updatedID of eshop
eshop:projectDomainDomain of eshop was changedID of eshop
invoice:createInvoice creation eventNumber (code) of invoice
invoice:deleteInvoice deleting eventNumber (code) of invoice
invoice:updateInvoice change eventNumber (code) of invoice
job:finishedThe asynchronous request was finishedJob id
mailingListEmail:createE-mail addition event into the e-mail distribution listName (code) of e-mail distribution list
mailingListEmail:deleteE-mail deleting event from the e-mail distribution listName (code) of e-mail distribution
order:cancelOrder cancel event. Webhook is emitted when order status is set to canceled. Throws 409 Conflict when try to register simultaneously with order:updateNumber (code) of order
order:createOrder creation eventNumber (code) of order
order:deleteOrder deleting eventNumber (code) of order
order:updateOrder change event. Throws 409 Conflict when try to register simultaneously with order:cancelNumber (code) of order
orderStatusesList:changeOrder status list change event. Emitted when order status is created, updated or deletedOrder status ID
paymentMethod:changePayment method change eventPayment method GUID
proformaInvoice:createProforma invoice creation eventNumber (code) of proforma invoice
proformaInvoice:deleteProforma invoice deleting eventNumber (code) of proforma invoice
proformaInvoice:updateProforma invoice change eventNumber (code) of proforma invoice
proofPayment:createProof of payment creation eventNumber (code) of proof payment
proofPayment:deleteProof of payment deleting eventNumber (code) of proof payment
proofPayment:updateProof of payment change eventNumber (code) of proof payment
shippingMethod:changeShipping method change eventShipping method GUID
shippingRequest:cancelledShipping request was not chosen for order deliveryshippingRequestCode associated with the cart
shippingRequest:confirmedShipping request was chosen for order deliveryshippingRequestCode associated with the cart
stock:movementStock change eventStock 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

Mass Webhooks

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

ValueDescriptionIdentifier meaning
invoice:massUpdateMass change of invoices eventJson serialized list of number (code) of invoices
order:massUpdateMass change of orders eventJson serialized list of number (code) of orders

System Webhooks

These webhooks cannot be registered via API, they are setup in Partners' Addon administration section instead.

ValueDescription
addon:suspendThe addon was suspended by the eshop or by Shoptet operations staff
addon:approveThe addon was approved (resumed) after it was suspended
addon:terminateThe addon was terminated by the eshop or by Shoptet operations staff
addon:uninstallThe addon was uninstalled by the eshop admin or the eshop was terminated

URL address from endpoint Eshop info

See endpoint Eshop info

IdentDescription
admin-orders-listListing of orders in administration
admin-customers-listList of customers in administration
oauthOAuth server address, used for e-shop user verification

List of product catalogues

Provider (identification)Description
glamiGlami
googleGoogle
heurekaHeuréka
zboziZboží.cz

Invoice Billing Methods

idDescription
1COD (cz: Dobírka)
2Wire transfer (cz: Převodem)
3Cash (cz: Hotově)
4Card (cz: Kartou)

VAT modes

Value
Normal
One Stop Shop
Mini One Stop Shop
Reverse charge
Outside the EU

Postman collection

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

Fork Shoptet API Collection from Shoptet Public API Workspace (recommended)

Also check postman documentation for more details: Fork a collection.

Step 1: Navigate to Shoptet Public API Workspace

  • Launch Postman on your desktop or in the browser.

  • In the search bar in the top header of app, type Shoptet Public API and select collection from Shoptet public API Workspace.

Step 2: Locate the Shoptet API Collection

  • Once inside the Shoptet Public API Workspace, go to the Collections tab.

  • Find the Shoptet API collection.

Step 3: Fork the 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 collection to get notified about changes in the original collection.

  • Click Fork Collection.

Step 4: Access Your Forked 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.

Import openapi.yaml into Postman as a Collection

Step 1: Upload the openapi.yaml File

  • 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.yaml file into the window, or click Upload Files and browse to the file's location.

Step 2: Verify OpenAPI Import

  • Postman will automatically recognize the OpenAPI schema.

  • It will display a preview of the API schema.

Step 3: Import as Collection

  • 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.yaml file.

Step 4: Access the Imported Collection

  • 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!

Collection settings

  1. Click the Shoptet API collection name.

  2. Go to Authorization tab.

  3. Set your access token into the value of Shoptet-Access-Token key.

  4. Go to Variables tab.

  5. You can set baseUrl variable here.

Last changes

Last API changes are published on the [API news] page (https://developers.shoptet.com/category/api/).

Download OpenAPI description
Languages
Servers
https://api.myshoptet.com/

Eshop

This endpoint is used for general information about the e-shop settings.

Operations

Products

Product endpoints are used for managing products in the e-shop and also for its related modules.

Operations

Price lists

Price lists are used for setting up different prices for products for different customer groups.

Operations

Orders

Order endpoints are used for managing orders in the e-shop.

Operations

Invoices

Invoice endpoints are used for managing invoices in the e-shop.

Operations

Proforma invoices

Proforma invoice endpoints are used for managing proforma invoices in the e-shop.

The code (code) is the proforma invoice identifier. Although this is usually a number, it is necessary to take into account that this might also include

letters, a dash, etc.

Operations

Credit notes

Credit note endpoints are used for managing credit notes in the e-shop.

The code (code) is the credit note identifier. Although this is usually a number, it is necessary to take into account that this might also include

letters, a dash, etc.

Operations

List of credit notes

Request

The list of credit notes supports paging

Query
isValidboolean

filtering according to document validity. Optional.

invoiceCodestring

filtering according to number of invoice. Optional.

creationTimeFromstring

date of credit note creation, in ISO 8601 format, lower limit. Optional.

Example: creationTimeFrom=2017-02-28T17:04:47+0100
creationTimeTostring

date of credit note creation, in ISO 8601 format, upper limit. Optional.

Example: creationTimeTo=2028-02-28T17:04:47+0100
varSymbolstring

filtering according to variable symbol of credit note

proofPaymentCodestring

filtering according to proof payment code. Optional.

Headers
Content-Typestringrequired
Default application/vnd.shoptet.v1.0
curl -i -X GET \
  'https://api.myshoptet.com/api/credit-notes?creationTimeFrom=string&creationTimeTo=string&invoiceCode=string&isValid=true&proofPaymentCode=string&varSymbol=string' \
  -H 'Content-Type: application/vnd.shoptet.v1.0' \
  -H 'Shoptet-Access-Token: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/vnd.shoptet.v1.0+json; charset=utf-8
dataobjectrequired
data.​creditNotesArray of objectsrequired
data.​creditNotes[].​codestringrequired

credit note number. Caution! This does not have to be just a number, it can also contain letters, a dash, etc.

data.​creditNotes[].​varSymbolnumber or nullrequired
data.​creditNotes[].​isValidbooleanrequired

is the credit note valid?

data.​creditNotes[].​invoiceCodestring or nullrequired

invoice number (can be null). Caution! This does not have to be just a number, it can also contain letters, a dash, etc.

data.​creditNotes[].​proofPaymentCodestring or nullrequired

proof payment code (can be null). Caution! This does not have to be just a number, it can also contain letters, a dash, etc.

data.​creditNotes[].​orderCodestring or nullrequired

purchase order number (can be null). Caution! This does not have to be just a number, it can also contain letters, a dash, etc.

data.​creditNotes[].​creationTimestring or null(typeDateTime)^[0-9]{4}-[01][0-9]-[0123][0-9]T[012][0-9]:[0...required

date of issue, in ISO 8601 format

data.​creditNotes[].​billCompanystring or nullrequired

name of the company (can be null)

data.​creditNotes[].​billFullNamestring or nullrequired

full name of the customer (can be null)

data.​creditNotes[].​priceobject(price)required

price informations

data.​creditNotes[].​price.​vatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

VAT value, two decimal places

data.​creditNotes[].​price.​toPaystring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

total price to pay

data.​creditNotes[].​price.​currencyCodestring(typeCurrencyCode)^[a-zA-Z]{3}$required

currency code. List of available currencies within the e-shop can be found in endpoint GET /api/eshop.

data.​creditNotes[].​price.​withoutVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price excluding tax

data.​creditNotes[].​price.​withVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price including tax

data.​creditNotes[].​price.​exchangeRatestring(typeExchangeRate)^[0-9]+\.[0-9]{8}$required

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!

data.​creditNotes[].​price.​partialPaymentAmountstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$

can be value expressed in percents or as exact money value expression (with up to two decimal places) - depends on partialPaymentType value

data.​creditNotes[].​price.​partialPaymentTypestring

'percents' = partial payment as percentage from total price | 'absolute' = exact expression of partial payment in money

data.​creditNotes[].​changeTimestring or null(typeDateTime)^[0-9]{4}-[01][0-9]-[0123][0-9]T[012][0-9]:[0...required

date of last change, in ISO 8601 format

data.​paginatorobject(paginator)required
data.​paginator.​totalCountintegerrequired

total number of available records

data.​paginator.​pageintegerrequired

current page

data.​paginator.​pageCountintegerrequired

total available of pages

data.​paginator.​itemsOnPageintegerrequired

number of currently returned records

data.​paginator.​itemsPerPageintegerrequired

required number of records per page

errorsArray of objects or null(Errors)required
errors[].​errorCodestringrequired

Short text error identification

errors[].​messagestringrequired

Descriptive error message

errors[].​instancestringrequired

Identification of the entity referenced

Response
application/vnd.shoptet.v1.0+json; charset=utf-8
{ "data": { "creditNotes": [], "paginator": {} }, "errors": [ {} ] }

List of all credit notes

Request

Additional information about one credit notes.

This endpoint has several sections, which are only sent when requested in the include parameter (see Requested sections).

ValueSection
surchargeParametersItem surcharge parameters
Query
creationTimeFromstring

Export credit notes created after date

Example: creationTimeFrom=2014-09-05T00:00:00%2B0000
creationTimeTostring

Export credit notes created before date

Example: creationTimeTo=2019-09-05T00:00:00%2B0000
changeTimeFromstring

Export credit notes updated after date

Example: changeTimeFrom=2014-09-05T00:00:00%2B0000
changeTimeTostring

Export credit notes updated before date

Example: changeTimeTo=2019-09-05T00:00:00%2B0000
codeFromstring

Export credit notes with code after given value

Example: codeFrom=0000000006
codeTostring

Export credit notes with code before given value

Example: codeTo=0000000006
invoiceCodeFromstring

Export credit notes with invoice code after given value

Example: invoiceCodeFrom=2017000010
invoiceCodeTostring

Export credit notes with invoice code before given value

Example: invoiceCodeTo=2017000010
dueDateFromstring

Export credit notes with due date after date

Example: dueDateFrom=2014-09-05T00:00:00%2B0000
dueDateTostring

Export credit notes with due date before date

Example: dueDateTo=2019-09-05T00:00:00%2B0000
hasProofPaymentCodeboolean

Export credit notes with or without proof payment codes only

Example: hasProofPaymentCode=true
taxDateFromstring

Export credit notes with tax date after date

Example: taxDateFrom=2014-09-05T00:00:00%2B0000
taxDateTostring

Export credit notes with tax date before date

Example: taxDateTo=2019-09-05T00:00:00%2B0000
orderCodeFromstring

Export credit notes with order code after given value

Example: orderCodeFrom=2017000010
orderCodeTostring

Export credit notes with order code before given value

Example: orderCodeTo=2017000010
customerGuidstring

Export credit notes with given customer

Example: customerGuid=443cad54-73bc-11e8-8216-002590dad85e
varSymbolstring

Export credit notes with given variable symbol

Example: varSymbol=2010001
restockedboolean

Export restocked or not restocked credit notes

Example: restocked=false
isValidboolean

Filtering according to document validity

Example: isValid=true
includestring

Sections to include

Example: include=surchargeParameters
Headers
Content-Typestringrequired
Default application/vnd.shoptet.v1.0
curl -i -X GET \
  'https://api.myshoptet.com/api/credit-notes/snapshot?changeTimeFrom=string&changeTimeTo=string&codeFrom=string&codeTo=string&creationTimeFrom=string&creationTimeTo=string&customerGuid=string&dueDateFrom=string&dueDateTo=string&hasProofPaymentCode=true&include=string&invoiceCodeFrom=string&invoiceCodeTo=string&isValid=true&orderCodeFrom=string&orderCodeTo=string&restocked=true&taxDateFrom=string&taxDateTo=string&varSymbol=string' \
  -H 'Content-Type: application/vnd.shoptet.v1.0' \
  -H 'Shoptet-Access-Token: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/vnd.shoptet.v1.0+json; charset=utf-8
dataobject
errorsArray of objects or null(Errors)
Response
application/vnd.shoptet.v1.0+json; charset=utf-8
{ "data": { "jobId": "ad24xod" }, "errors": [ {} ] }

Credit note detail

Request

Additional information about one credit note.

This endpoint has several sections, which are only sent when requested in the include parameter (see Requested sections).

ValueSection
surchargeParametersItem surcharge parameters
Path
codestringrequired
Example: 0000000002
Query
includestring

Sections to include

Example: include=surchargeParameters
Headers
Content-Typestringrequired
Default application/vnd.shoptet.v1.0
curl -i -X GET \
  'https://api.myshoptet.com/api/credit-notes/{code}?include=string' \
  -H 'Content-Type: application/vnd.shoptet.v1.0' \
  -H 'Shoptet-Access-Token: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/vnd.shoptet.v1.0+json; charset=utf-8
dataobjectrequired
data.​creditNoteobjectrequired
data.​creditNote.​codestringrequired

variant code (product) (can be null)

data.​creditNote.​isValidbooleanrequired

is the credit note valid?

data.​creditNote.​invoiceCodestring or nullrequired

invoice number (can be null). Caution! This does not have to be just a number, it can also contain letters, a dash, etc.

data.​creditNote.​orderCodestring or nullrequired

purchase order number (can be null). Caution! This does not have to be just a number, it can also contain letters, a dash, etc.

data.​creditNote.​proofPaymentCodestring or nullrequired

proof payment code (can be null). Caution! This does not have to be just a number, it can also contain letters, a dash, etc.

data.​creditNote.​creationTimestring or null(typeDateTime)^[0-9]{4}-[01][0-9]-[0123][0-9]T[012][0-9]:[0...required

date of issue, in ISO 8601 format

data.​creditNote.​changeTimestring or null(typeDateTime)^[0-9]{4}-[01][0-9]-[0123][0-9]T[012][0-9]:[0...required

date of change, in ISO 8601 format

data.​creditNote.​dueDatestring or null(date)(typeDate)^[0-9]{4}-[0-9]{2}-[0-9]{2}$required

due date in ISO 8601 format (can be null)

data.​creditNote.​taxDatestring or null(date)(typeDate)^[0-9]{4}-[0-9]{2}-[0-9]{2}$required

taxation date in ISO 8601 format (can be null)

data.​creditNote.​varSymbolnumberrequired

variable symbol

data.​creditNote.​constSymbolinteger or nullrequired

constant symbol (can be null)

data.​creditNote.​specSymbolnumber or nullrequired

specific symbol (can be null)

data.​creditNote.​restockedboolean

Items in credit note were restocked?

data.​creditNote.​stockAmountChangeTypestring or nullrequired

type of change in stock quantity (can be null)

data.​creditNote.​weightstring(typeWeightUnlimited)^[0-9]+\.[0-9]{3}$required

weight in kg, unpacked, 3 decimal places. Maximum value 999999.

data.​creditNote.​completePackageWeightstring(typeWeightUnlimited)^[0-9]+\.[0-9]{3}$required

weight in kg, unpacked, 3 decimal places. Maximum value 999999.

data.​creditNote.​billingMethodbillingMethod (object) or nullrequired

information about the method of payment (can be null)

One of:

information about the method of payment (can be null)

data.​creditNote.​billingMethod.​idintegerrequired

unique identifier of billing method

data.​creditNote.​billingMethod.​namestringrequired
data.​creditNote.​billingAddressobject(billingAddress)required

invoicing address

data.​creditNote.​billingAddress.​companystring or nullrequired

name of purchaser''s company (or null)

data.​creditNote.​billingAddress.​fullNamestring or nullrequired

name of purchaser (or null)

data.​creditNote.​billingAddress.​streetstring or nullrequired

street of purchaser (or null)

data.​creditNote.​billingAddress.​houseNumberstring or nullrequired

street number (or null)

data.​creditNote.​billingAddress.​citystring or nullrequired

city/town (village) (or null)

data.​creditNote.​billingAddress.​districtstring or nullrequired

county (or null)

data.​creditNote.​billingAddress.​additionalstring or nullrequired

additional address information (or null)

data.​creditNote.​billingAddress.​zipstring or nullrequired

ZIP or postal code (or null)

data.​creditNote.​billingAddress.​countryCodestring or nullrequired

tree-character ISO country code (ISO 4217)

data.​creditNote.​billingAddress.​regionNamestring or nullrequired

region name (or null)

data.​creditNote.​billingAddress.​regionShortcutstring or nullrequired

region abbreviation (or null)

data.​creditNote.​billingAddress.​companyIdstring or nullrequired

Company registration number. (can be null)

data.​creditNote.​billingAddress.​vatIdstring or nullrequired

VAT identification number. (can be null)

data.​creditNote.​billingAddress.​vatIdValidationStatusany

Info, whether VAT ID has been verified, enum [unverified, verified, waiting]

Enum"unverified""verified""waiting"null
data.​creditNote.​billingAddress.​taxIdstring or nullrequired

TAX identification number. For Czech address, taxId is same as vatId. (can be null)

data.​creditNote.​deliveryAddressobject(address)required

delivery address (can be null)

data.​creditNote.​deliveryAddress.​companystring or nullrequired

name of purchaser''s company (or null)

data.​creditNote.​deliveryAddress.​fullNamestring or nullrequired

name of purchaser (or null)

data.​creditNote.​deliveryAddress.​streetstring or nullrequired

street of purchaser (or null)

data.​creditNote.​deliveryAddress.​houseNumberstring or nullrequired

street number (or null)

data.​creditNote.​deliveryAddress.​citystring or nullrequired

city/town (village) (or null)

data.​creditNote.​deliveryAddress.​districtstring or nullrequired

county (or null)

data.​creditNote.​deliveryAddress.​additionalstring or nullrequired

additional address information (or null)

data.​creditNote.​deliveryAddress.​zipstring or nullrequired

ZIP or postal code (or null)

data.​creditNote.​deliveryAddress.​countryCodestring or nullrequired

tree-character ISO country code (ISO 4217)

data.​creditNote.​deliveryAddress.​regionNamestring or nullrequired

region name (or null)

data.​creditNote.​deliveryAddress.​regionShortcutstring or nullrequired

region abbreviation (or null)

data.​creditNote.​addressesEqualbooleanrequired

Are delivery and invoicing address the same?

data.​creditNote.​priceobject(price)required
data.​creditNote.​price.​vatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

VAT value, two decimal places

data.​creditNote.​price.​toPaystring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

total price to pay

data.​creditNote.​price.​currencyCodestring(typeCurrencyCode)^[a-zA-Z]{3}$required

currency code. List of available currencies within the e-shop can be found in endpoint GET /api/eshop.

data.​creditNote.​price.​withoutVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price excluding tax

data.​creditNote.​price.​withVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price including tax

data.​creditNote.​price.​exchangeRatestring(typeExchangeRate)^[0-9]+\.[0-9]{8}$required

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!

data.​creditNote.​price.​partialPaymentAmountstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$

can be value expressed in percents or as exact money value expression (with up to two decimal places) - depends on partialPaymentType value

data.​creditNote.​price.​partialPaymentTypestring

'percents' = partial payment as percentage from total price | 'absolute' = exact expression of partial payment in money

data.​creditNote.​customerobject(documentCustomer)required
data.​creditNote.​customer.​guidstring(typeGuidUnlimited)<= 36 charactersrequired

customer identifier (can be null)

data.​creditNote.​customer.​phonestring or nullrequired

customer phone (can be null)

data.​creditNote.​customer.​emailstring or nullrequired

customer e-mail (can be null)

data.​creditNote.​customer.​remarkstring or nullrequired

remark for the customer (can be null)

data.​creditNote.​eshopobject(eshop)required
data.​creditNote.​eshop.​bankAccountstring or nullrequired

e-shop bank account (can be null)

data.​creditNote.​eshop.​ibanstring or nullrequired

e-shop IBAN (can be null)

data.​creditNote.​eshop.​bicstring or nullrequired

bank code - SWIFT (can be null)

data.​creditNote.​eshop.​vatPayerbooleanrequired

VAT payer (can be null)

data.​creditNote.​itemsArray of objects(documentItemsWithPrice)required
data.​creditNote.​items[].​productGuidstring(typeGuidUnlimited)<= 36 charactersrequired

global unique permanent product identifier (can be null)

data.​creditNote.​items[].​codestring or nullrequired

variant code (product) (can be null)

data.​creditNote.​items[].​itemTypestringrequired

item type

data.​creditNote.​items[].​namestring or nullrequired

product name (can be null)

data.​creditNote.​items[].​variantNamestring or nullrequired

variant name (can be null)

data.​creditNote.​items[].​brandstring or nullrequired

brand name (can be null)

data.​creditNote.​items[].​amountstring or null(typeAmount)^(-)?[0-9]+\.[0-9]{3}$required

quantity

data.​creditNote.​items[].​amountUnitstring or nullrequired

unit of quantity (can be null)

data.​creditNote.​items[].​remarkstring or nullrequired

remark (can be null)

data.​creditNote.​items[].​priceRatiostring(typePriceRatio)[0-9]+\.[0-9]{4}$required

discount - 0.7800 = discount 22%; 1.0000 = no discount

data.​creditNote.​items[].​weightstring(typeWeight)^[0-9]{1,6}\.[0-9]{3}$required

weight in kg, unpacked (can be null). 3 decimal places. Maximum value 999999.

data.​creditNote.​items[].​additionalFieldstring or nullrequired

additional info (can be null)

data.​creditNote.​items[].​itemPriceobject(itemPrice)required

item price

data.​creditNote.​items[].​itemPrice.​withVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price including tax

data.​creditNote.​items[].​itemPrice.​withoutVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price excluding tax

data.​creditNote.​items[].​itemPrice.​vatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

VAT value, two decimal places

data.​creditNote.​items[].​itemPrice.​vatRatestring(typeVatRate)^[0-9]+\.[0-9]{2}$required

VAT rate

data.​creditNote.​items[].​buyPriceobject(itemPrice)required

purchase price of the part, can be null.

data.​creditNote.​items[].​buyPrice.​withVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price including tax

data.​creditNote.​items[].​buyPrice.​withoutVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price excluding tax

data.​creditNote.​items[].​buyPrice.​vatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

VAT value, two decimal places

data.​creditNote.​items[].​buyPrice.​vatRatestring(typeVatRate)^[0-9]+\.[0-9]{2}$required

VAT rate

data.​creditNote.​items[].​displayPricesArray of objects(itemPrice)

in some cases, one item is displayed as multiple lines in the administration or a printout. This array contains one or more rows representing the printout version of the item.

data.​creditNote.​items[].​itemIdnumberrequired

item identifier for manipulation with this item

data.​creditNote.​items[].​surchargeParametersArray of objects(itemSurchargeParameters)
data.​creditNote.​items[].​specificSurchargeParametersArray of objects(itemSpecificSurchargeParameters)
data.​creditNote.​documentRemarkstring or nullrequired

remark on the document (can be null)

data.​creditNote.​vatPayerbooleanrequired

is the tradesman a VAT payer? (can be null)

data.​creditNote.​vatModestring or null

VAT mode, can be null, possible values: Normal, One Stop Shop, Mini One Stop Shop, Reverse charge, Outside the EU

errorsArray of objects or null(Errors)required
errors[].​errorCodestringrequired

Short text error identification

errors[].​messagestringrequired

Descriptive error message

errors[].​instancestringrequired

Identification of the entity referenced

Response
application/vnd.shoptet.v1.0+json; charset=utf-8
{ "data": { "creditNote": {} }, "errors": [ {} ] }

Credit note update

Request

Path
codestringrequired
Example: 0000000002
Headers
Content-Typestringrequired
Default application/vnd.shoptet.v1.0
Bodyapplication/vnd.shoptet.v1.0+json
dataobjectnon-emptyrequired
data.​varSymbolnumber[ 0 .. 9999999999 ]

Variable symbol. Optional, generated by eshop settings if not set.

data.​dueDatestring or null(date)(typeDate)^[0-9]{4}-[0-9]{2}-[0-9]{2}$

Due date. Optional, generated by eshop settings if not set.

data.​taxDatestring or null(date)(typeDate)^[0-9]{4}-[0-9]{2}-[0-9]{2}$

Date of taxation. Default is today.

data.​constSymbolstring(typeConstSymbol)^[0-9]{1,4}$

Const symbol. Only numbers are allowed (max length 4).

data.​specSymbolnumber or null[ 0 .. 9999999999 ]

Specific symbol.

data.​billingMethodIdnumber
data.​orderCodestring or null[ 1 .. 10 ] characters

Order code. Optional.

curl -i -X PATCH \
  'https://api.myshoptet.com/api/credit-notes/{code}' \
  -H 'Content-Type: application/vnd.shoptet.v1.0+json' \
  -H 'Shoptet-Access-Token: YOUR_API_KEY_HERE' \
  -d '{
    "data": {
      "varSymbol": 99,
      "dueDate": "2017-04-04",
      "taxDate": "2017-04-04",
      "constSymbol": "0308",
      "specSymbol": 201323134,
      "billingMethodId": 1,
      "orderCode": "201323134"
    }
  }'

Responses

Created

Bodyapplication/vnd.shoptet.v1.0+json; charset=utf-8
dataobjectrequired
data.​creditNoteobjectrequired
data.​creditNote.​codestringrequired

variant code (product) (can be null)

data.​creditNote.​isValidbooleanrequired

is the credit note valid?

data.​creditNote.​invoiceCodestring or nullrequired

invoice number (can be null). Caution! This does not have to be just a number, it can also contain letters, a dash, etc.

data.​creditNote.​orderCodestring or nullrequired

purchase order number (can be null). Caution! This does not have to be just a number, it can also contain letters, a dash, etc.

data.​creditNote.​proofPaymentCodestring or nullrequired

proof payment code (can be null). Caution! This does not have to be just a number, it can also contain letters, a dash, etc.

data.​creditNote.​creationTimestring or null(typeDateTime)^[0-9]{4}-[01][0-9]-[0123][0-9]T[012][0-9]:[0...required

date of issue, in ISO 8601 format

data.​creditNote.​changeTimestring or null(typeDateTime)^[0-9]{4}-[01][0-9]-[0123][0-9]T[012][0-9]:[0...required

date of change, in ISO 8601 format

data.​creditNote.​dueDatestring or null(date)(typeDate)^[0-9]{4}-[0-9]{2}-[0-9]{2}$required

due date in ISO 8601 format (can be null)

data.​creditNote.​taxDatestring or null(date)(typeDate)^[0-9]{4}-[0-9]{2}-[0-9]{2}$required

taxation date in ISO 8601 format (can be null)

data.​creditNote.​varSymbolnumberrequired

variable symbol

data.​creditNote.​constSymbolinteger or nullrequired

constant symbol (can be null)

data.​creditNote.​specSymbolnumber or nullrequired

specific symbol (can be null)

data.​creditNote.​restockedboolean

Items in credit note were restocked?

data.​creditNote.​stockAmountChangeTypestring or nullrequired

type of change in stock quantity (can be null)

data.​creditNote.​weightstring(typeWeightUnlimited)^[0-9]+\.[0-9]{3}$required

weight in kg, unpacked, 3 decimal places. Maximum value 999999.

data.​creditNote.​completePackageWeightstring(typeWeightUnlimited)^[0-9]+\.[0-9]{3}$required

weight in kg, unpacked, 3 decimal places. Maximum value 999999.

data.​creditNote.​billingMethodbillingMethod (object) or nullrequired

information about the method of payment (can be null)

One of:

information about the method of payment (can be null)

data.​creditNote.​billingMethod.​idintegerrequired

unique identifier of billing method

data.​creditNote.​billingMethod.​namestringrequired
data.​creditNote.​billingAddressobject(billingAddress)required

invoicing address

data.​creditNote.​billingAddress.​companystring or nullrequired

name of purchaser''s company (or null)

data.​creditNote.​billingAddress.​fullNamestring or nullrequired

name of purchaser (or null)

data.​creditNote.​billingAddress.​streetstring or nullrequired

street of purchaser (or null)

data.​creditNote.​billingAddress.​houseNumberstring or nullrequired

street number (or null)

data.​creditNote.​billingAddress.​citystring or nullrequired

city/town (village) (or null)

data.​creditNote.​billingAddress.​districtstring or nullrequired

county (or null)

data.​creditNote.​billingAddress.​additionalstring or nullrequired

additional address information (or null)

data.​creditNote.​billingAddress.​zipstring or nullrequired

ZIP or postal code (or null)

data.​creditNote.​billingAddress.​countryCodestring or nullrequired

tree-character ISO country code (ISO 4217)

data.​creditNote.​billingAddress.​regionNamestring or nullrequired

region name (or null)

data.​creditNote.​billingAddress.​regionShortcutstring or nullrequired

region abbreviation (or null)

data.​creditNote.​billingAddress.​companyIdstring or nullrequired

Company registration number. (can be null)

data.​creditNote.​billingAddress.​vatIdstring or nullrequired

VAT identification number. (can be null)

data.​creditNote.​billingAddress.​vatIdValidationStatusany

Info, whether VAT ID has been verified, enum [unverified, verified, waiting]

Enum"unverified""verified""waiting"null
data.​creditNote.​billingAddress.​taxIdstring or nullrequired

TAX identification number. For Czech address, taxId is same as vatId. (can be null)

data.​creditNote.​deliveryAddressobject(address)required

delivery address (can be null)

data.​creditNote.​deliveryAddress.​companystring or nullrequired

name of purchaser''s company (or null)

data.​creditNote.​deliveryAddress.​fullNamestring or nullrequired

name of purchaser (or null)

data.​creditNote.​deliveryAddress.​streetstring or nullrequired

street of purchaser (or null)

data.​creditNote.​deliveryAddress.​houseNumberstring or nullrequired

street number (or null)

data.​creditNote.​deliveryAddress.​citystring or nullrequired

city/town (village) (or null)

data.​creditNote.​deliveryAddress.​districtstring or nullrequired

county (or null)

data.​creditNote.​deliveryAddress.​additionalstring or nullrequired

additional address information (or null)

data.​creditNote.​deliveryAddress.​zipstring or nullrequired

ZIP or postal code (or null)

data.​creditNote.​deliveryAddress.​countryCodestring or nullrequired

tree-character ISO country code (ISO 4217)

data.​creditNote.​deliveryAddress.​regionNamestring or nullrequired

region name (or null)

data.​creditNote.​deliveryAddress.​regionShortcutstring or nullrequired

region abbreviation (or null)

data.​creditNote.​addressesEqualbooleanrequired

Are delivery and invoicing address the same?

data.​creditNote.​priceobject(price)required
data.​creditNote.​price.​vatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

VAT value, two decimal places

data.​creditNote.​price.​toPaystring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

total price to pay

data.​creditNote.​price.​currencyCodestring(typeCurrencyCode)^[a-zA-Z]{3}$required

currency code. List of available currencies within the e-shop can be found in endpoint GET /api/eshop.

data.​creditNote.​price.​withoutVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price excluding tax

data.​creditNote.​price.​withVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price including tax

data.​creditNote.​price.​exchangeRatestring(typeExchangeRate)^[0-9]+\.[0-9]{8}$required

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!

data.​creditNote.​price.​partialPaymentAmountstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$

can be value expressed in percents or as exact money value expression (with up to two decimal places) - depends on partialPaymentType value

data.​creditNote.​price.​partialPaymentTypestring

'percents' = partial payment as percentage from total price | 'absolute' = exact expression of partial payment in money

data.​creditNote.​customerobject(documentCustomer)required
data.​creditNote.​customer.​guidstring(typeGuidUnlimited)<= 36 charactersrequired

customer identifier (can be null)

data.​creditNote.​customer.​phonestring or nullrequired

customer phone (can be null)

data.​creditNote.​customer.​emailstring or nullrequired

customer e-mail (can be null)

data.​creditNote.​customer.​remarkstring or nullrequired

remark for the customer (can be null)

data.​creditNote.​eshopobject(eshop)required
data.​creditNote.​eshop.​bankAccountstring or nullrequired

e-shop bank account (can be null)

data.​creditNote.​eshop.​ibanstring or nullrequired

e-shop IBAN (can be null)

data.​creditNote.​eshop.​bicstring or nullrequired

bank code - SWIFT (can be null)

data.​creditNote.​eshop.​vatPayerbooleanrequired

VAT payer (can be null)

data.​creditNote.​itemsArray of objects(documentItemsWithPrice)required
data.​creditNote.​items[].​productGuidstring(typeGuidUnlimited)<= 36 charactersrequired

global unique permanent product identifier (can be null)

data.​creditNote.​items[].​codestring or nullrequired

variant code (product) (can be null)

data.​creditNote.​items[].​itemTypestringrequired

item type

data.​creditNote.​items[].​namestring or nullrequired

product name (can be null)

data.​creditNote.​items[].​variantNamestring or nullrequired

variant name (can be null)

data.​creditNote.​items[].​brandstring or nullrequired

brand name (can be null)

data.​creditNote.​items[].​amountstring or null(typeAmount)^(-)?[0-9]+\.[0-9]{3}$required

quantity

data.​creditNote.​items[].​amountUnitstring or nullrequired

unit of quantity (can be null)

data.​creditNote.​items[].​remarkstring or nullrequired

remark (can be null)

data.​creditNote.​items[].​priceRatiostring(typePriceRatio)[0-9]+\.[0-9]{4}$required

discount - 0.7800 = discount 22%; 1.0000 = no discount

data.​creditNote.​items[].​weightstring(typeWeight)^[0-9]{1,6}\.[0-9]{3}$required

weight in kg, unpacked (can be null). 3 decimal places. Maximum value 999999.

data.​creditNote.​items[].​additionalFieldstring or nullrequired

additional info (can be null)

data.​creditNote.​items[].​itemPriceobject(itemPrice)required

item price

data.​creditNote.​items[].​itemPrice.​withVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price including tax

data.​creditNote.​items[].​itemPrice.​withoutVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price excluding tax

data.​creditNote.​items[].​itemPrice.​vatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

VAT value, two decimal places

data.​creditNote.​items[].​itemPrice.​vatRatestring(typeVatRate)^[0-9]+\.[0-9]{2}$required

VAT rate

data.​creditNote.​items[].​buyPriceobject(itemPrice)required

purchase price of the part, can be null.

data.​creditNote.​items[].​buyPrice.​withVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price including tax

data.​creditNote.​items[].​buyPrice.​withoutVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price excluding tax

data.​creditNote.​items[].​buyPrice.​vatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

VAT value, two decimal places

data.​creditNote.​items[].​buyPrice.​vatRatestring(typeVatRate)^[0-9]+\.[0-9]{2}$required

VAT rate

data.​creditNote.​items[].​displayPricesArray of objects(itemPrice)

in some cases, one item is displayed as multiple lines in the administration or a printout. This array contains one or more rows representing the printout version of the item.

data.​creditNote.​items[].​itemIdnumberrequired

item identifier for manipulation with this item

data.​creditNote.​items[].​surchargeParametersArray of objects(itemSurchargeParameters)
data.​creditNote.​items[].​specificSurchargeParametersArray of objects(itemSpecificSurchargeParameters)
data.​creditNote.​documentRemarkstring or nullrequired

remark on the document (can be null)

data.​creditNote.​vatPayerbooleanrequired

is the tradesman a VAT payer? (can be null)

data.​creditNote.​vatModestring or null

VAT mode, can be null, possible values: Normal, One Stop Shop, Mini One Stop Shop, Reverse charge, Outside the EU

errorsArray of objects or null(Errors)required
errors[].​errorCodestringrequired

Short text error identification

errors[].​messagestringrequired

Descriptive error message

errors[].​instancestringrequired

Identification of the entity referenced

Response
application/vnd.shoptet.v1.0+json; charset=utf-8
{ "data": { "creditNote": {} }, "errors": [ {} ] }

Credit note deletion

Request

Path
codestringrequired
Example: 0000000002
Headers
Content-Typestringrequired
Default application/vnd.shoptet.v1.0
curl -i -X DELETE \
  'https://api.myshoptet.com/api/credit-notes/{code}' \
  -H 'Content-Type: application/vnd.shoptet.v1.0' \
  -H 'Shoptet-Access-Token: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/vnd.shoptet.v1.0+json; charset=utf-8
datanullrequired
errorsArray of objects or null(Errors)required
errors[].​errorCodestringrequired

Short text error identification

errors[].​messagestringrequired

Descriptive error message

errors[].​instancestringrequired

Identification of the entity referenced

Response
application/vnd.shoptet.v1.0+json; charset=utf-8
{ "data": null, "errors": [ {} ] }

Credit note restock

Request

Restock items from credit note.

Path
codestringrequired
Example: 0000000002
Headers
Content-Typestringrequired
Default application/vnd.shoptet.v1.0
curl -i -X POST \
  'https://api.myshoptet.com/api/credit-notes/{code}/restock' \
  -H 'Content-Type: application/vnd.shoptet.v1.0' \
  -H 'Shoptet-Access-Token: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/vnd.shoptet.v1.0+json; charset=utf-8
dataobjectrequired
data.​notesArray of stringsrequired

Notes about no longer existing products which cannot be restocked. Messages are in administration language.

errorsArray of objects or null(Errors)required
errors[].​errorCodestringrequired

Short text error identification

errors[].​messagestringrequired

Descriptive error message

errors[].​instancestringrequired

Identification of the entity referenced

Response
application/vnd.shoptet.v1.0+json; charset=utf-8
{ "data": { "notes": [] }, "errors": [ {} ] }

Credit note from invoice creation

Request

Creating credit note from existing invoice.

This endpoint has several sections, which are only sent when requested in the include parameter (see Requested sections).

Value | Section

--------|------

surchargeParameters| Item surcharge parameters

It will create a credit note from the given invoice. It will automatically take all invoice items and add them to the credit note. If you want to add just some items from the invoice or different amount, use the parameter items. This parameter will allow you to generate credit note only with provided items.

Path
codestringrequired

Code of invoice

Example: 2018000004
Query
includestring

Sections to include

Example: include=surchargeParameters
Headers
Content-Typestringrequired
Default application/vnd.shoptet.v1.0
Bodyapplication/vnd.shoptet.v1.0+json
dataobjectrequired
data.​creditNoteCodestring

Credit nore code. Optional, generated by eshop settings if not set.

data.​varSymbolnumber[ 0 .. 9999999999 ]

Variable symbol. Optional, generated by eshop settings if not set.

data.​dueDatestring or null(date)(typeDate)^[0-9]{4}-[0-9]{2}-[0-9]{2}$

Due date. Optional, generated by eshop settings if not set.

data.​taxDatestring or null(date)(typeDate)^[0-9]{4}-[0-9]{2}-[0-9]{2}$

Date of taxation. Default is today.

data.​constSymbolstring(typeConstSymbol)^[0-9]{1,4}$

Const symbol. Only numbers are allowed (max length 4).

data.​specSymbolnumber[ 0 .. 9999999999 ]

Spec symbol.

data.​billingMethodIdnumber
data.​orderCodestring[ 1 .. 10 ] characters

Order Code. Optional.

data.​useItemIdsArray of arraysnon-empty

DEPRECATED - List of invoice item ids. Can be found in field data.invoice.items.itemId in Invoice detail.

data.​itemsArray of objectsnon-empty

List of invoice item ids and their amounts.

curl -i -X POST \
  'https://api.myshoptet.com/api/invoices/{code}/credit-note?include=string' \
  -H 'Content-Type: application/vnd.shoptet.v1.0+json' \
  -H 'Shoptet-Access-Token: YOUR_API_KEY_HERE' \
  -d '{
    "data": {
      "creditNoteCode": "0000000099",
      "varSymbol": 99,
      "dueDate": "2017-04-04",
      "taxDate": "2017-04-04",
      "constSymbol": "0308",
      "specSymbol": 201323134,
      "billingMethodId": 1,
      "orderCode": "201323134",
      "useItemIds": [],
      "items": [
        {
          "invoiceItemId": 231,
          "amount": "1.000"
        }
      ]
    }
  }'

Responses

Created

Bodyapplication/vnd.shoptet.v1.0+json; charset=utf-8
dataobjectrequired
data.​creditNoteobjectrequired
data.​creditNote.​codestringrequired

variant code (product) (can be null)

data.​creditNote.​isValidbooleanrequired

is the credit note valid?

data.​creditNote.​invoiceCodestring or nullrequired

invoice number (can be null). Caution! This does not have to be just a number, it can also contain letters, a dash, etc.

data.​creditNote.​orderCodestring or nullrequired

purchase order number (can be null). Caution! This does not have to be just a number, it can also contain letters, a dash, etc.

data.​creditNote.​proofPaymentCodestring or nullrequired

proof payment code (can be null). Caution! This does not have to be just a number, it can also contain letters, a dash, etc.

data.​creditNote.​creationTimestring or null(typeDateTime)^[0-9]{4}-[01][0-9]-[0123][0-9]T[012][0-9]:[0...required

date of issue, in ISO 8601 format

data.​creditNote.​changeTimestring or null(typeDateTime)^[0-9]{4}-[01][0-9]-[0123][0-9]T[012][0-9]:[0...required

date of change, in ISO 8601 format

data.​creditNote.​dueDatestring or null(date)(typeDate)^[0-9]{4}-[0-9]{2}-[0-9]{2}$required

due date in ISO 8601 format (can be null)

data.​creditNote.​taxDatestring or null(date)(typeDate)^[0-9]{4}-[0-9]{2}-[0-9]{2}$required

taxation date in ISO 8601 format (can be null)

data.​creditNote.​varSymbolnumberrequired

variable symbol

data.​creditNote.​constSymbolinteger or nullrequired

constant symbol (can be null)

data.​creditNote.​specSymbolnumber or nullrequired

specific symbol (can be null)

data.​creditNote.​restockedboolean

Items in credit note were restocked?

data.​creditNote.​stockAmountChangeTypestring or nullrequired

type of change in stock quantity (can be null)

data.​creditNote.​weightstring(typeWeightUnlimited)^[0-9]+\.[0-9]{3}$required

weight in kg, unpacked, 3 decimal places. Maximum value 999999.

data.​creditNote.​completePackageWeightstring(typeWeightUnlimited)^[0-9]+\.[0-9]{3}$required

weight in kg, unpacked, 3 decimal places. Maximum value 999999.

data.​creditNote.​billingMethodbillingMethod (object) or nullrequired

information about the method of payment (can be null)

One of:

information about the method of payment (can be null)

data.​creditNote.​billingMethod.​idintegerrequired

unique identifier of billing method

data.​creditNote.​billingMethod.​namestringrequired
data.​creditNote.​billingAddressobject(billingAddress)required

invoicing address

data.​creditNote.​billingAddress.​companystring or nullrequired

name of purchaser''s company (or null)

data.​creditNote.​billingAddress.​fullNamestring or nullrequired

name of purchaser (or null)

data.​creditNote.​billingAddress.​streetstring or nullrequired

street of purchaser (or null)

data.​creditNote.​billingAddress.​houseNumberstring or nullrequired

street number (or null)

data.​creditNote.​billingAddress.​citystring or nullrequired

city/town (village) (or null)

data.​creditNote.​billingAddress.​districtstring or nullrequired

county (or null)

data.​creditNote.​billingAddress.​additionalstring or nullrequired

additional address information (or null)

data.​creditNote.​billingAddress.​zipstring or nullrequired

ZIP or postal code (or null)

data.​creditNote.​billingAddress.​countryCodestring or nullrequired

tree-character ISO country code (ISO 4217)

data.​creditNote.​billingAddress.​regionNamestring or nullrequired

region name (or null)

data.​creditNote.​billingAddress.​regionShortcutstring or nullrequired

region abbreviation (or null)

data.​creditNote.​billingAddress.​companyIdstring or nullrequired

Company registration number. (can be null)

data.​creditNote.​billingAddress.​vatIdstring or nullrequired

VAT identification number. (can be null)

data.​creditNote.​billingAddress.​vatIdValidationStatusany

Info, whether VAT ID has been verified, enum [unverified, verified, waiting]

Enum"unverified""verified""waiting"null
data.​creditNote.​billingAddress.​taxIdstring or nullrequired

TAX identification number. For Czech address, taxId is same as vatId. (can be null)

data.​creditNote.​deliveryAddressobject(address)required

delivery address (can be null)

data.​creditNote.​deliveryAddress.​companystring or nullrequired

name of purchaser''s company (or null)

data.​creditNote.​deliveryAddress.​fullNamestring or nullrequired

name of purchaser (or null)

data.​creditNote.​deliveryAddress.​streetstring or nullrequired

street of purchaser (or null)

data.​creditNote.​deliveryAddress.​houseNumberstring or nullrequired

street number (or null)

data.​creditNote.​deliveryAddress.​citystring or nullrequired

city/town (village) (or null)

data.​creditNote.​deliveryAddress.​districtstring or nullrequired

county (or null)

data.​creditNote.​deliveryAddress.​additionalstring or nullrequired

additional address information (or null)

data.​creditNote.​deliveryAddress.​zipstring or nullrequired

ZIP or postal code (or null)

data.​creditNote.​deliveryAddress.​countryCodestring or nullrequired

tree-character ISO country code (ISO 4217)

data.​creditNote.​deliveryAddress.​regionNamestring or nullrequired

region name (or null)

data.​creditNote.​deliveryAddress.​regionShortcutstring or nullrequired

region abbreviation (or null)

data.​creditNote.​addressesEqualbooleanrequired

Are delivery and invoicing address the same?

data.​creditNote.​priceobject(price)required
data.​creditNote.​price.​vatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

VAT value, two decimal places

data.​creditNote.​price.​toPaystring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

total price to pay

data.​creditNote.​price.​currencyCodestring(typeCurrencyCode)^[a-zA-Z]{3}$required

currency code. List of available currencies within the e-shop can be found in endpoint GET /api/eshop.

data.​creditNote.​price.​withoutVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price excluding tax

data.​creditNote.​price.​withVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price including tax

data.​creditNote.​price.​exchangeRatestring(typeExchangeRate)^[0-9]+\.[0-9]{8}$required

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!

data.​creditNote.​price.​partialPaymentAmountstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$

can be value expressed in percents or as exact money value expression (with up to two decimal places) - depends on partialPaymentType value

data.​creditNote.​price.​partialPaymentTypestring

'percents' = partial payment as percentage from total price | 'absolute' = exact expression of partial payment in money

data.​creditNote.​customerobject(documentCustomer)required
data.​creditNote.​customer.​guidstring(typeGuidUnlimited)<= 36 charactersrequired

customer identifier (can be null)

data.​creditNote.​customer.​phonestring or nullrequired

customer phone (can be null)

data.​creditNote.​customer.​emailstring or nullrequired

customer e-mail (can be null)

data.​creditNote.​customer.​remarkstring or nullrequired

remark for the customer (can be null)

data.​creditNote.​eshopobject(eshop)required
data.​creditNote.​eshop.​bankAccountstring or nullrequired

e-shop bank account (can be null)

data.​creditNote.​eshop.​ibanstring or nullrequired

e-shop IBAN (can be null)

data.​creditNote.​eshop.​bicstring or nullrequired

bank code - SWIFT (can be null)

data.​creditNote.​eshop.​vatPayerbooleanrequired

VAT payer (can be null)

data.​creditNote.​itemsArray of objects(documentItemsWithPrice)required
data.​creditNote.​items[].​productGuidstring(typeGuidUnlimited)<= 36 charactersrequired

global unique permanent product identifier (can be null)

data.​creditNote.​items[].​codestring or nullrequired

variant code (product) (can be null)

data.​creditNote.​items[].​itemTypestringrequired

item type

data.​creditNote.​items[].​namestring or nullrequired

product name (can be null)

data.​creditNote.​items[].​variantNamestring or nullrequired

variant name (can be null)

data.​creditNote.​items[].​brandstring or nullrequired

brand name (can be null)

data.​creditNote.​items[].​amountstring or null(typeAmount)^(-)?[0-9]+\.[0-9]{3}$required

quantity

data.​creditNote.​items[].​amountUnitstring or nullrequired

unit of quantity (can be null)

data.​creditNote.​items[].​remarkstring or nullrequired

remark (can be null)

data.​creditNote.​items[].​priceRatiostring(typePriceRatio)[0-9]+\.[0-9]{4}$required

discount - 0.7800 = discount 22%; 1.0000 = no discount

data.​creditNote.​items[].​weightstring(typeWeight)^[0-9]{1,6}\.[0-9]{3}$required

weight in kg, unpacked (can be null). 3 decimal places. Maximum value 999999.

data.​creditNote.​items[].​additionalFieldstring or nullrequired

additional info (can be null)

data.​creditNote.​items[].​itemPriceobject(itemPrice)required

item price

data.​creditNote.​items[].​itemPrice.​withVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price including tax

data.​creditNote.​items[].​itemPrice.​withoutVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price excluding tax

data.​creditNote.​items[].​itemPrice.​vatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

VAT value, two decimal places

data.​creditNote.​items[].​itemPrice.​vatRatestring(typeVatRate)^[0-9]+\.[0-9]{2}$required

VAT rate

data.​creditNote.​items[].​buyPriceobject(itemPrice)required

purchase price of the part, can be null.

data.​creditNote.​items[].​buyPrice.​withVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price including tax

data.​creditNote.​items[].​buyPrice.​withoutVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price excluding tax

data.​creditNote.​items[].​buyPrice.​vatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

VAT value, two decimal places

data.​creditNote.​items[].​buyPrice.​vatRatestring(typeVatRate)^[0-9]+\.[0-9]{2}$required

VAT rate

data.​creditNote.​items[].​displayPricesArray of objects(itemPrice)

in some cases, one item is displayed as multiple lines in the administration or a printout. This array contains one or more rows representing the printout version of the item.

data.​creditNote.​items[].​itemIdnumberrequired

item identifier for manipulation with this item

data.​creditNote.​items[].​surchargeParametersArray of objects(itemSurchargeParameters)
data.​creditNote.​items[].​specificSurchargeParametersArray of objects(itemSpecificSurchargeParameters)
data.​creditNote.​documentRemarkstring or nullrequired

remark on the document (can be null)

data.​creditNote.​vatPayerbooleanrequired

is the tradesman a VAT payer? (can be null)

data.​creditNote.​vatModestring or null

VAT mode, can be null, possible values: Normal, One Stop Shop, Mini One Stop Shop, Reverse charge, Outside the EU

errorsArray of objects or null(Errors)required
errors[].​errorCodestringrequired

Short text error identification

errors[].​messagestringrequired

Descriptive error message

errors[].​instancestringrequired

Identification of the entity referenced

Response
application/vnd.shoptet.v1.0+json; charset=utf-8
{ "data": { "creditNote": {} }, "errors": [ {} ] }

Credit note from proof of payment

Request

Creating credit note from existing proof of payment.

It will create a credit note from the given proof of payment. It will automatically take all proof of payment items and add them to the credit note.

Path
codestringrequired

Proof of payment code

Example: P-2014000004-01
Headers
Content-Typestringrequired
Default application/vnd.shoptet.v1.0
Bodyapplication/vnd.shoptet.v1.0+json
dataobjectrequired
data.​creditNoteCodestring

Credit note code. Optional, generated by eshop settings if not set.

data.​varSymbolnumber[ 0 .. 9999999999 ]

Variable symbol. Optional, generated by eshop settings if not set.

data.​dueDatestring or null(date)(typeDate)^[0-9]{4}-[0-9]{2}-[0-9]{2}$

Due date. Optional, generated by eshop settings if not set.

data.​taxDatestring or null(date)(typeDate)^[0-9]{4}-[0-9]{2}-[0-9]{2}$

Date of taxation. Optional, default is today.

data.​constSymbolstring(typeConstSymbol)^[0-9]{1,4}$

Constant symbol. Optional

data.​specSymbolnumber[ 0 .. 9999999999 ]

Specific symbol. Optional

data.​billingMethodIdnumber
data.​orderCodestring[ 1 .. 10 ] characters

Order Code. Optional, defaults to proof payment's order code if not set.

curl -i -X GET \
  'https://api.myshoptet.com/api/proof-payments/{code}/credit-note' \
  -H 'Content-Type: application/vnd.shoptet.v1.0+json' \
  -H 'Shoptet-Access-Token: YOUR_API_KEY_HERE' \
  -d '{
    "data": {
      "creditNoteCode": "0000000099",
      "varSymbol": 99,
      "dueDate": "2017-04-04",
      "taxDate": "2017-04-04",
      "constSymbol": "0308",
      "specSymbol": 201323134,
      "billingMethodId": 1,
      "orderCode": "201323134"
    }
  }'

Responses

Created

Bodyapplication/vnd.shoptet.v1.0+json; charset=utf-8
dataobjectrequired
data.​creditNoteobjectrequired
data.​creditNote.​codestringrequired

variant code (product) (can be null)

data.​creditNote.​isValidbooleanrequired

is the credit note valid?

data.​creditNote.​invoiceCodestring or nullrequired

invoice number (can be null). Caution! This does not have to be just a number, it can also contain letters, a dash, etc.

data.​creditNote.​orderCodestring or nullrequired

purchase order number (can be null). Caution! This does not have to be just a number, it can also contain letters, a dash, etc.

data.​creditNote.​proofPaymentCodestring or nullrequired

proof payment code (can be null). Caution! This does not have to be just a number, it can also contain letters, a dash, etc.

data.​creditNote.​creationTimestring or null(typeDateTime)^[0-9]{4}-[01][0-9]-[0123][0-9]T[012][0-9]:[0...required

date of issue, in ISO 8601 format

data.​creditNote.​changeTimestring or null(typeDateTime)^[0-9]{4}-[01][0-9]-[0123][0-9]T[012][0-9]:[0...required

date of change, in ISO 8601 format

data.​creditNote.​dueDatestring or null(date)(typeDate)^[0-9]{4}-[0-9]{2}-[0-9]{2}$required

due date in ISO 8601 format (can be null)

data.​creditNote.​taxDatestring or null(date)(typeDate)^[0-9]{4}-[0-9]{2}-[0-9]{2}$required

taxation date in ISO 8601 format (can be null)

data.​creditNote.​varSymbolnumberrequired

variable symbol

data.​creditNote.​constSymbolinteger or nullrequired

constant symbol (can be null)

data.​creditNote.​specSymbolnumber or nullrequired

specific symbol (can be null)

data.​creditNote.​restockedboolean

Items in credit note were restocked?

data.​creditNote.​stockAmountChangeTypestring or nullrequired

type of change in stock quantity (can be null)

data.​creditNote.​weightstring(typeWeightUnlimited)^[0-9]+\.[0-9]{3}$required

weight in kg, unpacked, 3 decimal places. Maximum value 999999.

data.​creditNote.​completePackageWeightstring(typeWeightUnlimited)^[0-9]+\.[0-9]{3}$required

weight in kg, unpacked, 3 decimal places. Maximum value 999999.

data.​creditNote.​billingMethodbillingMethod (object) or nullrequired

information about the method of payment (can be null)

One of:

information about the method of payment (can be null)

data.​creditNote.​billingMethod.​idintegerrequired

unique identifier of billing method

data.​creditNote.​billingMethod.​namestringrequired
data.​creditNote.​billingAddressobject(billingAddress)required

invoicing address

data.​creditNote.​billingAddress.​companystring or nullrequired

name of purchaser''s company (or null)

data.​creditNote.​billingAddress.​fullNamestring or nullrequired

name of purchaser (or null)

data.​creditNote.​billingAddress.​streetstring or nullrequired

street of purchaser (or null)

data.​creditNote.​billingAddress.​houseNumberstring or nullrequired

street number (or null)

data.​creditNote.​billingAddress.​citystring or nullrequired

city/town (village) (or null)

data.​creditNote.​billingAddress.​districtstring or nullrequired

county (or null)

data.​creditNote.​billingAddress.​additionalstring or nullrequired

additional address information (or null)

data.​creditNote.​billingAddress.​zipstring or nullrequired

ZIP or postal code (or null)

data.​creditNote.​billingAddress.​countryCodestring or nullrequired

tree-character ISO country code (ISO 4217)

data.​creditNote.​billingAddress.​regionNamestring or nullrequired

region name (or null)

data.​creditNote.​billingAddress.​regionShortcutstring or nullrequired

region abbreviation (or null)

data.​creditNote.​billingAddress.​companyIdstring or nullrequired

Company registration number. (can be null)

data.​creditNote.​billingAddress.​vatIdstring or nullrequired

VAT identification number. (can be null)

data.​creditNote.​billingAddress.​vatIdValidationStatusany

Info, whether VAT ID has been verified, enum [unverified, verified, waiting]

Enum"unverified""verified""waiting"null
data.​creditNote.​billingAddress.​taxIdstring or nullrequired

TAX identification number. For Czech address, taxId is same as vatId. (can be null)

data.​creditNote.​deliveryAddressobject(address)required

delivery address (can be null)

data.​creditNote.​deliveryAddress.​companystring or nullrequired

name of purchaser''s company (or null)

data.​creditNote.​deliveryAddress.​fullNamestring or nullrequired

name of purchaser (or null)

data.​creditNote.​deliveryAddress.​streetstring or nullrequired

street of purchaser (or null)

data.​creditNote.​deliveryAddress.​houseNumberstring or nullrequired

street number (or null)

data.​creditNote.​deliveryAddress.​citystring or nullrequired

city/town (village) (or null)

data.​creditNote.​deliveryAddress.​districtstring or nullrequired

county (or null)

data.​creditNote.​deliveryAddress.​additionalstring or nullrequired

additional address information (or null)

data.​creditNote.​deliveryAddress.​zipstring or nullrequired

ZIP or postal code (or null)

data.​creditNote.​deliveryAddress.​countryCodestring or nullrequired

tree-character ISO country code (ISO 4217)

data.​creditNote.​deliveryAddress.​regionNamestring or nullrequired

region name (or null)

data.​creditNote.​deliveryAddress.​regionShortcutstring or nullrequired

region abbreviation (or null)

data.​creditNote.​addressesEqualbooleanrequired

Are delivery and invoicing address the same?

data.​creditNote.​priceobject(price)required
data.​creditNote.​price.​vatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

VAT value, two decimal places

data.​creditNote.​price.​toPaystring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

total price to pay

data.​creditNote.​price.​currencyCodestring(typeCurrencyCode)^[a-zA-Z]{3}$required

currency code. List of available currencies within the e-shop can be found in endpoint GET /api/eshop.

data.​creditNote.​price.​withoutVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price excluding tax

data.​creditNote.​price.​withVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price including tax

data.​creditNote.​price.​exchangeRatestring(typeExchangeRate)^[0-9]+\.[0-9]{8}$required

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!

data.​creditNote.​price.​partialPaymentAmountstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$

can be value expressed in percents or as exact money value expression (with up to two decimal places) - depends on partialPaymentType value

data.​creditNote.​price.​partialPaymentTypestring

'percents' = partial payment as percentage from total price | 'absolute' = exact expression of partial payment in money

data.​creditNote.​customerobject(documentCustomer)required
data.​creditNote.​customer.​guidstring(typeGuidUnlimited)<= 36 charactersrequired

customer identifier (can be null)

data.​creditNote.​customer.​phonestring or nullrequired

customer phone (can be null)

data.​creditNote.​customer.​emailstring or nullrequired

customer e-mail (can be null)

data.​creditNote.​customer.​remarkstring or nullrequired

remark for the customer (can be null)

data.​creditNote.​eshopobject(eshop)required
data.​creditNote.​eshop.​bankAccountstring or nullrequired

e-shop bank account (can be null)

data.​creditNote.​eshop.​ibanstring or nullrequired

e-shop IBAN (can be null)

data.​creditNote.​eshop.​bicstring or nullrequired

bank code - SWIFT (can be null)

data.​creditNote.​eshop.​vatPayerbooleanrequired

VAT payer (can be null)

data.​creditNote.​itemsArray of objects(documentItemsWithPrice)required
data.​creditNote.​items[].​productGuidstring(typeGuidUnlimited)<= 36 charactersrequired

global unique permanent product identifier (can be null)

data.​creditNote.​items[].​codestring or nullrequired

variant code (product) (can be null)

data.​creditNote.​items[].​itemTypestringrequired

item type

data.​creditNote.​items[].​namestring or nullrequired

product name (can be null)

data.​creditNote.​items[].​variantNamestring or nullrequired

variant name (can be null)

data.​creditNote.​items[].​brandstring or nullrequired

brand name (can be null)

data.​creditNote.​items[].​amountstring or null(typeAmount)^(-)?[0-9]+\.[0-9]{3}$required

quantity

data.​creditNote.​items[].​amountUnitstring or nullrequired

unit of quantity (can be null)

data.​creditNote.​items[].​remarkstring or nullrequired

remark (can be null)

data.​creditNote.​items[].​priceRatiostring(typePriceRatio)[0-9]+\.[0-9]{4}$required

discount - 0.7800 = discount 22%; 1.0000 = no discount

data.​creditNote.​items[].​weightstring(typeWeight)^[0-9]{1,6}\.[0-9]{3}$required

weight in kg, unpacked (can be null). 3 decimal places. Maximum value 999999.

data.​creditNote.​items[].​additionalFieldstring or nullrequired

additional info (can be null)

data.​creditNote.​items[].​itemPriceobject(itemPrice)required

item price

data.​creditNote.​items[].​itemPrice.​withVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price including tax

data.​creditNote.​items[].​itemPrice.​withoutVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price excluding tax

data.​creditNote.​items[].​itemPrice.​vatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

VAT value, two decimal places

data.​creditNote.​items[].​itemPrice.​vatRatestring(typeVatRate)^[0-9]+\.[0-9]{2}$required

VAT rate

data.​creditNote.​items[].​buyPriceobject(itemPrice)required

purchase price of the part, can be null.

data.​creditNote.​items[].​buyPrice.​withVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price including tax

data.​creditNote.​items[].​buyPrice.​withoutVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price excluding tax

data.​creditNote.​items[].​buyPrice.​vatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

VAT value, two decimal places

data.​creditNote.​items[].​buyPrice.​vatRatestring(typeVatRate)^[0-9]+\.[0-9]{2}$required

VAT rate

data.​creditNote.​items[].​displayPricesArray of objects(itemPrice)

in some cases, one item is displayed as multiple lines in the administration or a printout. This array contains one or more rows representing the printout version of the item.

data.​creditNote.​items[].​itemIdnumberrequired

item identifier for manipulation with this item

data.​creditNote.​items[].​surchargeParametersArray of objects(itemSurchargeParameters)
data.​creditNote.​items[].​specificSurchargeParametersArray of objects(itemSpecificSurchargeParameters)
data.​creditNote.​documentRemarkstring or nullrequired

remark on the document (can be null)

data.​creditNote.​vatPayerbooleanrequired

is the tradesman a VAT payer? (can be null)

data.​creditNote.​vatModestring or null

VAT mode, can be null, possible values: Normal, One Stop Shop, Mini One Stop Shop, Reverse charge, Outside the EU

errorsArray of objects or null(Errors)required
errors[].​errorCodestringrequired

Short text error identification

errors[].​messagestringrequired

Descriptive error message

errors[].​instancestringrequired

Identification of the entity referenced

Response
application/vnd.shoptet.v1.0+json; charset=utf-8
{ "data": { "creditNote": {} }, "errors": [ {} ] }

Creation of credit note item

Request

Creates a new credit note item to an existing credit note.

Path
codestringrequired

credit note code (number)

Example: 2018000012
Headers
Content-Typestringrequired
Default application/vnd.shoptet.v1.0
Bodyapplication/vnd.shoptet.v1.0+json
dataobjectnon-emptyrequired
data.​itemTypestringnon-emptyrequired

item type, required (allowed product or product-set only)

data.​codestring
data.​amountstring or null(typeAmount)^(-)?[0-9]+\.[0-9]{3}$required

name of item, required

data.​namestring or nullrequired

name of item, required

data.​variantNamestring or null

name of variant (can be null)

data.​amountUnitstring or null

unit of amount (kg, ks) (can be null)

data.​pricestring

price of item, 2 decimal places accuracy (can be null), default value 0.00

data.​priceRatiostring(typePriceRatio)non-empty[0-9]+\.[0-9]{4}$

price ratio of item, required

data.​includingVatboolean

default value is false; whether the credit note item price is saved with VAT or without

data.​vatRatestring(typeVatRate)^[0-9]+\.[0-9]{2}$

VAT rate in percent

data.​weightstring(typeWeightRequest)^[0-9]{1,5}\.[0-9]{3}$

weight of the item, 3 decimal places accuracy (can be null)

data.​remarkstring or null

item note (can be null)

data.​additionalFieldstring or null

field for additional info (can be null)

curl -i -X POST \
  'https://api.myshoptet.com/api/credit-notes/{code}/item' \
  -H 'Content-Type: application/vnd.shoptet.v1.0+json' \
  -H 'Shoptet-Access-Token: YOUR_API_KEY_HERE' \
  -d '{
    "data": {
      "itemType": "product",
      "code": "string",
      "amount": "1.000",
      "name": "Item name",
      "variantName": "white",
      "amountUnit": "kg",
      "price": "100.00",
      "priceRatio": "0.7800",
      "includingVat": true,
      "vatRate": "21.00",
      "weight": "15.500",
      "remark": "item note",
      "additionalField": "additional info"
    }
  }'

Responses

OK

Bodyapplication/vnd.shoptet.v1.0+json; charset=utf-8
dataobjectrequired
data.​creditNoteobjectrequired
data.​creditNote.​codestringrequired

variant code (product) (can be null)

data.​creditNote.​isValidbooleanrequired

is the credit note valid?

data.​creditNote.​invoiceCodestring or nullrequired

invoice number (can be null). Caution! This does not have to be just a number, it can also contain letters, a dash, etc.

data.​creditNote.​orderCodestring or nullrequired

purchase order number (can be null). Caution! This does not have to be just a number, it can also contain letters, a dash, etc.

data.​creditNote.​proofPaymentCodestring or nullrequired

proof payment code (can be null). Caution! This does not have to be just a number, it can also contain letters, a dash, etc.

data.​creditNote.​creationTimestring or null(typeDateTime)^[0-9]{4}-[01][0-9]-[0123][0-9]T[012][0-9]:[0...required

date of issue, in ISO 8601 format

data.​creditNote.​changeTimestring or null(typeDateTime)^[0-9]{4}-[01][0-9]-[0123][0-9]T[012][0-9]:[0...required

date of change, in ISO 8601 format

data.​creditNote.​dueDatestring or null(date)(typeDate)^[0-9]{4}-[0-9]{2}-[0-9]{2}$required

due date in ISO 8601 format (can be null)

data.​creditNote.​taxDatestring or null(date)(typeDate)^[0-9]{4}-[0-9]{2}-[0-9]{2}$required

taxation date in ISO 8601 format (can be null)

data.​creditNote.​varSymbolnumberrequired

variable symbol

data.​creditNote.​constSymbolinteger or nullrequired

constant symbol (can be null)

data.​creditNote.​specSymbolnumber or nullrequired

specific symbol (can be null)

data.​creditNote.​restockedboolean

Items in credit note were restocked?

data.​creditNote.​stockAmountChangeTypestring or nullrequired

type of change in stock quantity (can be null)

data.​creditNote.​weightstring(typeWeightUnlimited)^[0-9]+\.[0-9]{3}$required

weight in kg, unpacked, 3 decimal places. Maximum value 999999.

data.​creditNote.​completePackageWeightstring(typeWeightUnlimited)^[0-9]+\.[0-9]{3}$required

weight in kg, unpacked, 3 decimal places. Maximum value 999999.

data.​creditNote.​billingMethodbillingMethod (object) or nullrequired

information about the method of payment (can be null)

One of:

information about the method of payment (can be null)

data.​creditNote.​billingMethod.​idintegerrequired

unique identifier of billing method

data.​creditNote.​billingMethod.​namestringrequired
data.​creditNote.​billingAddressobject(billingAddress)required

invoicing address

data.​creditNote.​billingAddress.​companystring or nullrequired

name of purchaser''s company (or null)

data.​creditNote.​billingAddress.​fullNamestring or nullrequired

name of purchaser (or null)

data.​creditNote.​billingAddress.​streetstring or nullrequired

street of purchaser (or null)

data.​creditNote.​billingAddress.​houseNumberstring or nullrequired

street number (or null)

data.​creditNote.​billingAddress.​citystring or nullrequired

city/town (village) (or null)

data.​creditNote.​billingAddress.​districtstring or nullrequired

county (or null)

data.​creditNote.​billingAddress.​additionalstring or nullrequired

additional address information (or null)

data.​creditNote.​billingAddress.​zipstring or nullrequired

ZIP or postal code (or null)

data.​creditNote.​billingAddress.​countryCodestring or nullrequired

tree-character ISO country code (ISO 4217)

data.​creditNote.​billingAddress.​regionNamestring or nullrequired

region name (or null)

data.​creditNote.​billingAddress.​regionShortcutstring or nullrequired

region abbreviation (or null)

data.​creditNote.​billingAddress.​companyIdstring or nullrequired

Company registration number. (can be null)

data.​creditNote.​billingAddress.​vatIdstring or nullrequired

VAT identification number. (can be null)

data.​creditNote.​billingAddress.​vatIdValidationStatusany

Info, whether VAT ID has been verified, enum [unverified, verified, waiting]

Enum"unverified""verified""waiting"null
data.​creditNote.​billingAddress.​taxIdstring or nullrequired

TAX identification number. For Czech address, taxId is same as vatId. (can be null)

data.​creditNote.​deliveryAddressobject(address)required

delivery address (can be null)

data.​creditNote.​deliveryAddress.​companystring or nullrequired

name of purchaser''s company (or null)

data.​creditNote.​deliveryAddress.​fullNamestring or nullrequired

name of purchaser (or null)

data.​creditNote.​deliveryAddress.​streetstring or nullrequired

street of purchaser (or null)

data.​creditNote.​deliveryAddress.​houseNumberstring or nullrequired

street number (or null)

data.​creditNote.​deliveryAddress.​citystring or nullrequired

city/town (village) (or null)

data.​creditNote.​deliveryAddress.​districtstring or nullrequired

county (or null)

data.​creditNote.​deliveryAddress.​additionalstring or nullrequired

additional address information (or null)

data.​creditNote.​deliveryAddress.​zipstring or nullrequired

ZIP or postal code (or null)

data.​creditNote.​deliveryAddress.​countryCodestring or nullrequired

tree-character ISO country code (ISO 4217)

data.​creditNote.​deliveryAddress.​regionNamestring or nullrequired

region name (or null)

data.​creditNote.​deliveryAddress.​regionShortcutstring or nullrequired

region abbreviation (or null)

data.​creditNote.​addressesEqualbooleanrequired

Are delivery and invoicing address the same?

data.​creditNote.​priceobject(price)required
data.​creditNote.​price.​vatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

VAT value, two decimal places

data.​creditNote.​price.​toPaystring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

total price to pay

data.​creditNote.​price.​currencyCodestring(typeCurrencyCode)^[a-zA-Z]{3}$required

currency code. List of available currencies within the e-shop can be found in endpoint GET /api/eshop.

data.​creditNote.​price.​withoutVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price excluding tax

data.​creditNote.​price.​withVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price including tax

data.​creditNote.​price.​exchangeRatestring(typeExchangeRate)^[0-9]+\.[0-9]{8}$required

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!

data.​creditNote.​price.​partialPaymentAmountstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$

can be value expressed in percents or as exact money value expression (with up to two decimal places) - depends on partialPaymentType value

data.​creditNote.​price.​partialPaymentTypestring

'percents' = partial payment as percentage from total price | 'absolute' = exact expression of partial payment in money

data.​creditNote.​customerobject(documentCustomer)required
data.​creditNote.​customer.​guidstring(typeGuidUnlimited)<= 36 charactersrequired

customer identifier (can be null)

data.​creditNote.​customer.​phonestring or nullrequired

customer phone (can be null)

data.​creditNote.​customer.​emailstring or nullrequired

customer e-mail (can be null)

data.​creditNote.​customer.​remarkstring or nullrequired

remark for the customer (can be null)

data.​creditNote.​eshopobject(eshop)required
data.​creditNote.​eshop.​bankAccountstring or nullrequired

e-shop bank account (can be null)

data.​creditNote.​eshop.​ibanstring or nullrequired

e-shop IBAN (can be null)

data.​creditNote.​eshop.​bicstring or nullrequired

bank code - SWIFT (can be null)

data.​creditNote.​eshop.​vatPayerbooleanrequired

VAT payer (can be null)

data.​creditNote.​itemsArray of objects(documentItemsWithPrice)required
data.​creditNote.​items[].​productGuidstring(typeGuidUnlimited)<= 36 charactersrequired

global unique permanent product identifier (can be null)

data.​creditNote.​items[].​codestring or nullrequired

variant code (product) (can be null)

data.​creditNote.​items[].​itemTypestringrequired

item type

data.​creditNote.​items[].​namestring or nullrequired

product name (can be null)

data.​creditNote.​items[].​variantNamestring or nullrequired

variant name (can be null)

data.​creditNote.​items[].​brandstring or nullrequired

brand name (can be null)

data.​creditNote.​items[].​amountstring or null(typeAmount)^(-)?[0-9]+\.[0-9]{3}$required

quantity

data.​creditNote.​items[].​amountUnitstring or nullrequired

unit of quantity (can be null)

data.​creditNote.​items[].​remarkstring or nullrequired

remark (can be null)

data.​creditNote.​items[].​priceRatiostring(typePriceRatio)[0-9]+\.[0-9]{4}$required

discount - 0.7800 = discount 22%; 1.0000 = no discount

data.​creditNote.​items[].​weightstring(typeWeight)^[0-9]{1,6}\.[0-9]{3}$required

weight in kg, unpacked (can be null). 3 decimal places. Maximum value 999999.

data.​creditNote.​items[].​additionalFieldstring or nullrequired

additional info (can be null)

data.​creditNote.​items[].​itemPriceobject(itemPrice)required

item price

data.​creditNote.​items[].​itemPrice.​withVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price including tax

data.​creditNote.​items[].​itemPrice.​withoutVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price excluding tax

data.​creditNote.​items[].​itemPrice.​vatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

VAT value, two decimal places

data.​creditNote.​items[].​itemPrice.​vatRatestring(typeVatRate)^[0-9]+\.[0-9]{2}$required

VAT rate

data.​creditNote.​items[].​buyPriceobject(itemPrice)required

purchase price of the part, can be null.

data.​creditNote.​items[].​buyPrice.​withVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price including tax

data.​creditNote.​items[].​buyPrice.​withoutVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price excluding tax

data.​creditNote.​items[].​buyPrice.​vatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

VAT value, two decimal places

data.​creditNote.​items[].​buyPrice.​vatRatestring(typeVatRate)^[0-9]+\.[0-9]{2}$required

VAT rate

data.​creditNote.​items[].​displayPricesArray of objects(itemPrice)

in some cases, one item is displayed as multiple lines in the administration or a printout. This array contains one or more rows representing the printout version of the item.

data.​creditNote.​items[].​itemIdnumberrequired

item identifier for manipulation with this item

data.​creditNote.​items[].​surchargeParametersArray of objects(itemSurchargeParameters)
data.​creditNote.​items[].​specificSurchargeParametersArray of objects(itemSpecificSurchargeParameters)
data.​creditNote.​documentRemarkstring or nullrequired

remark on the document (can be null)

data.​creditNote.​vatPayerbooleanrequired

is the tradesman a VAT payer? (can be null)

data.​creditNote.​vatModestring or null

VAT mode, can be null, possible values: Normal, One Stop Shop, Mini One Stop Shop, Reverse charge, Outside the EU

errorsArray of objects or null(Errors)required
errors[].​errorCodestringrequired

Short text error identification

errors[].​messagestringrequired

Descriptive error message

errors[].​instancestringrequired

Identification of the entity referenced

Response
application/vnd.shoptet.v1.0+json; charset=utf-8
{ "data": { "creditNote": {} }, "errors": [ {} ] }

Update of credit note item

Request

Updates credit note item. It's not possible to change productType property and it's not possible to update credit note item of another type then product or product-set.

Path
codestringrequired

credit note code (number)

Example: 2018000012
idnumberrequired

credit note item id. Can be found in field data.creditNote.items.itemId in Credit note detail. (number)

Example: 198
Headers
Content-Typestringrequired
Default application/vnd.shoptet.v1.0
Bodyapplication/vnd.shoptet.v1.0+json
dataobjectnon-emptyrequired
data.​codestring
data.​amountstring or null(typeAmount)^(-)?[0-9]+\.[0-9]{3}$

amount of item, 3 decimal places accuracy, required. For credit note you will probably use negative amount. (can be null)

data.​namestring or null

name of item (can be null)

data.​variantNamestring or null

name of variant (can be null)

data.​amountUnitstring or null

unit of amount (can be null)

data.​pricestring

price of item, 3 decimal places accuracy (can be null), default value 0.00

data.​includingVatboolean

default value is false; whether the credit note item price is saved with VAT or without

data.​vatRatestring(typeVatRate)^[0-9]+\.[0-9]{2}$

VAT rate in percent

data.​priceRatiostring(typePriceRatio)non-empty[0-9]+\.[0-9]{4}$

value of discount of price, 4 decimal places accuracy, (from 0.0000 to 1.0000), e.g. 0.8500 means 85% discount (can be null)

data.​weightstring(typeWeightRequest)^[0-9]{1,5}\.[0-9]{3}$

weight of the item, 3 decimal places accuracy (can be null)

data.​remarkstring or null

item note (can be null)

data.​additionalFieldstring or null

field for additional info (can be null)

curl -i -X PATCH \
  'https://api.myshoptet.com/api/credit-notes/{code}/item/{id}' \
  -H 'Content-Type: application/vnd.shoptet.v1.0+json' \
  -H 'Shoptet-Access-Token: YOUR_API_KEY_HERE' \
  -d '{
    "data": {
      "code": "string",
      "amount": "1.000",
      "name": "Item name",
      "variantName": "white",
      "amountUnit": "kg, ks",
      "price": "125.00",
      "includingVat": true,
      "vatRate": "21.00",
      "priceRatio": "0.7800",
      "weight": "15.500",
      "remark": "Item note",
      "additionalField": "additional info"
    }
  }'

Responses

OK

Bodyapplication/vnd.shoptet.v1.0+json; charset=utf-8
dataobjectrequired
data.​creditNoteItemobject(documentItemsWithPrice)required
data.​creditNoteItem.​productGuidstring(typeGuidUnlimited)<= 36 charactersrequired

global unique permanent product identifier (can be null)

data.​creditNoteItem.​codestring or nullrequired

variant code (product) (can be null)

data.​creditNoteItem.​itemTypestringrequired

item type

data.​creditNoteItem.​namestring or nullrequired

product name (can be null)

data.​creditNoteItem.​variantNamestring or nullrequired

variant name (can be null)

data.​creditNoteItem.​brandstring or nullrequired

brand name (can be null)

data.​creditNoteItem.​amountstring or null(typeAmount)^(-)?[0-9]+\.[0-9]{3}$required

quantity

data.​creditNoteItem.​amountUnitstring or nullrequired

unit of quantity (can be null)

data.​creditNoteItem.​remarkstring or nullrequired

remark (can be null)

data.​creditNoteItem.​priceRatiostring(typePriceRatio)[0-9]+\.[0-9]{4}$required

discount - 0.7800 = discount 22%; 1.0000 = no discount

data.​creditNoteItem.​weightstring(typeWeight)^[0-9]{1,6}\.[0-9]{3}$required

weight in kg, unpacked (can be null). 3 decimal places. Maximum value 999999.

data.​creditNoteItem.​additionalFieldstring or nullrequired

additional info (can be null)

data.​creditNoteItem.​itemPriceobject(itemPrice)required

item price

data.​creditNoteItem.​itemPrice.​withVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price including tax

data.​creditNoteItem.​itemPrice.​withoutVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price excluding tax

data.​creditNoteItem.​itemPrice.​vatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

VAT value, two decimal places

data.​creditNoteItem.​itemPrice.​vatRatestring(typeVatRate)^[0-9]+\.[0-9]{2}$required

VAT rate

data.​creditNoteItem.​buyPriceobject(itemPrice)required

purchase price of the part, can be null.

data.​creditNoteItem.​buyPrice.​withVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price including tax

data.​creditNoteItem.​buyPrice.​withoutVatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

price excluding tax

data.​creditNoteItem.​buyPrice.​vatstring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

VAT value, two decimal places

data.​creditNoteItem.​buyPrice.​vatRatestring(typeVatRate)^[0-9]+\.[0-9]{2}$required

VAT rate

data.​creditNoteItem.​displayPricesArray of objects(itemPrice)

in some cases, one item is displayed as multiple lines in the administration or a printout. This array contains one or more rows representing the printout version of the item.

data.​creditNoteItem.​itemIdnumberrequired

item identifier for manipulation with this item

data.​creditNoteItem.​surchargeParametersArray of objects(itemSurchargeParameters)
data.​creditNoteItem.​specificSurchargeParametersArray of objects(itemSpecificSurchargeParameters)
errorsArray of objects or null(Errors)required
errors[].​errorCodestringrequired

Short text error identification

errors[].​messagestringrequired

Descriptive error message

errors[].​instancestringrequired

Identification of the entity referenced

Response
application/vnd.shoptet.v1.0+json; charset=utf-8
{ "data": { "creditNoteItem": {} }, "errors": [ {} ] }

Deletion of credit note item

Request

Deletes credit note item. It's not possible to delete credit note item of another type then product or product-set.

Path
codestringrequired

credit note code (number)

Example: 2018000012
idnumberrequired

credit note item id. Can be found in field data.creditNote.items.itemId in Credit note detail. (number)

Example: 198
Headers
Content-Typestringrequired
Default application/vnd.shoptet.v1.0
curl -i -X DELETE \
  'https://api.myshoptet.com/api/credit-notes/{code}/item/{id}' \
  -H 'Content-Type: application/vnd.shoptet.v1.0' \
  -H 'Shoptet-Access-Token: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/vnd.shoptet.v1.0+json; charset=utf-8
datanullrequired
errorsArray of objects or null(Errors)required
errors[].​errorCodestringrequired

Short text error identification

errors[].​messagestringrequired

Descriptive error message

errors[].​instancestringrequired

Identification of the entity referenced

Response
application/vnd.shoptet.v1.0+json; charset=utf-8
{ "data": null, "errors": null }

Download credit note as PDF

Request

You can request the credit note as PDF file, response will be as application/octet-stream. You can download pdf documents

only one-by-one for every e-shop. Parallel requests end with 423 Locked error.

Path
codestringrequired
Example: 0000000002
Headers
Content-Typestringrequired
Default application/vnd.shoptet.v1.0
curl -i -X GET \
  'https://api.myshoptet.com/api/credit-notes/{code}/pdf' \
  -H 'Content-Type: application/vnd.shoptet.v1.0' \
  -H 'Shoptet-Access-Token: YOUR_API_KEY_HERE'

Responses

OK

Response
application/vnd.shoptet.v1.0+json; charset=utf-8
{ "data": null, "errors": [ {} ] }

Download credit note as ISDOC

Request

You can request the credit note as ISDOC file, response will be as application/octet-stream. You can download the documents only one-by-one for every e-shop. Parallel requests end with 423 Locked error.

Path
codestringrequired
Example: 0000000002
Headers
Content-Typestringrequired
Default application/vnd.shoptet.v1.0
curl -i -X GET \
  'https://api.myshoptet.com/api/credit-notes/{code}/isdoc' \
  -H 'Content-Type: application/vnd.shoptet.v1.0' \
  -H 'Shoptet-Access-Token: YOUR_API_KEY_HERE'

Responses

OK

Response
application/vnd.shoptet.v1.0+json; charset=utf-8
{ "data": null, "errors": [ {} ] }

Last credit note changes

Request

Returns the list of credit notes, which were changed. The Endpoint is intended to determine the changes after you have loaded the list of credit notes and you need to know the changes. The guaranteed history of changes is 30 days.

Each credit note is only given in the listing with its last change. For example, if the credit note was modified and then deleted, the listing will only show information about its deletion.

Creation is considered as edit action. So, when there is a new item created, it will be displayed like edit action.

Endpoint supports pagination.

Query
fromstringrequired
Example: from=2018-05-28T14:17:00+02:00
Headers
Content-Typestringrequired
Default application/vnd.shoptet.v1.0
curl -i -X GET \
  'https://api.myshoptet.com/api/credit-notes/changes?from=string' \
  -H 'Content-Type: application/vnd.shoptet.v1.0' \
  -H 'Shoptet-Access-Token: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/vnd.shoptet.v1.0+json; charset=utf-8
dataobjectrequired
data.​changesArray of objectsrequired
data.​changes[].​codestringrequired

identifier (number) of the document, which can be used to query about the details.

data.​changes[].​changeTimestring or null(typeDateTime)^[0-9]{4}-[01][0-9]-[0123][0-9]T[012][0-9]:[0...required

date and time when the event happened. ISO 8601 format (2017-12-12T22:08:01+0100).

data.​changes[].​changeTypestringrequired

type of event that happened with the document. Possible values are following: add, edit, delete.

data.​paginatorobject(paginator)required
data.​paginator.​totalCountintegerrequired

total number of available records

data.​paginator.​pageintegerrequired

current page

data.​paginator.​pageCountintegerrequired

total available of pages

data.​paginator.​itemsOnPageintegerrequired

number of currently returned records

data.​paginator.​itemsPerPageintegerrequired

required number of records per page

errorsArray of objects or null(Errors)required
errors[].​errorCodestringrequired

Short text error identification

errors[].​messagestringrequired

Descriptive error message

errors[].​instancestringrequired

Identification of the entity referenced

Response
application/vnd.shoptet.v1.0+json; charset=utf-8
{ "data": { "changes": [], "paginator": {} }, "errors": [ {} ] }

Delivery notes

Delivery note endpoints are used for managing delivery notes in the e-shop.

The code (code) is the credit notes identifier. Although this is usually a number, it is necessary to take into account that this might also include

letters, a dash, etc.

Operations

Proof payments

The code (code) is the proof payments identifier. Although this is usually a number, it is necessary to take into account that this might also include letters, a dash, etc.

Operations

Stocks

Stock endpoints are used for managing stocks in the e-shop.

Operations

Suppliers

Supplier endpoints are used for managing suppliers in the e-shop.

Operations

Brands

Brand endpoints are used for managing brands in the e-shop.

Please note, the field code is deprecated - use indexName instead. Parameter code accepts both: guid string style, e.g. d467bfbe-4334-11ef-ad70-0242ac1f0005, and index name string style, e.g. willy-wonka. The index name string style is deprecated - use guid style.

Operations

Customers

Customer endpoints are used for managing customers in the e-shop.

Operations

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:

  1. 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.

  2. 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.

  3. The code entered in the administration GUI (/admin/html-kody/, HTML code tab).

Operations

Payment gateways

API endpoints for integration of payment gateways.

If you are a Premium client, contact your Account or Onboarding manager. New payment gateway has to be approved by Shoptet and client needs to be familiar with the terms of payment in advance.

Operations

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 happened

  • event - event which invoked the call (see code list Webhook event types)

  • eventCreated - accurate time, when the event happened

  • eventInstance - 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/.

Operations

Shipping methods

Shipping methods endpoints are used for managing shipping methods in the e-shop.

Operations

Shipping requests

Shipping requests endpoints are used for managing shipping requests in the e-shop.

Operations

Payment methods

Payment methods endpoints are used for managing payment methods in the e-shop.

Operations

Unsubscribed emails

This functionality allows you to manage a list of email addresses that opted out of receiving marketing communications in compliance with legal requirements, including the possibility of comparing any further mailings with this list to exclude opt-out contacts.

Operations

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.

Operations

Discount coupons

Discount coupons endpoints are used for managing discount coupons in the e-shop.

Operations

X + Y discounts

X + Y discounts endpoints are used for managing X + Y discounts in the e-shop.

Operations

Articles

Article endpoints are used for managing articles in the e-shop.

Operations

Pages

Page endpoints are used for managing pages in the e-shop.

Operations

Discussions

Discussion endpoints are used for managing discussions in the e-shop.

Operations

Job endpoints

Job endpoints are used for managing asynchronous jobs in the e-shop.

Operations

Files

File endpoints are used for managing files in the e-shop.

Operations

System endpoints

This endpoints are used for obtaining information for endpoints in API.

Operations