API reference import

The import/ endpoint provides an interface for importing data into the system. The API can be used to start, pause, resume, cancel, and query the current progress of import processes.

Supported methods

List of all supported methods.

Command/info	Endpoints	GET	PUT	POST	DELETE
Import	import/

General

Supported services and formats

The import/ endpoint provides an interface for importing data into the system. The API can be used to start, pause, resume, cancel, and query the current progress of import processes. The import function is currently supported for the following services:

Service	Supported formats
`adminUser`	`json`, `csv`
`category`	`json`, `csv`
`customerAccount`	`json`, `csv`
`dataFeed`	`json`, `csv`
`dataFeedTemplate`	`json`, `csv`
`inquiry`	`json`, `csv`, `xml`
`inventory`	`json`, `csv`
`order`	`json`, `xml`, `zip`
`newsletterSubscriber`	`json`, `csv`
`product`	`json`, `csv`
`productRating`	`json`, `csv`
`seoViews`	`json`, `csv`
`text`	`json`, `xml`, `csv`
`voucher`	`json`, `csv`
`voucherPreset`	`json`, `csv`
`voucherTemplate`	`json`, `csv`

The zip format is only available for the order service. The ZIP file may only contain orders from WEBSALE 8 as individual .ord files, one file per order. Information on transferring orders from WEBSALE 8 can be found under Data migration.

Methods for data import

GET import/{service}/status

This endpoint returns the current status of a running or most recently executed import process for a given service (e.g. newsletterSubscriber). The response contains detailed information about the progress, processed and erroneous data records, and the start time. If available, the end time of the import is also shown. The status of an import process is represented by numeric values:
0 = READY
1 = STARTING
2 = RUNNING
3 = PAUSED
4 = CANCELED
5 = FINISHED
6 = ERROR These status values provide information about the current progress or result of an import.

For the newsletterSubscriber service, the shop sends the double opt-in emails to new subscribers at the end of the import, provided the importSubscribeDoubleOptIn option in newsletter.newsletter is enabled. This process can take up to 10 minutes. If it fails, the import ends with status 6 = ERROR. lastError then contains the text Failed to send double opt-in emails, and an internal error is reported in globalError.

To access the services, you need the appropriate permissions or an administrator account with full access. For most services, you need write and create permissions. For voucher, voucherTemplate, voucherPreset, inquiry, and order, write permission is sufficient. For product, write and create permissions for product variants are additionally required. For adminUser, an administrator account with full access is required. The same permissions apply to starting, pausing, resuming, and canceling an import.

Example

https://www.<your-shop>.de/admin/api/v1/import/newsletterSubscriber/status

Response

{
    "duration": 2,
    "end": "",
    "failed": 0,
    "globalError": 0,
    "importErrors": [],
    "lastError": "",
    "percentage": 60,
    "processed": 3,
    "start": "2025-02-19T13:31:40.000000000Z",
    "status": 2,
    "total": 5
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions for the service.
400 Bad Request		`service` is unknown.
503 Service Unavailable	”internalError”	Redis did not return a status.

POST import/{service}/start

This endpoint starts the import process for a given service. The data to be uploaded (e.g. as JSON or CSV) is passed in the request body. If an import process is already running for the service, it is automatically canceled before the new import is started. The response immediately returns the current status of the started import. It contains information about progress, the number of processed and erroneous data records, and start/end times. The status value is returned as a numeric code according to the import definition. The required permissions correspond to those of the status endpoint (see the section on GET import/{service}/status).

Query parameters

Parameter	Required	Description
`format`	No	The data format of the import file (e.g. `json`, `csv`). The supported formats depend on the respective service (see Supported services and formats).
`sendMail`	No	Only for the `adminUser` service: controls whether an email is sent to the imported users.

Example

https://www.<your-shop>.de/admin/api/v1/import/newsletterSubscriber/start?format=json

Request body

[
    {
        "blacklisted": false,
        "createdAt": "2025-02-04T15:05:24.000Z",
        "createdBy": 0,
        "email": "subscriber@websale.de",
        "fields": {
            "firstName": "fda",
            "lastName": "fafdsa",
            "salutation": "1"
        },
        "id": 2,
        "isImport": true,
        "subshopId": "deutsch",
        "targetGroupIds": [
            1,
            2,
            3
        ]
    },
    {
        "blacklisted": true,
        "createdAt": "2025-02-04T16:06:23.000Z",
        "createdBy": 1,
        "email": "foo@example.com",
        "fields": {},
        "id": 3,
        "isImport": false,
        "subshopId": "deutsch",
        "targetGroupIds": [
            1
        ]
    },
    ...
]

Response

{
    "duration": 1,
    "end": "2025-04-28T11:55:13.000000000Z",
    "failed": 9,
    "globalError": 0,
    "importErrors": [
        {
            "errors": [
                {
                    "entryId": "",
                    "error": 0,
                    "field": "salutation"
                },
                {
                    "entryId": "",
                    "error": 0,
                    "field": "lastName"
                },
                {
                    "entryId": "",
                    "error": 0,
                    "field": "firstName"
                }
            ],
            "index": 1
        },
        {
            "errors": [
                {
                    "entryId": "",
                    "error": 0,
                    "field": "salutation"
                },
                {
                    "entryId": "",
                    "error": 0,
                    "field": "lastName"
                },
                {
                    "entryId": "",
                    "error": 0,
                    "field": "firstName"
                }
            ],
            "index": 3
        },
        ...
    ],
    "lastError": "",
    "percentage": 100,
    "processed": 12,
    "start": "2025-04-28T11:55:12.000000000Z",
    "status": 5,
    "total": 12
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to write or create the service’s data.
400 Bad Request		`service` is unknown. The service does not support the `format`.
503 Service Unavailable	”serviceUnavailable”	The import process could not be triggered.
503 Service Unavailable	”internalError”	Redis did not return a status. The internal `FileService` cannot be reached. Request could not be stored in a file. The status could not be updated in Redis. The import process did not start within 10 seconds.

POST import/{service}/pause

This endpoint pauses a running import process for a given service. The response contains the current status of the paused process, including processed data records, progress, and any errors. After a successful pause, the status value is set to PAUSED (3). The required permissions correspond to those of the status endpoint (see the section on GET import/{service}/status).

Example

https://www.<your-shop>.de/admin/api/v1/import/newsletterSubscriber/pause

Response

{
    "duration": 0,
    "end": "",
    "failed": 0,
    "globalError": 0,
    "importErrors": [],
    "lastError": "",
    "percentage": 60,
    "processed": 3,
    "start": "2025-02-19T13:39:17.000000000Z",
    "status": 3,
    "total": 5
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions.
400 Bad Request		`service` is unknown.
404 Not found		The process is not running or is not in the RUNNING status.
503 Service Unavailable	”internalError”	Redis did not return a status. Redis cannot be reached. The process could not be stopped.

POST import/{service}/resume

This endpoint resumes a paused import process for a given service. The response contains the current status of the resumed process, including processed data records, progress, and any errors. The required permissions correspond to those of the status endpoint (see the section on GET import/{service}/status).

Example

https://www.<your-shop>.de/admin/api/v1/import/newsletterSubscriber/resume

Response

{
    "duration": 0,
    "end": "",
    "failed": 0,
    "globalError": 0,
    "importErrors": [],
    "lastError": "",
    "percentage": 60,
    "processed": 3,
    "start": "2025-02-19T13:39:17.000000000Z",
    "status": 2,
    "total": 5
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions.
400 Bad Request		`service` is unknown.
404 Not found		The process is not in the PAUSED status.
503 Service Unavailable	”internalError”	Redis did not return a status. Redis cannot be reached. The process could not be stopped.

DELETE import/{service}/cancel

This endpoint cancels a running import process for a given service. The response contains the current status of the canceled process, including processed data records, progress, and any errors. After a successful cancel, the status value is set to CANCELED (4). The required permissions correspond to those of the status endpoint (see the section on GET import/{service}/status).

Example

https://www.<your-shop>.de/admin/api/v1/import/newsletterSubscriber/cancel

Response

{
    "duration": 2,
    "end": "2025-02-19T13:39:19.000000000Z",
    "failed": 0,
    "globalError": 0,
    "importErrors": [],
    "lastError": "",
    "percentage": 60,
    "processed": 3,
    "start": "2025-02-19T13:39:17.000000000Z",
    "status": 4,
    "total": 5
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions.
400 Bad Request		`service` is unknown.
404 Not found		The process is not running or is not in a cancelable status (RUNNING, STARTING, or PAUSED).
503 Service Unavailable	”internalError”	Redis did not return a status. Redis cannot be reached. The process could not be stopped.

Support

Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: Zum Kundenportal Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.

Interfaces

Admin Interface API

Storefront API

More

Supported methods

General

Supported services and formats

Methods for data import

GET import/{service}/status

Example

Response

Error codes

POST import/{service}/start

Query parameters

Example

Request body

Response

Error codes

POST import/{service}/pause

Example

Response

Error codes

POST import/{service}/resume

Example

Response

Error codes

DELETE import/{service}/cancel

Example

Response

Error codes

Support

​Supported methods

​General

​Supported services and formats

​Methods for data import

​GET import/{service}/status

​Example

​Response

​Error codes

​POST import/{service}/start

​Query parameters

​Example

​Request body

​Response

​Error codes

​POST import/{service}/pause

​Example

​Response

​Error codes

​POST import/{service}/resume

​Example

​Response

​Error codes

​DELETE import/{service}/cancel

​Example

​Response

​Error codes

​Support

Supported methods

General

Supported services and formats

Methods for data import

GET import/{service}/status

Example

Response

Error codes

POST import/{service}/start

Query parameters

Example

Request body

Response

Error codes

POST import/{service}/pause

Example

Response

Error codes

POST import/{service}/resume

Example

Response

Error codes

DELETE import/{service}/cancel

Example

Response

Error codes

Support