Zum Hauptinhalt springen
Omneya
EN
Start test system Try it
Developer docs menu

Manufacturers

List, read, create, change and delete manufacturers, including the product safety (GPSR) contact data. Manufacturers are shared by all shops of the system.

List manufacturers

GET /manufacturers

Scope: manufacturers.read

Returns the manufacturers page by page, sorted by name. Deleted manufacturers are not listed. search finds manufacturers whose name starts with the given text.

Query parameters

Parameter Type Required Description
search string optional Start of the name. At least 2 characters. min length 2 · max length 191
status integer optional Only manufacturers with this status (1 active, 0 inactive). one of: 0, 1
page integer optional Page number. min 1 · max 1000000 · default 1
per_page integer optional Manufacturers per page. min 1 · max 100 · default 25

Example request

curl "https://shop.example.com/api/v1/manufacturers" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json"

Responses

200 OK One page of manufacturers. 

{
  "data": [
    {
      "id": 12,
      "name": "Acme Tools",
      "status": 1,
      "website": "https://acme.example",
      "logo_url": null,
      "street": "Sample Street",
      "house_number": "7",
      "postal_code": "20095",
      "city": "Hamburg",
      "phone_number": "+49 40 1234567",
      "fax_number": null,
      "contact_email": "info@acme.example",
      "external_name": null,
      "country": "DE",
      "responsible_name": null,
      "responsible_street": null,
      "responsible_house_number": null,
      "responsible_postal_code": null,
      "responsible_city": null,
      "responsible_country": null,
      "responsible_email": null,
      "responsible_phone": null,
      "position": 1,
      "comments": null,
      "created_at": "2026-10-15T09:30:00+02:00",
      "updated_at": "2026-10-15T09:30:00+02:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 1,
    "last_page": 1
  }
}
Response fields
Field Type Required Description
data[] array of object required
id integer required
name string required max length 191
status integer required 1 active, 0 inactive. one of: 0, 1
website string | null optional max length 191
logo_url string | null optional max length 191
street string | null optional max length 191
house_number string | null optional max length 191
postal_code string | null optional max length 191
city string | null optional max length 191
phone_number string | null optional max length 191
fax_number string | null optional max length 191
contact_email string | null optional max length 191
external_name string | null optional max length 191
country string | null optional ISO 3166-1 alpha-2 code. min length 2 · max length 2
responsible_name string | null optional Responsible person in the EU (Article 16 GPSR). max length 191
responsible_street string | null optional max length 191
responsible_house_number string | null optional max length 191
responsible_postal_code string | null optional max length 191
responsible_city string | null optional max length 191
responsible_country string | null optional ISO 3166-1 alpha-2 code. min length 2 · max length 2
responsible_email string | null optional max length 191
responsible_phone string | null optional max length 191
position integer | null optional
comments string | null optional
created_at string (date-time) | null optional
updated_at string (date-time) | null optional
meta object required
current_page integer required
per_page integer required
total integer required
last_page integer required

Error responses

401 Unauthorized The API key is missing, malformed, wrong, paused, expired or revoked. The body is always the same and never names the reason. 
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key.",
    "details": []
  }
}
403 Forbidden The API key is valid but lacks a scope this endpoint needs. details.required lists the scopes the endpoint requires, details.missing the ones your key lacks. Ask the shop operator to add the scope. 
{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key is missing a required scope.",
    "details": {
      "required": [
        "orders.write"
      ],
      "missing": [
        "orders.write"
      ]
    }
  }
}
422 Unprocessable Content The request data is invalid. details lists every problem at once: per field a list of {code, message}. Field names use dots for nesting, for example value_ids.1 is the second entry of value_ids (counting from 0). 
{
  "error": {
    "code": "validation_failed",
    "message": "The request payload is invalid.",
    "details": {
      "street": [
        {
          "code": "required",
          "message": "The street field is required."
        }
      ],
      "country": [
        {
          "code": "unknown_country",
          "message": "The selected country is invalid."
        }
      ]
    }
  }
}
429 Too Many Requests Too many requests. Either your API client used up its requests per minute (message Too many requests., with all rate limit headers), or too many failed authentications came in a short time (message Too many authentication attempts., only Retry-After). Both carry the code rate_limited. 
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests.",
    "details": []
  }
}
500 Internal Server Error An unexpected error occurred on our side. Retry later. 
{
  "error": {
    "code": "server_error",
    "message": "An unexpected error occurred.",
    "details": []
  }
}

All error codes: error code reference.

Create a manufacturer

POST /manufacturers

Scope: manufacturers.write

Creates a manufacturer. Only name is required; it must not be used by another manufacturer (compared without regard to upper and lower case and accents, deleted manufacturers do not count). Countries are sent as ISO 3166-1 alpha-2 codes. Without status the manufacturer is active. Unknown fields are rejected with unknown_field.

Request body

Field Type Required Description
name string required Must not be used by another manufacturer (compared without regard to upper and lower case and accents). Cannot be cleared. min length 1 · max length 191
status integer optional 1 = active, 0 = inactive. Default on create: 1. one of: 0, 1
website string (uri) | null optional http or https URL. max length 191
logo_url string (uri) | null optional http or https URL. Link to the logo; there is no logo upload. max length 191
street string | null optional max length 191
house_number string | null optional max length 191
postal_code string | null optional max length 191
city string | null optional max length 191
country string | null optional Country code according to ISO 3166-1 alpha-2. Unknown codes fail with unknown_country. min length 2 · max length 2
phone_number string | null optional max length 191
fax_number string | null optional max length 191
contact_email string (email) | null optional max length 191
external_name string | null optional max length 191
position integer | null optional min 0 · max 2147483647
comments string | null optional max length 16383
responsible_name string | null optional Responsible person in the EU (Article 16 GPSR). max length 191
responsible_street string | null optional max length 191
responsible_house_number string | null optional max length 191
responsible_postal_code string | null optional max length 191
responsible_city string | null optional max length 191
responsible_country string | null optional Country code according to ISO 3166-1 alpha-2. Unknown codes fail with unknown_country. min length 2 · max length 2
responsible_email string (email) | null optional max length 191
responsible_phone string | null optional max length 191

Example request

curl -X POST "https://shop.example.com/api/v1/manufacturers" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme Tools",
  "website": "https://acme.example",
  "logo_url": "https://cdn.example/acme-logo.png",
  "street": "Sample Street",
  "house_number": "7",
  "postal_code": "20095",
  "city": "Hamburg",
  "country": "DE",
  "phone_number": "+49 40 1234567",
  "contact_email": "info@acme.example",
  "position": 1
}'

Responses

201 Created The manufacturer was created. 

{
  "data": {
    "id": 12,
    "name": "Acme Tools",
    "status": 1,
    "website": "https://acme.example",
    "logo_url": "https://cdn.example/acme-logo.png",
    "street": "Sample Street",
    "house_number": "7",
    "postal_code": "20095",
    "city": "Hamburg",
    "phone_number": "+49 40 1234567",
    "fax_number": null,
    "contact_email": "info@acme.example",
    "external_name": null,
    "country": "DE",
    "responsible_name": null,
    "responsible_street": null,
    "responsible_house_number": null,
    "responsible_postal_code": null,
    "responsible_city": null,
    "responsible_country": null,
    "responsible_email": null,
    "responsible_phone": null,
    "position": 1,
    "comments": null,
    "created_at": "2026-10-15T09:30:00+02:00",
    "updated_at": "2026-10-15T09:30:00+02:00",
    "articles_count": 0
  }
}
Response fields
Field Type Required Description
data object required
id integer required
name string required max length 191
status integer required 1 active, 0 inactive. one of: 0, 1
website string | null optional max length 191
logo_url string | null optional max length 191
street string | null optional max length 191
house_number string | null optional max length 191
postal_code string | null optional max length 191
city string | null optional max length 191
phone_number string | null optional max length 191
fax_number string | null optional max length 191
contact_email string | null optional max length 191
external_name string | null optional max length 191
country string | null optional ISO 3166-1 alpha-2 code. min length 2 · max length 2
responsible_name string | null optional Responsible person in the EU (Article 16 GPSR). max length 191
responsible_street string | null optional max length 191
responsible_house_number string | null optional max length 191
responsible_postal_code string | null optional max length 191
responsible_city string | null optional max length 191
responsible_country string | null optional ISO 3166-1 alpha-2 code. min length 2 · max length 2
responsible_email string | null optional max length 191
responsible_phone string | null optional max length 191
position integer | null optional
comments string | null optional
created_at string (date-time) | null optional
updated_at string (date-time) | null optional
articles_count integer optional Number of articles (not deleted) assigned to this manufacturer.

Error responses

401 Unauthorized The API key is missing, malformed, wrong, paused, expired or revoked. The body is always the same and never names the reason. 
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key.",
    "details": []
  }
}
403 Forbidden The API key is valid but lacks a scope this endpoint needs. details.required lists the scopes the endpoint requires, details.missing the ones your key lacks. Ask the shop operator to add the scope. 
{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key is missing a required scope.",
    "details": {
      "required": [
        "orders.write"
      ],
      "missing": [
        "orders.write"
      ]
    }
  }
}
422 Unprocessable Content The request data is invalid. details lists every problem at once: per field a list of {code, message}. Field names use dots for nesting, for example value_ids.1 is the second entry of value_ids (counting from 0). 
{
  "error": {
    "code": "validation_failed",
    "message": "The request payload is invalid.",
    "details": {
      "street": [
        {
          "code": "required",
          "message": "The street field is required."
        }
      ],
      "country": [
        {
          "code": "unknown_country",
          "message": "The selected country is invalid."
        }
      ]
    }
  }
}
429 Too Many Requests Too many requests. Either your API client used up its requests per minute (message Too many requests., with all rate limit headers), or too many failed authentications came in a short time (message Too many authentication attempts., only Retry-After). Both carry the code rate_limited. 
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests.",
    "details": []
  }
}
500 Internal Server Error An unexpected error occurred on our side. Retry later. 
{
  "error": {
    "code": "server_error",
    "message": "An unexpected error occurred.",
    "details": []
  }
}

All error codes: error code reference.

Get a manufacturer

GET /manufacturers/{id}

Scope: manufacturers.read

Returns one manufacturer with all fields and the number of its articles. A deleted or unknown manufacturer answers 404.

Path parameters

Parameter Type Required Description
id integer required Our manufacturer ID. min 1

Example request

curl "https://shop.example.com/api/v1/manufacturers/12" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json"

Responses

200 OK The manufacturer. 

{
  "data": {
    "id": 12,
    "name": "Acme Tools",
    "status": 1,
    "website": "https://acme.example",
    "logo_url": null,
    "street": "Sample Street",
    "house_number": "7",
    "postal_code": "20095",
    "city": "Hamburg",
    "phone_number": "+49 40 1234567",
    "fax_number": null,
    "contact_email": "info@acme.example",
    "external_name": null,
    "country": "DE",
    "responsible_name": null,
    "responsible_street": null,
    "responsible_house_number": null,
    "responsible_postal_code": null,
    "responsible_city": null,
    "responsible_country": null,
    "responsible_email": null,
    "responsible_phone": null,
    "position": 1,
    "comments": null,
    "created_at": "2026-10-15T09:30:00+02:00",
    "updated_at": "2026-10-15T09:30:00+02:00",
    "articles_count": 42
  }
}
Response fields
Field Type Required Description
data object required
id integer required
name string required max length 191
status integer required 1 active, 0 inactive. one of: 0, 1
website string | null optional max length 191
logo_url string | null optional max length 191
street string | null optional max length 191
house_number string | null optional max length 191
postal_code string | null optional max length 191
city string | null optional max length 191
phone_number string | null optional max length 191
fax_number string | null optional max length 191
contact_email string | null optional max length 191
external_name string | null optional max length 191
country string | null optional ISO 3166-1 alpha-2 code. min length 2 · max length 2
responsible_name string | null optional Responsible person in the EU (Article 16 GPSR). max length 191
responsible_street string | null optional max length 191
responsible_house_number string | null optional max length 191
responsible_postal_code string | null optional max length 191
responsible_city string | null optional max length 191
responsible_country string | null optional ISO 3166-1 alpha-2 code. min length 2 · max length 2
responsible_email string | null optional max length 191
responsible_phone string | null optional max length 191
position integer | null optional
comments string | null optional
created_at string (date-time) | null optional
updated_at string (date-time) | null optional
articles_count integer optional Number of articles (not deleted) assigned to this manufacturer.

Error responses

401 Unauthorized The API key is missing, malformed, wrong, paused, expired or revoked. The body is always the same and never names the reason. 
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key.",
    "details": []
  }
}
403 Forbidden The API key is valid but lacks a scope this endpoint needs. details.required lists the scopes the endpoint requires, details.missing the ones your key lacks. Ask the shop operator to add the scope. 
{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key is missing a required scope.",
    "details": {
      "required": [
        "orders.write"
      ],
      "missing": [
        "orders.write"
      ]
    }
  }
}
404 Not Found The path does not exist, the API is not enabled on this system, the order does not belong to the shop of your API client, or the customer, address or label value is not known to your API client. 
{
  "error": {
    "code": "not_found",
    "message": "The requested resource does not exist.",
    "details": []
  }
}
429 Too Many Requests Too many requests. Either your API client used up its requests per minute (message Too many requests., with all rate limit headers), or too many failed authentications came in a short time (message Too many authentication attempts., only Retry-After). Both carry the code rate_limited. 
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests.",
    "details": []
  }
}
500 Internal Server Error An unexpected error occurred on our side. Retry later. 
{
  "error": {
    "code": "server_error",
    "message": "An unexpected error occurred.",
    "details": []
  }
}

All error codes: error code reference.

Change a manufacturer

PATCH /manufacturers/{id}

Scope: manufacturers.write

Only the fields you send are changed. Send null to clear a field; name and status cannot be cleared. At least one field is required. A new name must not be used by another manufacturer. A deleted or unknown manufacturer answers 404. Unknown fields are rejected with unknown_field.

Path parameters

Parameter Type Required Description
id integer required Our manufacturer ID. min 1

Request body

Field Type Required Description
name string optional Must not be used by another manufacturer (compared without regard to upper and lower case and accents). Cannot be cleared. min length 1 · max length 191
status integer optional 1 = active, 0 = inactive. Default on create: 1. one of: 0, 1
website string (uri) | null optional http or https URL. max length 191
logo_url string (uri) | null optional http or https URL. Link to the logo; there is no logo upload. max length 191
street string | null optional max length 191
house_number string | null optional max length 191
postal_code string | null optional max length 191
city string | null optional max length 191
country string | null optional Country code according to ISO 3166-1 alpha-2. Unknown codes fail with unknown_country. min length 2 · max length 2
phone_number string | null optional max length 191
fax_number string | null optional max length 191
contact_email string (email) | null optional max length 191
external_name string | null optional max length 191
position integer | null optional min 0 · max 2147483647
comments string | null optional max length 16383
responsible_name string | null optional Responsible person in the EU (Article 16 GPSR). max length 191
responsible_street string | null optional max length 191
responsible_house_number string | null optional max length 191
responsible_postal_code string | null optional max length 191
responsible_city string | null optional max length 191
responsible_country string | null optional Country code according to ISO 3166-1 alpha-2. Unknown codes fail with unknown_country. min length 2 · max length 2
responsible_email string (email) | null optional max length 191
responsible_phone string | null optional max length 191

Example request

curl -X PATCH "https://shop.example.com/api/v1/manufacturers/12" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "city": "Bremen",
  "fax_number": null
}'

Responses

200 OK The changed manufacturer. 

{
  "data": {
    "id": 12,
    "name": "Acme Tools",
    "status": 1,
    "website": "https://acme.example",
    "logo_url": "https://cdn.example/acme-logo.png",
    "street": "Sample Street",
    "house_number": "7",
    "postal_code": "20095",
    "city": "Bremen",
    "phone_number": "+49 40 1234567",
    "fax_number": null,
    "contact_email": "info@acme.example",
    "external_name": null,
    "country": "DE",
    "responsible_name": null,
    "responsible_street": null,
    "responsible_house_number": null,
    "responsible_postal_code": null,
    "responsible_city": null,
    "responsible_country": null,
    "responsible_email": null,
    "responsible_phone": null,
    "position": 1,
    "comments": null,
    "created_at": "2026-10-15T09:30:00+02:00",
    "updated_at": "2026-10-16T11:00:00+02:00",
    "articles_count": 42
  }
}
Response fields
Field Type Required Description
data object required
id integer required
name string required max length 191
status integer required 1 active, 0 inactive. one of: 0, 1
website string | null optional max length 191
logo_url string | null optional max length 191
street string | null optional max length 191
house_number string | null optional max length 191
postal_code string | null optional max length 191
city string | null optional max length 191
phone_number string | null optional max length 191
fax_number string | null optional max length 191
contact_email string | null optional max length 191
external_name string | null optional max length 191
country string | null optional ISO 3166-1 alpha-2 code. min length 2 · max length 2
responsible_name string | null optional Responsible person in the EU (Article 16 GPSR). max length 191
responsible_street string | null optional max length 191
responsible_house_number string | null optional max length 191
responsible_postal_code string | null optional max length 191
responsible_city string | null optional max length 191
responsible_country string | null optional ISO 3166-1 alpha-2 code. min length 2 · max length 2
responsible_email string | null optional max length 191
responsible_phone string | null optional max length 191
position integer | null optional
comments string | null optional
created_at string (date-time) | null optional
updated_at string (date-time) | null optional
articles_count integer optional Number of articles (not deleted) assigned to this manufacturer.

Error responses

401 Unauthorized The API key is missing, malformed, wrong, paused, expired or revoked. The body is always the same and never names the reason. 
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key.",
    "details": []
  }
}
403 Forbidden The API key is valid but lacks a scope this endpoint needs. details.required lists the scopes the endpoint requires, details.missing the ones your key lacks. Ask the shop operator to add the scope. 
{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key is missing a required scope.",
    "details": {
      "required": [
        "orders.write"
      ],
      "missing": [
        "orders.write"
      ]
    }
  }
}
404 Not Found The path does not exist, the API is not enabled on this system, the order does not belong to the shop of your API client, or the customer, address or label value is not known to your API client. 
{
  "error": {
    "code": "not_found",
    "message": "The requested resource does not exist.",
    "details": []
  }
}
422 Unprocessable Content The request data is invalid. details lists every problem at once: per field a list of {code, message}. Field names use dots for nesting, for example value_ids.1 is the second entry of value_ids (counting from 0). 
{
  "error": {
    "code": "validation_failed",
    "message": "The request payload is invalid.",
    "details": {
      "street": [
        {
          "code": "required",
          "message": "The street field is required."
        }
      ],
      "country": [
        {
          "code": "unknown_country",
          "message": "The selected country is invalid."
        }
      ]
    }
  }
}
429 Too Many Requests Too many requests. Either your API client used up its requests per minute (message Too many requests., with all rate limit headers), or too many failed authentications came in a short time (message Too many authentication attempts., only Retry-After). Both carry the code rate_limited. 
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests.",
    "details": []
  }
}
500 Internal Server Error An unexpected error occurred on our side. Retry later. 
{
  "error": {
    "code": "server_error",
    "message": "An unexpected error occurred.",
    "details": []
  }
}

All error codes: error code reference.

Delete a manufacturer

DELETE /manufacturers/{id}

Scope: manufacturers.write

If articles are assigned, the first request answers 409 manufacturer_has_articles with their number in details.articles_count. Repeat the request with confirmed_articles_count set to that number to delete the manufacturer; the articles then have no manufacturer. If the number changed in between, you get 409 again with the new number. An invalid confirmed_articles_count answers 422 before the manufacturer is looked up.

Path parameters

Parameter Type Required Description
id integer required Our manufacturer ID. min 1

Query parameters

Parameter Type Required Description
confirmed_articles_count integer optional Number of assigned articles you confirm, taken from details.articles_count of the 409 answer. min 0

Example request

curl -X DELETE "https://shop.example.com/api/v1/manufacturers/12" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json"

Responses

204 No Content The manufacturer was deleted. The response has no body.

Error responses

401 Unauthorized The API key is missing, malformed, wrong, paused, expired or revoked. The body is always the same and never names the reason. 
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key.",
    "details": []
  }
}
403 Forbidden The API key is valid but lacks a scope this endpoint needs. details.required lists the scopes the endpoint requires, details.missing the ones your key lacks. Ask the shop operator to add the scope. 
{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key is missing a required scope.",
    "details": {
      "required": [
        "orders.write"
      ],
      "missing": [
        "orders.write"
      ]
    }
  }
}
404 Not Found The path does not exist, the API is not enabled on this system, the order does not belong to the shop of your API client, or the customer, address or label value is not known to your API client. 
{
  "error": {
    "code": "not_found",
    "message": "The requested resource does not exist.",
    "details": []
  }
}
409 Conflict manufacturer_has_articles: articles are assigned, and confirmed_articles_count is missing or does not match their number. Nothing was deleted. 
{
  "error": {
    "code": "manufacturer_has_articles",
    "message": "12 articles are assigned to this manufacturer. Deleting it removes the manufacturer from these articles. To confirm, repeat the request with confirmed_articles_count=12.",
    "details": {
      "articles_count": 12
    }
  }
}
422 Unprocessable Content The request data is invalid. details lists every problem at once: per field a list of {code, message}. Field names use dots for nesting, for example value_ids.1 is the second entry of value_ids (counting from 0). 
{
  "error": {
    "code": "validation_failed",
    "message": "The request payload is invalid.",
    "details": {
      "street": [
        {
          "code": "required",
          "message": "The street field is required."
        }
      ],
      "country": [
        {
          "code": "unknown_country",
          "message": "The selected country is invalid."
        }
      ]
    }
  }
}
429 Too Many Requests Too many requests. Either your API client used up its requests per minute (message Too many requests., with all rate limit headers), or too many failed authentications came in a short time (message Too many authentication attempts., only Retry-After). Both carry the code rate_limited. 
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests.",
    "details": []
  }
}
500 Internal Server Error An unexpected error occurred on our side. Retry later. 
{
  "error": {
    "code": "server_error",
    "message": "An unexpected error occurred.",
    "details": []
  }
}

All error codes: error code reference.