Quote Service

Download OpenAPI specification:Download

E-mail: documentation@emporix.com

Manage the customers' quotes before going to checkout.

Key Features:

The Quote Management feature provides the possibility to create, read, update, and delete a quote.
- Quote requested created by customer
- Quote created by employee on behalf of the customer
Accepting and declining a quote as employee or customer
Notification for customer for created quote
Notification for employee if customer created a quote request
Quote overview

Key Benefits:

Ability to generate and retrieve quotes without going directly to checkout
Streamlined purchasing process with quote management within one platform
Automated notifications minimizing the amount of manual work
Transparent quote status
Easy-to-integrate quotation process

Quote management

Retrieving quotes

Retrieves quotes. The response includes either all quotes or a subset of quotes based on the assigned access token scopes.

Required scopes (one of)

quote.quote_read - assigned to employees to allow them to retrieve all tenant quotes
quote.quote_read_own - assigned to customers to enable them to retrieve only the quotes that they created themselves or that were created on their behalf

SecurityOAuth2

Request

path Parameters

tenant

required

string

Your Emporix tenant's name.

Note: The tenant name should always be written in lowercase.

Example: saasdev2

query Parameters

pageSize	integer >= 1 Default: 60 Number of items to be retrieved per page.
pageNumber	integer >= 1 Default: 1 Page number to be retrieved. The number of the first page is 1.
sort	string List of properties used to sort the results, separated by colons. The order of properties indicates their priority in sorting. Possible values: `{fieldName}` `{fieldName}:asc` `{fieldName}:desc` Note: If you want to sort the results by localized properties, the possible values are: `{fieldName}.{language}` `{fieldName}.{language}:asc` `{fieldName}.{language}:desc` If the sorting direction is not specified, the fields are sorted in ascending order.
q	string A standard query parameter is used to search for specific values. Searching for items by string-based properties: By a field value: `q=siteCode:main`, where `siteCode` is the field name, and `main` is its desired value. By a localized field value: `q=items.product.name.en:apple_lobo`, where `name` is the field name of product, `en` is the language code, and `apple_lobo` is the field value expressed in the specified language. Note: This query works only for localized fields, which are stored in a map format, where `key` is the language code and `value` is the translation to particular language. Searching for items by a number-based property: With a specific value: `q=items.quantity.quantity:20` With a value greater than: `q=items.quantity.quantity:>20` With a value lower than: `q=items.quantity.quantity:<20` With a value greater than or equal to: `q=items.quantity.quantity:>=20` With a value lower than or equal to: `q=items.quantity.quantity:<=20` With a value within a range of values: `q=items.quantity.quantity:(>=10 AND <=20)` where `items.quantity.quantity` is the name of the number-based field, and `20` is its querying value. Searching for items by a date-based property: All numer-based property queries are also valid for dates. In that case, the date should be placed within double quotes: `q=metadataCreatedAt:(>="2021-05-18T07:27:27.455Z" AND <"2021-05-20T07:27:27.455Z")` Searching for items by a boolean-based property: `q=description.multiLanguage:true`, where `description.multiLanguage` is the boolean field name, and `true` is its desired value. Searching for items with a nonexistent or empty property: `q=description.en:null`, where `description.en` is the field that has its value set to `null`. Searching for items with an existing property: `q=mixin:exists`, where `mixin` is the field that has a non-empty value. Searching for items by multiple specific values: `q=id:(5c3325baa9812100098ff48f,5c3325d1a9812100098ff494)`, where `id` is the field name, and strings within the bracket are the desired values. Searching for items by multiple fields: `q=id:5c3325baa9812100098ff48f siteCode:main` where `id` and `siteCode` are field names. All objects that contain the specified values are returned. Multiple fields (separated by space) can be specified. Multiple values for each field can also be specified in the format presented earlier. Searching for items with string-based properties conforming to a regex: `q=siteCode:~ain` or `q=code:(~U PL)` - in case of searching for strings with space, where `siteCode` is the name of the field, and `ain` or `U PL` is its querying regex. Searching for items with a localized string-based property conforming to a regex: `items.product.name.en:~(Joghurt im)` - where `name` is the product field name, `en` is the desired language, and `Joghurt im` is the search term. Example: q=siteCode:{main}
fields	string Fields to be returned in the response. When this parameter is passed, only the `id` and `{fieldName}` are retrieved for each entry. You can specify multiple fields by separating them with commas. Example: fields=code,message

header Parameters

Accept-Language

string

List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields. If a value is specified, then it must be present in the tenant configuration.

If the header is set to a particular language or a list of languages, all localized fields are retrieved as strings.
If the header is set to *, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.
If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.

X-Total-Count

boolean

Default: false

Flag indicating whether the total number of retrieved items should be returned.

Example: true

Responses

200

The request was successful. Quote's details are returned.

400

Unsupported language provided.

401

Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.

403

Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.

get/{tenant}/quotes

Request samples

Response samples

application/json

[{"id": "5b3188dc-9a5c-4163-8756-4f228c295a59",
"customer": {"customerId": "72318750",
"firstName": "Stefan",
"lastName": "Muller",
"contactEmail": "s.muller@emporix.com"
},
"employee": {"employeeId": "00u6fo3yzjE8Q7X0d417",
"firstName": "John",
"lastName": "Smith"
},
"cartId": "63ee5168e55c231c327220d3",
"company": {"name": "ABC"
},
"siteCode": "main",
"orderId": "B7025189",
"currency": "USD",
"status": {"value": "ACCEPTED",
"comment": "comment example",
"quoteReason": {"id": "29817428df374918f236951",
"code": "PRICE_TOO_HIGH",
"type": "CHANGE",
"message": {"en": "The price is too high",
"de": "Der Preis ist zu hoch"
}
}
},
"validTo": "2023-03-25T09:36:55.974Z",
"totalPrice": {"netValue": 205,
"grossValue": 225.5,
"taxValue": 20.5
},
"subtotalPrice": {"netValue": 205,
"grossValue": 225.5,
"taxValue": 20.5
},
"taxAggregate": {"lines": [{"name": "STANDARD",
"amount": 20.5,
"rate": 10,
"taxable": 225.5
}
]
},
"shipping": {"value": 10,
"grossValue": 12,
"methodId": "fedex-2dayground",
"zoneId": "63440460ceeaa26d794fcbbb",
"methodName": {"en": "FedEx 2Day",
"pl": "FedEx 2Dni"
},
"shippingTaxCode": "STANDARD"
},
"comment": {"employeeComment": "Employee comment"
},
"billingAddress": {"id": "63440460cee2826d794fcb8a",
"name": "ABC",
"addressLine1": "Street",
"addressLine2": "27a",
"city": "London",
"countryCode": "GB",
"postcode": "32131",
"state": "London"
},
"shippingAddress": {"id": "63440460cee2826d794fcb8a",
"name": "ABC",
"addressLine1": "Street",
"addressLine2": "27a",
"city": "London",
"countryCode": "GB",
"postcode": "32131",
"state": "London"
},
"items": [{"id": "0972ef39-9a4a-4867-b3c1-f8c00f66ee0a",
"quantity": {"quantity": 1,
"unitCode": "piece"
},
"price": {"priceId": "63ec99a2457e8f7548685fe5",
"unitPrice": 34,
"newUnitPrice": 34,
"discount": 0,
"totalNetValue": 34,
"tax": {"taxClass": "STANDARD",
"taxRate": 10,
"prices": {"grossValue": 37.4,
"netValue": 34
}
}
},
"product": {"productId": "BC10033--BC10033-35",
"name": {"de": "Hohe Sicherheitsschuhe Reptile RS S3 SRC, schwarz",
"ar": "حذاء الجريمة المحافظ المرتفع RS S3 SRC ، NERE",
"ru": "Safety shoes high Reptile RS S3 SRC, black",
"th": "Safety shoes high Reptile RS S3 SRC, black",
"en": "Safety shoes high Reptile RS S3 SRC, black",
"it": "Scarpe antinfortunistiche alte Reptile RS S3 SRC, nere",
"fr": "Chaussures de sécurité hautes Reptile RS S3 SRC, noir",
"en-gb": "Safety shoes high Reptile RS S3 SRC, black",
"es": "Zapatos de seguridad altos Reptile RS S3 SRC, negros"
},
"media": {"contentType": "image/jpg",
"url": "https://res.cloudinary.com/saas-ag/image/upload/v1676449882/mrworkerstage/products/82c30154-dcf7-4bb9-b210-d960fec6c9fd.jpg"
},
"taxClasses": {"DE": "STANDARD",
"PL": "ZERO"
}
}
},
{"id": "ac16dd14-baa4-4ccb-bad3-756b36b89235",
"quantity": {"quantity": 3,
"unitCode": "piece"
},
"price": {"priceId": "63ec9ad0457e8f75486861cf",
"unitPrice": 57,
"newUnitPrice": 57,
"totalNetValue": 171,
"tax": {"taxClass": "STANDARD",
"taxRate": 10,
"prices": {"grossValue": 188.1,
"netValue": 171
}
}
},
"product": {"productId": "0601394000",
"name": {"de": "GWS 750 - Kabelgebundener Winkelschleifer 750 W 115 mm",
"ar": "GWS 750 - 750 W 115 مم طاحونة الزاوية",
"ru": "GWS 750 - Corded angle grinder 750 W 115 mm",
"th": "GWS 750 - Corded angle grinder 750 W 115 mm",
"en": "GWS 750 - Corded angle grinder 750 W 115 mm",
"it": "GWS 750 - Smerigliatrice angolare a filo 750 W 115 mm",
"fr": "GWS 750 - Meuleuse d'angle filaire 750 W 115 mm",
"en-gb": "GWS 750 - Corded angle grinder 750 W 115 mm",
"es": "GWS 750 - Amoladora angular con cable 750 W 115 mm"
},
"media": {"contentType": "image/jpg",
"url": "https://res.cloudinary.com/saas-ag/image/upload/v1676450433/mrworkerstage/products/937b1491-e099-46f2-b31a-f7c2f7945f7a.jpg"
},
"taxClasses": {"DE": "STANDARD",
"PL": "ZERO"
}
}
}
],
"mixins": {"customAttributes": {"attribute": {"value": 1,
"unit": "kg"
}
}
},
"metadata": {"mixins": {"customAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/CAAS/customAttributes.json"
},
"version": 1,
"createdAt": "2023-02-23T09:36:55.929Z",
"modifiedAt": "2023-02-23T09:38:49.196Z"
}
}
]

Creating a quote

Generates a new quote, which can be created either manually using a complete quote definition that includes items, or by copying the details from cart.

Required scopes

quote.quote_manage - required for the employee to create a quote
quote.quote_manage_own - required for the customer to be able to create a quote from cart

SecurityOAuth2

Request

path Parameters

tenant

required

string

Your Emporix tenant's name.

Note: The tenant name should always be written in lowercase.

Example: saasdev2

Request Body schema: application/json

One of:

The schema specifies the attributes that must be provided when creating a quote manually.

id	string The ID for a quote can either be manually provided at the time of the quote creation, or is automatically generated if not provided.
customerId required	string The customer ID for which the new quote is created. Either this attribute or the `customerEmail` attribute is required for the quote creation
employeeId	string The employee ID for which the new quote is created. By default, the employeeId is taken from session token, but in case the session token is not provided, employeeId is taken from the payload. Default employee from the configuration will be assigned to the quote in case session token nor 'employeeId' is not provided.
companyName required	string The name of the merchant company.
siteCode required	string The site code for which the quote is created.
currency required	string The currency for which the quote is created.
billingAddressId required	string The ID of the location which should specify the billing address.
shippingAddressId required	string The ID of the location which should specify the shipping address.
validTo	string <date-time> The date until which the quote is valid for the customer. After this date, the quote cannot be approved and transformed into order by the customer.
	object (QuoteShipping) The shipping cost of the quote
	Array of objects Quote items
	object Mixins request
	object Metadata request
customerEmail	string The contact email that identifies the customer. Either this atribute or the `customerId` atribute is mandatory for the quote creation request

Responses

201

The request was successful. The Quote has been created.

400

Unsupported content language provided.

401

Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.

403

Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.

409

Conflict.

post/{tenant}/quotes

Request samples

application/json

{"customerId": "9tt954309b06d46d3cf19fe",
"employeeId": "9tt954309b06d46d3cf19fa",
"billingAddressId": "64672a8f9939d331699cbe6e",
"shippingAddressId": "64672a8f9939d331699cbe6e",
"companyName": "ABC",
"siteCode": "main",
"currency": "USD",
"validTo": "2022-04-01T04:37:04.301Z",
"shipping": {"value": 10,
"methodId": "fedex-2dayground",
"zoneId": "63440460ceeaa26d794fcbbb",
"shippingTaxCode": "STANDARD"
},
"items": [{"quantity": {"quantity": 1,
"unitCode": "piece"
},
"price": {"priceId": "6245aa0a78a8576e338fa9c4",
"unitPrice": 13,
"totalNetValue": 13,
"tax": {"taxClass": "STANDARD",
"taxRate": 20
}
},
"product": {"productId": "7i98542309b06d46d3cf19fe"
}
}
],
"mixins": {"customAttributes": {"attribute": {"value": 1,
"unit": "kg"
}
}
},
"metadata": {"mixins": {"customAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/CAAS/customAttributes.json"
}
}
}

Response samples

application/json

{"id": "e241dc9e-a3f6-4573-bb01-a8ae21d2d4ae"
}

Retrieving a single quote

Retrieves a quote by a given id.

Required scopes

quote.quote_read - allows employees to retrieve any quote
quote.quote_read_own - allows customers to retrieve their own quote

SecurityOAuth2

Request

path Parameters

tenant required	string Your Emporix tenant's name. Note: The tenant name should always be written in lowercase. Example: saasdev2
quoteId required	string Quote unique identifier generated when the quote is created. Example: 084bcaf5-66b8-4ddd-9489-65c5f6449e94

header Parameters

Accept-Language

string

If the header is set to a particular language or a list of languages, all localized fields are retrieved as strings.
If the header is set to *, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.
If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.

Responses

200

400

Unsupported language provided.

401

Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.

403

Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.

404

Given resource cannot be found.

get/{tenant}/quotes/{quoteId}

Request samples

Response samples

application/json

{"id": "5b3188dc-9a5c-4163-8756-4f228c295a59",
"customer": {"customerId": "72318750",
"firstName": "Stefan",
"lastName": "Muller",
"contactEmail": "s.muller@emporix.com"
},
"employee": {"employeeId": "00u6fo3yzjE8Q7X0d417",
"firstName": "John",
"lastName": "Smith"
},
"cartId": "63ee5168e55c231c327220d3",
"company": {"name": "The best company"
},
"siteCode": "main",
"orderId": "B7025189",
"currency": "USD",
"status": {"value": "ACCEPTED",
"comment": "comment example",
"quoteReason": {"id": "29817428df374918f236951",
"code": "PRICE_TOO_HIGH",
"type": "CHANGE",
"message": {"en": "The price is too high",
"de": "Der Preis ist zu hoch"
}
},
"validTo": "2023-03-25T09:36:55.974Z"
},
"comment": {"employeeComment": "Employee comment"
},
"validTo": "2023-03-25T09:36:55.974Z",
"totalPrice": {"netValue": 205,
"grossValue": 225.5,
"taxValue": 20.5
},
"subtotalPrice": {"netValue": 205,
"grossValue": 225.5,
"taxValue": 20.5
},
"taxAggregate": {"lines": [{"name": "STANDARD",
"amount": 20.5,
"rate": 10,
"taxable": 225.5
}
]
},
"shipping": {"value": 10,
"grossValue": 12,
"methodId": "fedex-2dayground",
"zoneId": "63440460ceeaa26d794fcbbb",
"methodName": {"en": "FedEx 2Day",
"pl": "FedEx 2Dni"
},
"shippingTaxCode": "STANDARD"
},
"billingAddress": {"id": "63440460cee2826d794fcb8a",
"name": "ABC",
"addressLine1": "Street",
"addressLine2": "27a",
"city": "London",
"countryCode": "GB",
"postcode": "32131",
"state": "London"
},
"shippingAddress": {"id": "63440460cee2826d794fcb8a",
"name": "ABC",
"addressLine1": "Street",
"addressLine2": "27a",
"city": "London",
"countryCode": "GB",
"postcode": "32131",
"state": "London"
},
"items": [{"id": "0972ef39-9a4a-4867-b3c1-f8c00f66ee0a",
"quantity": {"quantity": 1,
"unitCode": "piece"
},
"price": {"priceId": "63ec99a2457e8f7548685fe5",
"unitPrice": 34,
"newUnitPrice": 34,
"discount": 0,
"totalNetValue": 34,
"tax": {"taxClass": "STANDARD",
"taxRate": 10,
"prices": {"grossValue": 37.4,
"netValue": 34
}
}
},
"product": {"productId": "BC10033--BC10033-35",
"name": {"de": "Hohe Sicherheitsschuhe Reptile RS S3 SRC, schwarz",
"ar": "حذاء الجريمة المحافظ المرتفع RS S3 SRC ، NERE",
"ru": "Safety shoes high Reptile RS S3 SRC, black",
"th": "Safety shoes high Reptile RS S3 SRC, black",
"en": "Safety shoes high Reptile RS S3 SRC, black",
"it": "Scarpe antinfortunistiche alte Reptile RS S3 SRC, nere",
"fr": "Chaussures de sécurité hautes Reptile RS S3 SRC, noir",
"en-gb": "Safety shoes high Reptile RS S3 SRC, black",
"es": "Zapatos de seguridad altos Reptile RS S3 SRC, negros"
},
"media": {"contentType": "image/jpg",
"url": "https://res.cloudinary.com/saas-ag/image/upload/v1676449882/mrworkerstage/products/82c30154-dcf7-4bb9-b210-d960fec6c9fd.jpg"
},
"taxClasses": {"DE": "STANDARD",
"PL": "ZERO"
}
}
},
{"id": "ac16dd14-baa4-4ccb-bad3-756b36b89235",
"quantity": {"quantity": 3,
"unitCode": "piece"
},
"price": {"priceId": "63ec9ad0457e8f75486861cf",
"unitPrice": 57,
"newUnitPrice": 57,
"totalNetValue": 171,
"tax": {"taxClass": "STANDARD",
"taxRate": 10,
"prices": {"grossValue": 188.1,
"netValue": 171
}
}
},
"product": {"productId": "0601394000",
"name": {"de": "GWS 750 - Kabelgebundener Winkelschleifer 750 W 115 mm",
"ar": "GWS 750 - 750 W 115 مم طاحونة الزاوية",
"ru": "GWS 750 - Corded angle grinder 750 W 115 mm",
"th": "GWS 750 - Corded angle grinder 750 W 115 mm",
"en": "GWS 750 - Corded angle grinder 750 W 115 mm",
"it": "GWS 750 - Smerigliatrice angolare a filo 750 W 115 mm",
"fr": "GWS 750 - Meuleuse d'angle filaire 750 W 115 mm",
"en-gb": "GWS 750 - Corded angle grinder 750 W 115 mm",
"es": "GWS 750 - Amoladora angular con cable 750 W 115 mm"
},
"media": {"contentType": "image/jpg",
"url": "https://res.cloudinary.com/saas-ag/image/upload/v1676450433/mrworkerstage/products/937b1491-e099-46f2-b31a-f7c2f7945f7a.jpg"
},
"taxClasses": {"DE": "STANDARD",
"PL": "ZERO"
}
}
}
],
"mixins": {"customAttributes": {"attribute": {"value": 1,
"unit": "kg"
}
}
},
"metadata": {"mixins": {"customAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/CAAS/customAttributes.json"
},
"version": 1,
"createdAt": "2023-02-23T09:36:55.929Z",
"modifiedAt": "2023-02-23T09:38:49.196Z"
}
}

Partially updating a quote

Partially updates a quote with a given Id. Single update may contain multiple partial updates in the form of an array. It contains the allowed operations list:

add (adding an item to the items list)
remove (removing an item from the items list)
replace (replacing an item with given id with new definition which may contain custom price proposal or defined price)

After events are saved, some of the information is retrieved in the async way from other services: full price definition is based on the provided price ID, and the full product name is based on the provided product ID.

Required scopes

quote.quote_manage - allows employees or external api calls to modify all quotes
quote.quote_manage_own - allows customers to modify only their own quotes by modifying the status to either ACCEPTED or DECLINED.

SecurityOAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ The tenant that the caller is acting upon Note: This value must always be provided in lowercase.
quoteId required	string Quote unique identifier generated when the quote is created

Request Body schema: application/json

Array

op required	string Enum: "ADD" "REMOVE" "REPLACE"
path required	string Enum: "/status" "/validTo" "/comment" "/billingAddressId" "/shippingAddressId" "/companyName" "/customerId" "/shipping" "/items" "/items/{itemId}" "/items/{itemId}/price" "/mixins/{mixinsPath}" "/metadata/{mixinsPath}"
	QuoteItemUpdate (object) or Array of QuoteItemsReplaceUpdate (objects) or QuoteItemUpdatePrice (object) or QuoteUpdateStatus (object) or QuoteShipping (object) or Array of QuoteItemIds (objects) or string or object (QuoteUpdateValues)

Responses

204

The request was successful. The quote has been updated.

400

Unsupported content language provided.

401

Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.

403

Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.

404

Given resource cannot be found.

patch/{tenant}/quotes/{quoteId}

Request samples

application/json

[{"op": "ADD",
"path": "/items",
"value": {"itemId": "2298854309b06d4c6d3cf1zfe",
"quantity": {"quantity": 1,
"unitCode": "H87"
},
"price": {"priceId": "14551d2309b06sd46d3cf19bq",
"unitPrice": 13,
"totalNetValue": 13,
"tax": {"taxClass": "STANDARD",
"taxRate": 20
}
},
"product": {"productId": "74698542309b06dc46d3cf19fe"
}
}
},
{"op": "REPLACE",
"path": "/status",
"value": {"value": "OPEN",
"comment": "new comment"
}
},
{"op": "REPLACE",
"path": "/items/22988s54309b06d46d3acf19fe",
"value": {"quantity": {"quantity": 1,
"unitCode": "H87"
},
"price": {"priceId": "14551d2309b06sd46d3cf19bq",
"unitPrice": 13,
"totalNetValue": 13,
"tax": {"taxClass": "STANDARD",
"taxRate": 20
}
},
"product": {"productId": "74698542309b06dc46d3cf19fe"
}
}
},
{"op": "REMOVE",
"path": "/items/124dfa82410fas824kfa"
}
]

Response samples

application/json

{"code": 400,
"status": "Bad Request",
"message": "Language header validation failed",
"details": ["Following languages are not supported: 'ru'"
]
}

Deleting a quote

Deletes a quote with a given quote Id.

Required scopes

quote.quote_manage - the quote can be deleted by an employee

SecurityOAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ The tenant that the caller is acting upon Note: This value must always be provided in lowercase.
quoteId required	string Quote unique identifier generated when the quote is created

Responses

204

Quote has been deleted successfully.

401

Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.

403

Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.

delete/{tenant}/quotes/{quoteId}

Request samples

Response samples

application/json

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

Quote history

Retrieving quote history

Retrieves changes related to a quote with a given ID.

Required scopes

quote.quote_read - allows employees to retrieve history of any quote

SecurityOAuth2

Request

path Parameters

tenant required	string Your Emporix tenant's name. Note: The tenant name should always be written in lowercase. Example: saasdev2
quoteId required	string Quote unique identifier generated when the quote is created. Example: 084bcaf5-66b8-4ddd-9489-65c5f6449e94

header Parameters

X-Total-Count

boolean

Default: false

Flag indicating whether the total number of retrieved items should be returned.

Example: true

Responses

200

The request was successful. Quote details are returned.

401

Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.

403

Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.

get/{tenant}/quotes/{quoteId}/history

Request samples

Response samples

application/json

[{"id": "6447b45cac0475131f3a6261",
"op": "ADD",
"path": "/items",
"newValue": {"itemId": "2298854309b06d4c6d3cf1zfe",
"quantity": {"quantity": 1,
"unitCode": "H87"
},
"price": {"priceId": "14551d2309b06sd46d3cf19bq",
"unitPrice": 13,
"totalNetValue": 13,
"tax": {"taxClass": "STANDARD",
"taxRate": 20
},
"product": {"productId": "74698542309b06dc46d3cf19fe"
}
}
},
"userId": "7777i52309521897214",
"userFirstName": "Robin",
"userLastName": "Fritz",
"userType": "EMPLOYEE",
"modifiedAt": "2024-04-02T13:06:15.280Z"
},
{"id": "6447b45cac0475131f3a6262",
"op": "REPLACE",
"path": "/status",
"newValue": {"value": "OPEN"
},
"previousValue": {"value": "AWAITING"
},
"userId": "612ji52309521897214",
"userFirstName": "Robin",
"userLastName": "Fritz",
"userType": "EMPLOYEE",
"modifiedAt": "2024-04-02T13:06:15.280Z"
},
{"id": "6447b45cac0475131f3a6263",
"op": "REPLACE",
"path": "/validTo",
"newValue": "2025-04-02T13:06:15.280Z",
"previousValue": "2023-04-02T13:06:15.280Z",
"userId": "612ji52309521897214",
"userFirstName": "Stefan",
"userLastName": "Muller",
"userType": "EMPLOYEE",
"modifiedAt": "2024-04-02T13:06:15.280Z"
},
{"id": "6447b45cac0475131f3a6264",
"op": "REPLACE",
"path": "/items/2298854309b06d46d3cf19fe",
"previousValue": {"itemId": "2298854309b06d4c6d3cf1zfe",
"quantity": {"quantity": 1,
"unitCode": "H87"
},
"price": {"priceId": "14551d2309b06sd46d3cf19bq",
"unitPrice": 13,
"totalNetValue": 13,
"tax": {"taxClass": "STANDARD",
"taxRate": 20
},
"product": {"productId": "74698542309b06dc46d3cf19fe"
}
}
},
"newValue": {"itemId": "2298854309b06d4c6d3cf1zfe",
"quantity": {"quantity": 2,
"unitCode": "H87"
},
"price": {"priceId": "14551d2309b06sd46d3cf19bq",
"unitPrice": 14,
"totalNetValue": 14,
"tax": {"taxClass": "STANDARD",
"taxRate": 21
},
"product": {"productId": "74698542309b06dc46d3cf1fff"
}
}
},
"userId": "5577i52309521897214",
"userFirstName": "Mark",
"userLastName": "Schmidt",
"userType": "EMPLOYEE",
"modifiedAt": "2024-04-02T13:06:15.280Z"
},
{"id": "6447b45cac0475131f3a6261",
"op": "REMOVE",
"path": "/items/124dfa82410fas824kfa",
"previousValue": {"itemId": "2298854309b06d4c6d3cf1zfe",
"quantity": {"quantity": 1,
"unitCode": "H87"
},
"price": {"priceId": "14551d2309b06sd46d3cf19bq",
"unitPrice": 13,
"totalNetValue": 13,
"tax": {"taxClass": "STANDARD",
"taxRate": 20
},
"product": {"productId": "74698542309b06dc46d3cf19fe"
}
}
},
"userId": "612ji52309521897214",
"userFirstName": "Stefan",
"userLastName": "Muller",
"userType": "EMPLOYEE",
"modifiedAt": "2024-04-02T13:06:15.280Z"
}
]

Quote pdf

Creating a quote PDF

Generates a pdf for a given quote and returns its contents.

Required scopes

quote.quote_read - allows to generate a PDF for any quote
quote.quote_manage - allows to generate a PDF for any quote
quote.quote_manage_own - allows to generate a PDF for own quote

SecurityOAuth2

Request

path Parameters

tenant required	string Your Emporix tenant's name. Note: The tenant name should always be written in lowercase. Example: saasdev2
quoteId required	string Quote unique identifier generated when the quote is created. Example: 084bcaf5-66b8-4ddd-9489-65c5f6449e94

header Parameters

Accept-Language

string

If the header is set to a particular language or a list of languages, all localized fields are retrieved as strings.
If the header is set to *, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.
If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.

Responses

200

The request was successful. Generated pdf is returned.

400

Unsupported language provided.

401

Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.

403

Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.

404

Given resource cannot be found.

post/{tenant}/quotes/{quoteId}/pdf

Request samples

Response samples

application/json

{"code": 400,
"status": "Bad Request",
"message": "Language header validation failed",
"details": ["Following languages are not supported: 'ru'"
]
}

Quote reason

Creating a reason for changing the quote status

Creating reasons for the 'CHANGE' or 'DECLINE' types of quote statuses. The reason for the quote status change serves to provide more descriptive information why the status has been changed. This option is available both for merchants and customers, depending on who updates the status of the quote.

Required scopes

quote.quote_manage

SecurityOAuth2

Request

path Parameters

tenant

required

string

Your Emporix tenant's name.

Note: The tenant name should always be written in lowercase.

Example: saasdev2

header Parameters

Content-Language

required

string

The Content-Language request HTTP header defines language(s) of the payload.

Example: de

Request Body schema: application/json

id	string The ID for a quote reason can either be manually provided at the time of the quote reason creation, or is automatically generated if not provided.
type required	string Type of the quote reason. Enum: "CHANGE" "DECLINE"
code required	string Code of the reason for the quote status change.
required	object Localized message in the form of a map of translations.

Responses

201

The request was successful. Quote reason was created and its id is returned.

400

Unsupported language provided.

401

Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.

403

Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.

409

Conflict.

post/{tenant}/quote-reasons

Request samples

application/json

{"code": "PRICE_TOO_HIGH",
"type": "CHANGE",
"message": {"en": "The price is too high",
"de": "Der Preis ist zu hoch"
}
}

Response samples

application/json

{"id": "642c1ff3c78f9b2958d17c18"
}

Retrieving reasons for changing the quote status

Retrieves a full list of reasons for changing the quote status with details.

Required scopes

quote.quote_read
quote.quote_read_own

SecurityOAuth2

Request

path Parameters

tenant

required

string

Your Emporix tenant's name.

Note: The tenant name should always be written in lowercase.

Example: saasdev2

query Parameters

pageSize	integer >= 1 Default: 60 Number of items to be retrieved per page.
pageNumber	integer >= 1 Default: 1 Page number to be retrieved. The number of the first page is 1.
sort	string List of properties used to sort the results, separated by colons. The order of properties indicates their priority in sorting. Possible values: `{fieldName}` `{fieldName}:asc` `{fieldName}:desc` Note: If you want to sort the results by localized properties, the possible values are: `{fieldName}.{language}` `{fieldName}.{language}:asc` `{fieldName}.{language}:desc` If the sorting direction is not specified, the fields are sorted in ascending order.
q	string A standard query parameter is used to search for specific values. Searching for items by string-based properties: By a field value: `q=siteCode:main`, where `siteCode` is the field name, and `main` is its desired value. By a localized field value: `q=items.product.name.en:apple_lobo`, where `name` is the field name of product, `en` is the language code, and `apple_lobo` is the field value expressed in the specified language. Note: This query works only for localized fields, which are stored in a map format, where `key` is the language code and `value` is the translation to particular language. Searching for items by a number-based property: With a specific value: `q=items.quantity.quantity:20` With a value greater than: `q=items.quantity.quantity:>20` With a value lower than: `q=items.quantity.quantity:<20` With a value greater than or equal to: `q=items.quantity.quantity:>=20` With a value lower than or equal to: `q=items.quantity.quantity:<=20` With a value within a range of values: `q=items.quantity.quantity:(>=10 AND <=20)` where `items.quantity.quantity` is the name of the number-based field, and `20` is its querying value. Searching for items by a date-based property: All numer-based property queries are also valid for dates. In that case, the date should be placed within double quotes: `q=metadataCreatedAt:(>="2021-05-18T07:27:27.455Z" AND <"2021-05-20T07:27:27.455Z")` Searching for items by a boolean-based property: `q=description.multiLanguage:true`, where `description.multiLanguage` is the boolean field name, and `true` is its desired value. Searching for items with a nonexistent or empty property: `q=description.en:null`, where `description.en` is the field that has its value set to `null`. Searching for items with an existing property: `q=mixin:exists`, where `mixin` is the field that has a non-empty value. Searching for items by multiple specific values: `q=id:(5c3325baa9812100098ff48f,5c3325d1a9812100098ff494)`, where `id` is the field name, and strings within the bracket are the desired values. Searching for items by multiple fields: `q=id:5c3325baa9812100098ff48f siteCode:main` where `id` and `siteCode` are field names. All objects that contain the specified values are returned. Multiple fields (separated by space) can be specified. Multiple values for each field can also be specified in the format presented earlier. Searching for items with string-based properties conforming to a regex: `q=siteCode:~ain` or `q=code:(~U PL)` - in case of searching for strings with space, where `siteCode` is the name of the field, and `ain` or `U PL` is its querying regex. Searching for items with a localized string-based property conforming to a regex: `items.product.name.en:~(Joghurt im)` - where `name` is the product field name, `en` is the desired language, and `Joghurt im` is the search term. Example: q=siteCode:{main}
fields	string Fields to be returned in the response. When this parameter is passed, only the `id` and `{fieldName}` are retrieved for each entry. You can specify multiple fields by separating them with commas. Example: fields=code,message

header Parameters

Accept-Language

string

If the header is set to a particular language or a list of languages, all localized fields are retrieved as strings.
If the header is set to *, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.
If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.

X-Total-Count

boolean

Default: false

Flag indicating whether the total number of retrieved items should be returned.

Example: true

Responses

200

400

Unsupported language provided.

401

Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.

403

Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.

get/{tenant}/quote-reasons

Request samples

Response samples

application/json

[{"id": "642c1ff3c78f9b2958d17c18",
"code": "PRICE_TOO_HIGH",
"message": {"en": "The price is too high",
"de": "Der Preis ist zu hoch"
},
"type": "CHANGE",
"metadata": {"version": 1,
"createdAt": "2023-02-23T09:36:55.929Z",
"modifiedAt": "2023-02-23T09:38:49.196Z"
}
}
]

Retrieving a quote reason

Retrieves a quote reason with details by its unique identifier.

Required scopes

quote.quote_read
quote.quote_read_own

SecurityOAuth2

Request

path Parameters

tenant required	string Your Emporix tenant's name. Note: The tenant name should always be written in lowercase. Example: saasdev2
quoteReasonId required	string Quote reason unique identifier generated when the quote reason is created. Example: 642c1ff3c78f9b2958d17c18

header Parameters

Accept-Language

string

If the header is set to a particular language or a list of languages, all localized fields are retrieved as strings.
If the header is set to *, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.
If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.

Responses

200

400

Unsupported language provided.

401

Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.

403

Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.

404

Given resource cannot be found.

get/{tenant}/quote-reasons/{quoteReasonId}

Request samples

Response samples

application/json

{"id": "642c1ff3c78f9b2958d17c18",
"code": "PRICE_TOO_HIGH",
"message": {"en": "The price is too high",
"de": "Der Preis ist zu hoch"
},
"type": "CHANGE",
"metadata": {"version": 1,
"createdAt": "2023-02-23T09:36:55.929Z",
"modifiedAt": "2023-02-23T09:38:49.196Z"
}
}

Updating the reason for changing the quote status

Updating the reason for changing the quote status.

Required scopes

quote.quote_manage

SecurityOAuth2

Request

path Parameters

tenant required	string Your Emporix tenant's name. Note: The tenant name should always be written in lowercase. Example: saasdev2
quoteReasonId required	string Quote reason unique identifier generated when the quote reason is created. Example: 642c1ff3c78f9b2958d17c18

header Parameters

Content-Language

required

string

The Content-Language request HTTP header defines language(s) of the payload.

Example: de

Request Body schema: application/json

type required	string Type of the quote reason. Enum: "CHANGE" "DECLINE"
code required	string Code of the reason for the quote status change.
required	object Localized message in the form of a map of translations.
required	object The Quote Reason metadata details

Responses

204

The request was successful. Quote reason has been updated.

400

Unsupported language provided.

401

Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.

403

Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.

404

Given resource cannot be found.

409

Conflict.

put/{tenant}/quote-reasons/{quoteReasonId}

Request samples

application/json

{"code": "PRICE_TOO_HIGH",
"type": "CHANGE",
"message": {"en": "The price is too high",
"de": "Der Preis ist zu hoch"
},
"metadata": {"version": 1
}
}

Response samples

application/json

{"code": 400,
"status": "Bad Request",
"message": "Language header validation failed",
"details": ["Following languages are not supported: 'ru'"
]
}

Deleting the reason for changing the quote status

Deletes the reason provided for the quote status change with a specific reason ID.

Required scopes

quote.quote_manage - the quote reason can be deleted by an employee

SecurityOAuth2

Request

path Parameters

tenant required	string Your Emporix tenant's name. Note: The tenant name should always be written in lowercase. Example: saasdev2
quoteReasonId required	string Quote reason unique identifier generated when the quote reason is created. Example: 642c1ff3c78f9b2958d17c18

Responses

204

Quote reason has been deleted successfully.

401

Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.

403

Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.

delete/{tenant}/quote-reasons/{quoteReasonId}

Request samples

Response samples

application/json

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