Label Service

Download OpenAPI specification:Download

Labels allow to mark details related to a product, for example highlighting that a product has a worldwide shipment possibility.

Key Features:

Highlights important product information that you can display on the storefront.
Allows you to use your own icons and media files for proper indication of labels.
Facilitates marking items with the information that makes them easier to sell.

Key Benefits:

Enhance product visibility by highlighting key details directly on your storefront. This includes features such as "organic" or "eco-friendly," which help customers identify important features and make informed purchasing decisions.
Ensures compliance with relevant regulations.
Customizable labels improve engagement by utilizing your own icons and media to create visually impactful labels, such as "Gluten-Free", "A+++ energy class" or "Worldwide Shipping".

Label

Manage labels

Retrieving labels

Retrieves all tenant's labels.

SecurityOAuth2

Request

query Parameters

justOverlay

boolean

Restricts the labels to just the ones which should be printed on the Products as overlay. If the parameter is true, then only the labels with overlay.position >= 1 will be shown. Otherwise, all the labels will be shown.

header Parameters

Accept-Language

string

The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred.

Responses

200

The request was successful. List of labels is returned.

401

Unauthorized. The caller is not allowed to access this resource.

500

Some server side error occurred.

get/label

Request samples

Response samples

200
401
500

application/json

[{"id": "66fe65e83132e30001e6be29",
"name": "Worldwide Shipment",
"description": "<p>Worldwide Shipment</p>",
"image": "https://res.cloudinary.com/saas-ag/image/upload/v1727903960/tenant/labels/54fd0a26-fa47-45b7-ae22-8e54e0bb98d2.jpg",
"cloudinaryUrl": "tenant/labels/54fd0a26-fa47-45b7-ae22-8e54e0bb98d2",
"overlay": {"position": 0,
"isTrue": false
},
"metadata": {"createdAt": "2024-10-03T05:58:08.228Z",
"modifiedAt": "2024-10-03T05:58:08.228Z",
"version": 0
}
},
{"id": "61ge81e13562e22001h6cf456",
"name": "Extended Warranty",
"description": "<p>Warrany with full coverage</p>",
"image": "https://res.cloudinary.com/saas-ag/image/upload/v1727903960/tenant/labels/54fd0a26-fa47-45b7-ae22-8e54e0bb98d2.jpg",
"cloudinaryUrl": "tenant/labels/54fd0a26-fa47-45b7-ae22-8e54e0bb98d2",
"overlay": {"position": 1,
"isTrue": true
},
"metadata": {"createdAt": "2024-10-03T09:30:10.548Z",
"modifiedAt": "2024-10-03T09:30:10.548Z",
"version": 2
}
}
]

Creating a label

Creates a new label.

Required scopes

label.label_manage

SecurityOAuth2

Request

Request Body schema: application/json

id	string Unique ID of the label. It will be auto-generated if not provided.
name required	string Name of the label.
image required	string Image URL.
cloudinaryUrl	string Cludinary path.
	object (overlay) If present and `isTrue` is actually true the label should be printed on associated products on the described position.
required	string or object Localized resource description in a form of a map of translations.

Responses

201

The label was successfully created.

400

Request was syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized. The caller is not allowed to access this resource.

403

Access forbidden. The caller is not allowed to access this resource.

409

Label with given ID already exists.

500

Some server side error occurred.

post/label

Request samples

application/json

{"id": "66fe65e83132e30001e6be29",
"name": "Worldwide Shipment",
"description": "<p>Worldwide Shipment</p>",
"image": "https://res.cloudinary.com/saas-ag/image/upload/v1727903960/tenant/labels/54fd0a26-fa47-45b7-ae22-8e54e0bb98d2.jpg",
"cloudinaryUrl": "tenant/labels/54fd0a26-fa47-45b7-ae22-8e54e0bb98d2",
"overlay": {"position": 0,
"isTrue": true
}
}

Response samples

application/json

{"id": "66fe65e83132e30001e6be29",
"name": "Worldwide Shipment",
"description": "<p>Worldwide Shipment</p>",
"image": "https://res.cloudinary.com/saas-ag/image/upload/v1727903960/tenant/labels/54fd0a26-fa47-45b7-ae22-8e54e0bb98d2.jpg",
"cloudinaryUrl": "tenant/labels/54fd0a26-fa47-45b7-ae22-8e54e0bb98d2",
"overlay": {"position": 0,
"isTrue": true
},
"metadata": {"createdAt": "2024-10-03T05:58:08.228Z",
"modifiedAt": "2024-10-03T05:58:08.228Z",
"version": 0
}
}

Retrieving a label

Retrieves a label with the specified label ID.

SecurityOAuth2

Request

path Parameters

labelId

required

string

Unique identifier of the label.

Responses

200

The label was successfully retrieved.

401

Unauthorized. The caller is not allowed to access this resource.

404

Requested resource does not exist.

500

Some server side error occurred.

get/label/{labelId}

Request samples

Response samples

200
401
404
500

application/json

{"id": "66fe65e83132e30001e6be29",
"name": "Worldwide Shipment",
"description": "<p>Worldwide Shipment</p>",
"image": "https://res.cloudinary.com/saas-ag/image/upload/v1727903960/tenant/labels/54fd0a26-fa47-45b7-ae22-8e54e0bb98d2.jpg",
"cloudinaryUrl": "tenant/labels/54fd0a26-fa47-45b7-ae22-8e54e0bb98d2",
"overlay": {"position": 0,
"isTrue": true
},
"metadata": {"createdAt": "2024-10-03T05:58:08.228Z",
"modifiedAt": "2024-10-03T05:58:08.228Z",
"version": 0
}
}

Updating a label

Updates a label with the specified label ID.

Required scopes

label.label_manage

SecurityOAuth2

Request

path Parameters

labelId

required

string

Unique identifier of the label.

Request Body schema: application/json

name required	string Name of the label.
image required	string Image URL.
cloudinaryUrl	string Cludinary path.
	object (overlay) If present and `isTrue` is actually true the label should be printed on associated products on the described position.
required	string or object Localized resource description in a form of a map of translations.

Responses

200

The label was successfully updated.

400

Request was syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized. The caller is not allowed to access this resource.

403

Access forbidden. The caller is not allowed to access this resource.

404

Requested resource does not exist.

500

Some server side error occurred.

put/label/{labelId}

Request samples

application/json

{"name": "Worldwide Shipment",
"description": "<p>Worldwide Shipment</p>",
"image": "https://res.cloudinary.com/saas-ag/image/upload/v1727903960/tenant/labels/54fd0a26-fa47-45b7-ae22-8e54e0bb98d2.jpg",
"cloudinaryUrl": "tenant/labels/54fd0a26-fa47-45b7-ae22-8e54e0bb98d2",
"overlay": {"position": 0,
"isTrue": true
}
}

Response samples

application/json

{"id": "66fe65e83132e30001e6be29",
"name": "Worldwide Shipment",
"description": "<p>Worldwide Shipment</p>",
"image": "https://res.cloudinary.com/saas-ag/image/upload/v1727903960/tenant/labels/54fd0a26-fa47-45b7-ae22-8e54e0bb98d2.jpg",
"cloudinaryUrl": "tenant/labels/54fd0a26-fa47-45b7-ae22-8e54e0bb98d2",
"overlay": {"position": 0,
"isTrue": true
},
"metadata": {"createdAt": "2024-10-03T05:58:08.228Z",
"modifiedAt": "2024-10-03T05:58:08.228Z",
"version": 0
}
}

Partailly updating a label

Partially updates a label with the specified label ID.

Required scopes

label.label_manage

SecurityOAuth2

Request

path Parameters

labelId

required

string

Unique identifier of the label.

Request Body schema: application/json

name required	string Name of the label.
image required	string Image URL.
cloudinaryUrl	string Cludinary path.
	object (overlay) If present and `isTrue` is actually true the label should be printed on associated products on the described position.
required	string or object Localized resource description in a form of a map of translations.

Responses

200

The label was successfully updated.

401

Unauthorized. The caller is not allowed to access this resource.

403

Access forbidden. The caller is not allowed to access this resource.

404

Requested resource does not exist.

500

Some server side error occurred.

patch/label/{labelId}

Request samples

application/json

{"name": "Worldwide Shipment"
}

Response samples

200
401
403
404
500

application/json

{"id": "66fe65e83132e30001e6be29",
"name": "Worldwide Shipment",
"description": "<p>Worldwide Shipment</p>",
"image": "https://res.cloudinary.com/saas-ag/image/upload/v1727903960/tenant/labels/54fd0a26-fa47-45b7-ae22-8e54e0bb98d2.jpg",
"cloudinaryUrl": "tenant/labels/54fd0a26-fa47-45b7-ae22-8e54e0bb98d2",
"overlay": {"position": 0,
"isTrue": true
},
"metadata": {"createdAt": "2024-10-03T05:58:08.228Z",
"modifiedAt": "2024-10-03T05:58:08.228Z",
"version": 0
}
}

Deleting a label

Deletes a label with the specified label ID.

Required scopes

label.label_delete

SecurityOAuth2

Request

path Parameters

labelId

required

string

Unique identifier of the label.

Responses

204

The label was successfully deleted.

401

Unauthorized. The caller is not allowed to access this resource.

403

Access forbidden. The caller is not allowed to access this resource.

404

Requested resource does not exist.

500

Some server side error occurred.

delete/label/{labelId}

Request samples

Response samples

401
403
404
500

application/json

{"fault": {"faultstring": "Invalid Access Token",
"detail": {"errorcode": "keymanagement.service.invalid_access_token"
}
}
}

Media

Manage labels media

Creating a media

Creates an image for a label.

Required scopes

label.label_manage

SecurityOAuth2

Request

Request Body schema: multipart/form-data

file required	object <binary>
metadata	string

Responses

200

Successfully created media.

401

Unauthorized. The caller is not allowed to access this resource.

403

Access forbidden. The caller is not allowed to access this resource.

500

Some server side error occurred.

post/media

Request samples

Response samples

200
401
403
500

application/json

{"link": "https://res.cloudinary.com/saas-ag/image/upload/v1728023450/tenant/labels/0a075c00-3893-47e7-b0d7-84f9ba7e339a.jpg",
"id": "tenant/labels/0a075c00-3893-47e7-b0d7-84f9ba7e339a"
}

Deleting a media

Deletes label image with specified media ID.

Required scopes

label.label_delete

SecurityOAuth2

Request

path Parameters

mediaId

required

string

Unique identifier of the media.

Responses

200

Media successfully deleted.

401

Unauthorized. The caller is not allowed to access this resource.

403

Access forbidden. The caller is not allowed to access this resource.

404

Resource does not exist.

500

Some server side error occurred.

delete/media/{mediaId}

Request samples

Response samples

401
403
500

application/json

{"fault": {"faultstring": "Invalid Access Token",
"detail": {"errorcode": "keymanagement.service.invalid_access_token"
}
}
}