# Approvals
## Retrieving a list of approvals
> Retrieves a list of approval documents assigned to the user. The user must be a \*Requestor\* or an \*Approver\* to have the required \`approval.approval\_read\_own\` scope.
```json
{"openapi":"3.0.0","info":{"title":"Approval Service","version":"0.0.1"},"tags":[{"name":"Approvals"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"CustomerAccessToken":[]}],"components":{"securitySchemes":{"CustomerAccessToken":{"type":"http","scheme":"bearer","description":"To generate a customer access token, go to the [Logging in a customer](https://developer.emporix.io/api-references/api-guides/companies-and-customers/customer-management/api-reference/authentication-and-authorization#post-customer-tenant-login) endpoint."}},"responses":{"listOfApprovalsResponse_200":{"description":"Example response.","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/getApprovalResponse"},"type":"array"}}}},"common_response_Unauthorized_401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"common_response_Forbidden_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coreErrorMessage"}}}}},"schemas":{"getApprovalResponse":{"title":"An approval response","allOf":[{"$ref":"#/components/schemas/basicApproval"},{"type":"object","description":"Base schema for an approval response.","properties":{"id":{"type":"string","description":"An identifier of the approval document."},"approverComment":{"type":"string","description":"A comment from an approver user."},"resource":{"$ref":"#/components/schemas/resourceResponse"},"requestor":{"$ref":"#/components/schemas/user"},"approver":{"$ref":"#/components/schemas/user"},"status":{"$ref":"#/components/schemas/approvalStatus"},"expiryDate":{"$ref":"#/components/schemas/expiryDate"},"metadata":{"$ref":"#/components/schemas/metadata"}}}]},"basicApproval":{"title":"basicApproval","description":"Base schema for an approval.","allOf":[{"$ref":"#/components/schemas/genericApprovalForCreate"},{"type":"object","properties":{"resourceType":{"$ref":"#/components/schemas/resourceType"},"details":{"$ref":"#/components/schemas/details"}}}],"required":["resourceType","action","approver"]},"genericApprovalForCreate":{"title":"basicApproval","description":"Base schema for an approval creation.","type":"object","properties":{"action":{"$ref":"#/components/schemas/approvalAction"},"approver":{"type":"object","description":"User who can approve the approval request.","properties":{"userId":{"type":"string","description":"Identifier of the user."}}},"comment":{"type":"string","description":"A comment from the requestor to the approver."}},"required":["action","approver"]},"approvalAction":{"title":"An approval action","description":"Base schema for an approval action type.","type":"string","enum":["CHECKOUT"]},"resourceType":{"title":"A type of a resource","description":"Type of resource under approval. \n","type":"string","enum":["CART","QUOTE"]},"details":{"type":"object","title":"additional information","description":"Checkout details for **cart** approvals. **Required** when `resourceType` is `CART`.\n","properties":{"shipping":{"$ref":"#/components/schemas/shipping"},"payment":{"$ref":"#/components/schemas/payment"},"paymentMethods":{"description":"Methods chosen to process the payment for the order.","type":"array","items":{"$ref":"#/components/schemas/paymentMethod"}},"currency":{"type":"string","description":"Three-letter currency code, compliant with the ISO 4217 standard."},"addresses":{"type":"array","uniqueItems":true,"minItems":1,"description":"List of addresses associated with the order.","items":{"$ref":"#/components/schemas/address"}}}},"shipping":{"type":"object","title":"Shipping information","description":"Information about the shipping.","additionalProperties":false,"properties":{"methodId":{"type":"string","description":"Shipping method's unique identifier.","minLength":0},"zoneId":{"type":"string","description":"Shipping zone identifier.","minLength":0},"methodName":{"type":"string","description":"Shipping method chosen by the customer.","minLength":0},"amount":{"type":"number","minimum":0,"description":"Shipping net cost."},"shippingTaxCode":{"type":"string","description":"The tax code of the shipping."}}},"payment":{"type":"object","description":"Information about the payment.","title":"Payment information","additionalProperties":false,"properties":{"paymentId":{"type":"string","minLength":0},"customAttributes":{"type":"object"}}},"paymentMethod":{"type":"object","additionalProperties":false,"properties":{"provider":{"type":"string","description":"Payment provider, possible values: \n * `payment-gateway` - When the Emporix Payment-Gateway service should be used to handle a payment. For details about custom attributes that are required for a particular payment mode, check https://developer.emporix.io/user-guides/system-management/payment-gateway/payments. \n * `custom` - When a custom provider is used. In this case the created order has the `IN_CHECKOUT` status.\n * `none` - For payment by cash or invoice.\n","minLength":0},"customAttributes":{"type":"object","description":"Additional information about the payment method.","properties":{"token":{"type":"string","description":"Payment token used for the tokenized credit card flows. The field is used when provider type is `payment-gateway`. For more details, check https://developer.emporix.io/user-guides/system-management/payment-gateway/payments"},"modeId":{"type":"string","description":"Identifier of a payment mode. The payment mode has to be configured in the Emporix Payment Gateway service beforehand. For more details, check https://developer.emporix.io/user-guides/system-management/payment-gateway/payments"},"paymentType":{"type":"string","description":"Payment type chosen by the customer, for example `paymentByCredit` or `paymentByDebit`."}}},"method":{"type":"string","description":"Payment method chosen by the customer, for example `invoice` or `cash-on-delivery`."},"amount":{"type":"number","description":"Amount to be paid by the customer."}}},"address":{"type":"object","description":"Information about the customer address.","properties":{"contactName":{"type":"string","minLength":0},"companyName":{"type":"string"},"street":{"type":"string","minLength":0},"streetNumber":{"type":"string"},"streetAppendix":{"type":"string"},"zipCode":{"type":"string","maxLength":11,"minLength":0},"city":{"type":"string","minLength":0},"country":{"type":"string","minLength":1},"state":{"type":"string"},"contactPhone":{"type":"string"},"type":{"type":"string","description":"Type of the address data, for example `BILLING` or `SHIPPING`.","enum":["SHIPPING","BILLING"]}}},"resourceResponse":{"title":"Resource","description":"Resource of the approval.","type":"object","properties":{"id":{"type":"string","description":"The identifier of the resource."},"items":{"type":"array","items":{"$ref":"#/components/schemas/resourceItem"}},"totalPrice":{"$ref":"#/components/schemas/price"},"subTotalPrice":{"$ref":"#/components/schemas/price"},"subtotalAggregate":{"$ref":"#/components/schemas/taxablePrice"},"siteCode":{"type":"string","description":"Name of the site."},"deliveryWindow":{"$ref":"#/components/schemas/deliveryWindow"}}},"resourceItem":{"title":"Resource item","description":"Item of the resource.","type":"object","properties":{"quantity":{"type":"number","description":"Quantity of the given item."},"itemPrice":{"$ref":"#/components/schemas/resourceItemPrice"},"itemYrn":{"deprecated":true,"type":"string","description":"YRN which identifies the product."},"itemId":{"type":"string","description":"Line-item identifier (e.g. quote line id)."}}},"resourceItemPrice":{"title":"Resource item price","description":"Per-line price; used for resource line items.","type":"object","properties":{"currency":{"type":"string","description":"Currency of the price."},"amount":{"type":"number","deprecated":true,"description":"Deprecated; prefer `unitPrice`, `newUnitPrice`, or `calculatedPrice`."},"unitPrice":{"type":"number","description":"Unit net price before adjustments."},"newUnitPrice":{"type":"number","description":"Unit net price after adjustments (valid for quote line items)."},"calculatedPrice":{"$ref":"#/components/schemas/calculatedPrice"}}},"calculatedPrice":{"title":"Calculated price breakdown","type":"object","properties":{"price":{"type":"object","properties":{"netValue":{"description":"Net value of the price.","type":"number"},"grossValue":{"type":"number","description":"Gross value of the price."},"taxValue":{"description":"Tax value of the price.","type":"number"}}}}},"price":{"title":"Price value","description":"Aggregated price (totals, subtotals) with currency and optional tax breakdown.","type":"object","properties":{"currency":{"type":"string","description":"Currency of the price."},"amount":{"type":"number","deprecated":true,"description":"Deprecated; use `netValue`, `grossValue`, and `taxValue` when present."},"netValue":{"type":"number","description":"Net value of the price."},"grossValue":{"type":"number","description":"Gross value of the price."},"taxValue":{"type":"number","description":"Tax value of the price."}}},"taxablePrice":{"title":"Taxable price value","description":"Price value with the currency and tax information.","type":"object","properties":{"currency":{"type":"string","description":"Currency of the price."},"netValue":{"type":"number","description":"Net value of the price."},"grossValue":{"type":"number","description":"Gross value of the price."},"taxValue":{"type":"number","description":"Tax value of the price."}}},"deliveryWindow":{"title":"Delivery Window","description":"delivery window required for order.","type":"object","properties":{"id":{"type":"string","description":"Identifier of the delivery window."},"slotId":{"type":"string","description":"Identifier of the slot."},"deliveryDate":{"type":"string","description":"Delivery date."}}},"user":{"title":"user schema","type":"object","properties":{"userId":{"type":"string","description":"An identifier of the user."},"firstName":{"type":"string","description":"First name of the user."},"lastName":{"type":"string","description":"Last name of the user."}},"required":["userId","firstName","lastName"]},"approvalStatus":{"title":"A status of the approval","description":"Base schema for the approval status.","type":"string","enum":["PENDING","APPROVED","CLOSED","EXPIRED","DECLINED"]},"expiryDate":{"title":"An expiration date","description":"An expiration date which defines when the approval will expire. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-31T13:18:02.379Z`","type":"string"},"metadata":{"allOf":[{"$ref":"#/components/schemas/basicMetadata"},{"type":"object","properties":{"createdAt":{"description":"Date and time when the object was created. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-31T13:18:02.379Z`","type":"string"},"modifiedAt":{"description":"Date and time when the object was last modified. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-31T13:18:02.379Z`","type":"string"}}}],"required":["createdAt","modifiedAt","version"]},"basicMetadata":{"type":"object","properties":{"version":{"minimum":1,"type":"integer","description":"Version of the object. The version is required during the update operation because of the optimistic locking mechanism."}},"required":["version"]},"coreErrorMessage":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Error message."},"errorCode":{"type":"string","description":"code of the error."},"details":{"description":"Details information.","type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}}}},"parameters":{"x_total_count_header":{"name":"X-Total-Count","in":"header","required":false,"schema":{"type":"boolean"},"description":"To get information how many entities meet the filtering requirements, the `X-Total-Count` header has been introduced. The header is optional and its default value is `false`. If the header is provided and it is set to `true`, then the total count is approved in the `X-Total-Count` response header. In both cases (X-Total-Count `true`, `false` or not provided), the response body has the same format (array of entities). This means that the information about the total count is approved only on demand, provided that the X-Total-Count header is present in a request."},"page_size_query_param":{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","default":60,"minimum":1,"maximum":60},"description":"The number of documents being retrieved on one page."},"page_number_query_param":{"name":"pageNumber","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"The page number to be retrieved, where the size of the pages is specified by the `pageSize` parameter. The number of the first page is 1."},"sort_query_param":{"name":"sort","in":"query","required":false,"schema":{"type":"string"},"description":"Fields to sort the response data by following the order of the parameters from left to right. Can contain multiple fields in the following format: `field name:sort direction`, separated by a comma. The colon preceding the `sort direction` parameter is optional, and the descending order is taken only if it is equal to `desc` or `DESC`. The ascending order is assumed in any other case."},"q_query_param":{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"A standard query parameter is used to search for specific values.\n\nSee: [Standard Practices - Query parameter](https://developer.emporix.io/docs/content/q-param)\n"}}},"paths":{"/approval/{tenant}/approvals":{"get":{"summary":"Retrieving a list of approvals","operationId":"GET-approval-list-approvals","responses":{"200":{"$ref":"#/components/responses/listOfApprovalsResponse_200"},"401":{"$ref":"#/components/responses/common_response_Unauthorized_401"},"403":{"$ref":"#/components/responses/common_response_Forbidden_403"}},"tags":["Approvals"],"description":"Retrieves a list of approval documents assigned to the user. The user must be a *Requestor* or an *Approver* to have the required `approval.approval_read_own` scope.\n","parameters":[{"$ref":"#/components/parameters/x_total_count_header"},{"$ref":"#/components/parameters/page_size_query_param"},{"$ref":"#/components/parameters/page_number_query_param"},{"$ref":"#/components/parameters/sort_query_param"},{"$ref":"#/components/parameters/q_query_param"}]}}}}
```
## Creating a single approval
> Creates a single approval document with information about the approver, resource type and resource identifier.\
> \
> \- \*\*\`resourceType: CART\`\*\*: \`details\` is \*\*required\*\* (shipping, addresses, currency, payment methods, etc.).\
> \- \*\*\`resourceType: QUOTE\`\*\*: \`details\` must be \*\*omitted\*\*; the service loads quote data using \`resourceId\`.\
> \
> The user must be a \*Requestor\* or an \*Approver\* to have the required \`approval.approval\_manage\_own\` scope.\
> \
> In case of any validation problems, the below \`errorCodes\` can be returned:\
> \- \*\*APPROVAL-400003\*\*: Incorrect value of the approval status\
> \- \*\*APPROVAL-400004\*\*: Not matching combination of approval action and resource type \
> \- \*\*APPROVAL-400005\*\*: Approval has been already given\
> \- \*\*APPROVAL-400006\*\*: Provided approver cannot be assigned to the approval\
> \- \*\*APPROVAL-400008\*\*: Requested user has no permissions to the resource\
> \- \*\*APPROVAL-400011\*\*: Requested user is not assigned to any company\
> \- \*\*APPROVAL-404002\*\*: Provided resource does not exist\
> \- \*\*APPROVAL-404003\*\*: Requested user is not assigned to any legal entity\
> \- \*\*APPROVAL-409001\*\*: Approval already exists
```json
{"openapi":"3.0.0","info":{"title":"Approval Service","version":"0.0.1"},"tags":[{"name":"Approvals"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"CustomerAccessToken":[]}],"components":{"securitySchemes":{"CustomerAccessToken":{"type":"http","scheme":"bearer","description":"To generate a customer access token, go to the [Logging in a customer](https://developer.emporix.io/api-references/api-guides/companies-and-customers/customer-management/api-reference/authentication-and-authorization#post-customer-tenant-login) endpoint."}},"schemas":{"approvalId":{"title":"approvalId","type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the created approval."}}},"coreErrorMessage":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Error message."},"errorCode":{"type":"string","description":"code of the error."},"details":{"description":"Details information.","type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}}},"createCartApprovalRequest":{"title":"Create a cart approval","allOf":[{"$ref":"#/components/schemas/genericApprovalForCreate"},{"type":"object","description":"Request payload for creating a CART approval.","properties":{"id":{"type":"string","description":"An identifier of the approval document."},"resourceId":{"type":"string","description":"An identifier of the approval resource."},"resourceType":{"type":"string","enum":["CART"]},"details":{"$ref":"#/components/schemas/details"}},"required":["resourceId","resourceType","action","approver","details"]}]},"genericApprovalForCreate":{"title":"basicApproval","description":"Base schema for an approval creation.","type":"object","properties":{"action":{"$ref":"#/components/schemas/approvalAction"},"approver":{"type":"object","description":"User who can approve the approval request.","properties":{"userId":{"type":"string","description":"Identifier of the user."}}},"comment":{"type":"string","description":"A comment from the requestor to the approver."}},"required":["action","approver"]},"approvalAction":{"title":"An approval action","description":"Base schema for an approval action type.","type":"string","enum":["CHECKOUT"]},"details":{"type":"object","title":"additional information","description":"Checkout details for **cart** approvals. **Required** when `resourceType` is `CART`.\n","properties":{"shipping":{"$ref":"#/components/schemas/shipping"},"payment":{"$ref":"#/components/schemas/payment"},"paymentMethods":{"description":"Methods chosen to process the payment for the order.","type":"array","items":{"$ref":"#/components/schemas/paymentMethod"}},"currency":{"type":"string","description":"Three-letter currency code, compliant with the ISO 4217 standard."},"addresses":{"type":"array","uniqueItems":true,"minItems":1,"description":"List of addresses associated with the order.","items":{"$ref":"#/components/schemas/address"}}}},"shipping":{"type":"object","title":"Shipping information","description":"Information about the shipping.","additionalProperties":false,"properties":{"methodId":{"type":"string","description":"Shipping method's unique identifier.","minLength":0},"zoneId":{"type":"string","description":"Shipping zone identifier.","minLength":0},"methodName":{"type":"string","description":"Shipping method chosen by the customer.","minLength":0},"amount":{"type":"number","minimum":0,"description":"Shipping net cost."},"shippingTaxCode":{"type":"string","description":"The tax code of the shipping."}}},"payment":{"type":"object","description":"Information about the payment.","title":"Payment information","additionalProperties":false,"properties":{"paymentId":{"type":"string","minLength":0},"customAttributes":{"type":"object"}}},"paymentMethod":{"type":"object","additionalProperties":false,"properties":{"provider":{"type":"string","description":"Payment provider, possible values: \n * `payment-gateway` - When the Emporix Payment-Gateway service should be used to handle a payment. For details about custom attributes that are required for a particular payment mode, check https://developer.emporix.io/user-guides/system-management/payment-gateway/payments. \n * `custom` - When a custom provider is used. In this case the created order has the `IN_CHECKOUT` status.\n * `none` - For payment by cash or invoice.\n","minLength":0},"customAttributes":{"type":"object","description":"Additional information about the payment method.","properties":{"token":{"type":"string","description":"Payment token used for the tokenized credit card flows. The field is used when provider type is `payment-gateway`. For more details, check https://developer.emporix.io/user-guides/system-management/payment-gateway/payments"},"modeId":{"type":"string","description":"Identifier of a payment mode. The payment mode has to be configured in the Emporix Payment Gateway service beforehand. For more details, check https://developer.emporix.io/user-guides/system-management/payment-gateway/payments"},"paymentType":{"type":"string","description":"Payment type chosen by the customer, for example `paymentByCredit` or `paymentByDebit`."}}},"method":{"type":"string","description":"Payment method chosen by the customer, for example `invoice` or `cash-on-delivery`."},"amount":{"type":"number","description":"Amount to be paid by the customer."}}},"address":{"type":"object","description":"Information about the customer address.","properties":{"contactName":{"type":"string","minLength":0},"companyName":{"type":"string"},"street":{"type":"string","minLength":0},"streetNumber":{"type":"string"},"streetAppendix":{"type":"string"},"zipCode":{"type":"string","maxLength":11,"minLength":0},"city":{"type":"string","minLength":0},"country":{"type":"string","minLength":1},"state":{"type":"string"},"contactPhone":{"type":"string"},"type":{"type":"string","description":"Type of the address data, for example `BILLING` or `SHIPPING`.","enum":["SHIPPING","BILLING"]}}},"createQuoteApprovalRequest":{"title":"Create a quote approval","allOf":[{"$ref":"#/components/schemas/genericApprovalForCreate"},{"type":"object","description":"Request payload for creating a QUOTE approval (without details).","properties":{"id":{"type":"string","description":"An identifier of the approval document."},"resourceId":{"type":"string","description":"An identifier of the approval resource."},"resourceType":{"type":"string","enum":["QUOTE"]}},"required":["resourceId","resourceType","action","approver"]}]}},"responses":{"approvals_response_BadRequest_400":{"description":"Bad request due to validation, incorrect parameters, etc.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coreErrorMessage"}}}},"common_response_Unauthorized_401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"common_response_Forbidden_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coreErrorMessage"}}}},"approval_post_response_Conflict_409":{"description":"Resource with given code already exists.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coreErrorMessage"}}}}},"requestBodies":{"approvalCreateBody":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/createCartApprovalRequest"},{"$ref":"#/components/schemas/createQuoteApprovalRequest"}]}}}}},"parameters":{"path_tenant":{"name":"tenant","in":"path","required":true,"description":"Your Emporix tenant name.\n**Note**: The tenant name should always be written in lowercase.\n","schema":{"pattern":"^[a-z][a-z0-9]+$","minLength":3,"maxLength":16,"type":"string"}}}},"paths":{"/approval/{tenant}/approvals":{"post":{"summary":"Creating a single approval","responses":{"201":{"description":"The resource has been successfully created. \n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/approvalId"}}}},"400":{"$ref":"#/components/responses/approvals_response_BadRequest_400"},"401":{"$ref":"#/components/responses/common_response_Unauthorized_401"},"403":{"$ref":"#/components/responses/common_response_Forbidden_403"},"409":{"$ref":"#/components/responses/approval_post_response_Conflict_409"}},"description":"Creates a single approval document with information about the approver, resource type and resource identifier.\n\n- **`resourceType: CART`**: `details` is **required** (shipping, addresses, currency, payment methods, etc.).\n- **`resourceType: QUOTE`**: `details` must be **omitted**; the service loads quote data using `resourceId`.\n\nThe user must be a *Requestor* or an *Approver* to have the required `approval.approval_manage_own` scope.\n\nIn case of any validation problems, the below `errorCodes` can be returned:\n - **APPROVAL-400003**: Incorrect value of the approval status\n - **APPROVAL-400004**: Not matching combination of approval action and resource type \n - **APPROVAL-400005**: Approval has been already given\n - **APPROVAL-400006**: Provided approver cannot be assigned to the approval\n - **APPROVAL-400008**: Requested user has no permissions to the resource\n - **APPROVAL-400011**: Requested user is not assigned to any company\n - **APPROVAL-404002**: Provided resource does not exist\n - **APPROVAL-404003**: Requested user is not assigned to any legal entity\n - **APPROVAL-409001**: Approval already exists\n","operationId":"POST-approval-create-approval","requestBody":{"$ref":"#/components/requestBodies/approvalCreateBody"},"parameters":[{"$ref":"#/components/parameters/path_tenant"}],"tags":["Approvals"]}}}}
```
## Retrieving a single approval
> Retrieves a single approval document which is assigned to the user. The user must be a \*Requestor\* or an \*Approver\* to have the required \`approval.approval\_read\_own\` scope.\
> \
> In case of any validation problems, the below \`errorCodes\` can be returned:\
> \- \*\*APPROVAL-404001\*\*: Approval does not exist
```json
{"openapi":"3.0.0","info":{"title":"Approval Service","version":"0.0.1"},"tags":[{"name":"Approvals"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"CustomerAccessToken":[]}],"components":{"securitySchemes":{"CustomerAccessToken":{"type":"http","scheme":"bearer","description":"To generate a customer access token, go to the [Logging in a customer](https://developer.emporix.io/api-references/api-guides/companies-and-customers/customer-management/api-reference/authentication-and-authorization#post-customer-tenant-login) endpoint."}},"responses":{"singleApprovalResponse_200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/getApprovalResponse"}}}},"common_response_Unauthorized_401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"common_response_Forbidden_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coreErrorMessage"}}}},"approvals_response_NotFound_404":{"description":"Resource cannot be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coreErrorMessage"}}}}},"schemas":{"getApprovalResponse":{"title":"An approval response","allOf":[{"$ref":"#/components/schemas/basicApproval"},{"type":"object","description":"Base schema for an approval response.","properties":{"id":{"type":"string","description":"An identifier of the approval document."},"approverComment":{"type":"string","description":"A comment from an approver user."},"resource":{"$ref":"#/components/schemas/resourceResponse"},"requestor":{"$ref":"#/components/schemas/user"},"approver":{"$ref":"#/components/schemas/user"},"status":{"$ref":"#/components/schemas/approvalStatus"},"expiryDate":{"$ref":"#/components/schemas/expiryDate"},"metadata":{"$ref":"#/components/schemas/metadata"}}}]},"basicApproval":{"title":"basicApproval","description":"Base schema for an approval.","allOf":[{"$ref":"#/components/schemas/genericApprovalForCreate"},{"type":"object","properties":{"resourceType":{"$ref":"#/components/schemas/resourceType"},"details":{"$ref":"#/components/schemas/details"}}}],"required":["resourceType","action","approver"]},"genericApprovalForCreate":{"title":"basicApproval","description":"Base schema for an approval creation.","type":"object","properties":{"action":{"$ref":"#/components/schemas/approvalAction"},"approver":{"type":"object","description":"User who can approve the approval request.","properties":{"userId":{"type":"string","description":"Identifier of the user."}}},"comment":{"type":"string","description":"A comment from the requestor to the approver."}},"required":["action","approver"]},"approvalAction":{"title":"An approval action","description":"Base schema for an approval action type.","type":"string","enum":["CHECKOUT"]},"resourceType":{"title":"A type of a resource","description":"Type of resource under approval. \n","type":"string","enum":["CART","QUOTE"]},"details":{"type":"object","title":"additional information","description":"Checkout details for **cart** approvals. **Required** when `resourceType` is `CART`.\n","properties":{"shipping":{"$ref":"#/components/schemas/shipping"},"payment":{"$ref":"#/components/schemas/payment"},"paymentMethods":{"description":"Methods chosen to process the payment for the order.","type":"array","items":{"$ref":"#/components/schemas/paymentMethod"}},"currency":{"type":"string","description":"Three-letter currency code, compliant with the ISO 4217 standard."},"addresses":{"type":"array","uniqueItems":true,"minItems":1,"description":"List of addresses associated with the order.","items":{"$ref":"#/components/schemas/address"}}}},"shipping":{"type":"object","title":"Shipping information","description":"Information about the shipping.","additionalProperties":false,"properties":{"methodId":{"type":"string","description":"Shipping method's unique identifier.","minLength":0},"zoneId":{"type":"string","description":"Shipping zone identifier.","minLength":0},"methodName":{"type":"string","description":"Shipping method chosen by the customer.","minLength":0},"amount":{"type":"number","minimum":0,"description":"Shipping net cost."},"shippingTaxCode":{"type":"string","description":"The tax code of the shipping."}}},"payment":{"type":"object","description":"Information about the payment.","title":"Payment information","additionalProperties":false,"properties":{"paymentId":{"type":"string","minLength":0},"customAttributes":{"type":"object"}}},"paymentMethod":{"type":"object","additionalProperties":false,"properties":{"provider":{"type":"string","description":"Payment provider, possible values: \n * `payment-gateway` - When the Emporix Payment-Gateway service should be used to handle a payment. For details about custom attributes that are required for a particular payment mode, check https://developer.emporix.io/user-guides/system-management/payment-gateway/payments. \n * `custom` - When a custom provider is used. In this case the created order has the `IN_CHECKOUT` status.\n * `none` - For payment by cash or invoice.\n","minLength":0},"customAttributes":{"type":"object","description":"Additional information about the payment method.","properties":{"token":{"type":"string","description":"Payment token used for the tokenized credit card flows. The field is used when provider type is `payment-gateway`. For more details, check https://developer.emporix.io/user-guides/system-management/payment-gateway/payments"},"modeId":{"type":"string","description":"Identifier of a payment mode. The payment mode has to be configured in the Emporix Payment Gateway service beforehand. For more details, check https://developer.emporix.io/user-guides/system-management/payment-gateway/payments"},"paymentType":{"type":"string","description":"Payment type chosen by the customer, for example `paymentByCredit` or `paymentByDebit`."}}},"method":{"type":"string","description":"Payment method chosen by the customer, for example `invoice` or `cash-on-delivery`."},"amount":{"type":"number","description":"Amount to be paid by the customer."}}},"address":{"type":"object","description":"Information about the customer address.","properties":{"contactName":{"type":"string","minLength":0},"companyName":{"type":"string"},"street":{"type":"string","minLength":0},"streetNumber":{"type":"string"},"streetAppendix":{"type":"string"},"zipCode":{"type":"string","maxLength":11,"minLength":0},"city":{"type":"string","minLength":0},"country":{"type":"string","minLength":1},"state":{"type":"string"},"contactPhone":{"type":"string"},"type":{"type":"string","description":"Type of the address data, for example `BILLING` or `SHIPPING`.","enum":["SHIPPING","BILLING"]}}},"resourceResponse":{"title":"Resource","description":"Resource of the approval.","type":"object","properties":{"id":{"type":"string","description":"The identifier of the resource."},"items":{"type":"array","items":{"$ref":"#/components/schemas/resourceItem"}},"totalPrice":{"$ref":"#/components/schemas/price"},"subTotalPrice":{"$ref":"#/components/schemas/price"},"subtotalAggregate":{"$ref":"#/components/schemas/taxablePrice"},"siteCode":{"type":"string","description":"Name of the site."},"deliveryWindow":{"$ref":"#/components/schemas/deliveryWindow"}}},"resourceItem":{"title":"Resource item","description":"Item of the resource.","type":"object","properties":{"quantity":{"type":"number","description":"Quantity of the given item."},"itemPrice":{"$ref":"#/components/schemas/resourceItemPrice"},"itemYrn":{"deprecated":true,"type":"string","description":"YRN which identifies the product."},"itemId":{"type":"string","description":"Line-item identifier (e.g. quote line id)."}}},"resourceItemPrice":{"title":"Resource item price","description":"Per-line price; used for resource line items.","type":"object","properties":{"currency":{"type":"string","description":"Currency of the price."},"amount":{"type":"number","deprecated":true,"description":"Deprecated; prefer `unitPrice`, `newUnitPrice`, or `calculatedPrice`."},"unitPrice":{"type":"number","description":"Unit net price before adjustments."},"newUnitPrice":{"type":"number","description":"Unit net price after adjustments (valid for quote line items)."},"calculatedPrice":{"$ref":"#/components/schemas/calculatedPrice"}}},"calculatedPrice":{"title":"Calculated price breakdown","type":"object","properties":{"price":{"type":"object","properties":{"netValue":{"description":"Net value of the price.","type":"number"},"grossValue":{"type":"number","description":"Gross value of the price."},"taxValue":{"description":"Tax value of the price.","type":"number"}}}}},"price":{"title":"Price value","description":"Aggregated price (totals, subtotals) with currency and optional tax breakdown.","type":"object","properties":{"currency":{"type":"string","description":"Currency of the price."},"amount":{"type":"number","deprecated":true,"description":"Deprecated; use `netValue`, `grossValue`, and `taxValue` when present."},"netValue":{"type":"number","description":"Net value of the price."},"grossValue":{"type":"number","description":"Gross value of the price."},"taxValue":{"type":"number","description":"Tax value of the price."}}},"taxablePrice":{"title":"Taxable price value","description":"Price value with the currency and tax information.","type":"object","properties":{"currency":{"type":"string","description":"Currency of the price."},"netValue":{"type":"number","description":"Net value of the price."},"grossValue":{"type":"number","description":"Gross value of the price."},"taxValue":{"type":"number","description":"Tax value of the price."}}},"deliveryWindow":{"title":"Delivery Window","description":"delivery window required for order.","type":"object","properties":{"id":{"type":"string","description":"Identifier of the delivery window."},"slotId":{"type":"string","description":"Identifier of the slot."},"deliveryDate":{"type":"string","description":"Delivery date."}}},"user":{"title":"user schema","type":"object","properties":{"userId":{"type":"string","description":"An identifier of the user."},"firstName":{"type":"string","description":"First name of the user."},"lastName":{"type":"string","description":"Last name of the user."}},"required":["userId","firstName","lastName"]},"approvalStatus":{"title":"A status of the approval","description":"Base schema for the approval status.","type":"string","enum":["PENDING","APPROVED","CLOSED","EXPIRED","DECLINED"]},"expiryDate":{"title":"An expiration date","description":"An expiration date which defines when the approval will expire. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-31T13:18:02.379Z`","type":"string"},"metadata":{"allOf":[{"$ref":"#/components/schemas/basicMetadata"},{"type":"object","properties":{"createdAt":{"description":"Date and time when the object was created. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-31T13:18:02.379Z`","type":"string"},"modifiedAt":{"description":"Date and time when the object was last modified. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-31T13:18:02.379Z`","type":"string"}}}],"required":["createdAt","modifiedAt","version"]},"basicMetadata":{"type":"object","properties":{"version":{"minimum":1,"type":"integer","description":"Version of the object. The version is required during the update operation because of the optimistic locking mechanism."}},"required":["version"]},"coreErrorMessage":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Error message."},"errorCode":{"type":"string","description":"code of the error."},"details":{"description":"Details information.","type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}}}}},"paths":{"/approval/{tenant}/approvals/{approvalId}":{"get":{"summary":"Retrieving a single approval","tags":["Approvals"],"operationId":"GET-approval-retrieve-approval","description":"Retrieves a single approval document which is assigned to the user. The user must be a *Requestor* or an *Approver* to have the required `approval.approval_read_own` scope.\n\nIn case of any validation problems, the below `errorCodes` can be returned:\n - **APPROVAL-404001**: Approval does not exist\n","responses":{"200":{"$ref":"#/components/responses/singleApprovalResponse_200"},"401":{"$ref":"#/components/responses/common_response_Unauthorized_401"},"403":{"$ref":"#/components/responses/common_response_Forbidden_403"},"404":{"$ref":"#/components/responses/approvals_response_NotFound_404"}}}}}}
```
## Deleting a single approval
> Deletes a single approval document.\
> To delete an approval, a customer must be a \*Requestor\* or an \*Approver\* to have the required \`approval.approval\_manage\_own\` scope. The approval can only be deleted if its status is \`PENDING\`. The approval status is changed to \`CLOSED\` during deletion.\
> \
> In case of any validation problems, the below \`errorCodes\` can be returned:\
> \- \*\*APPROVAL-404001\*\*: Approval does not exist.
```json
{"openapi":"3.0.0","info":{"title":"Approval Service","version":"0.0.1"},"tags":[{"name":"Approvals"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"CustomerAccessToken":[]}],"components":{"securitySchemes":{"CustomerAccessToken":{"type":"http","scheme":"bearer","description":"To generate a customer access token, go to the [Logging in a customer](https://developer.emporix.io/api-references/api-guides/companies-and-customers/customer-management/api-reference/authentication-and-authorization#post-customer-tenant-login) endpoint."}},"responses":{"approvals_response_DeleteBadRequest_400":{"description":"Bad request - an approval cannot be deleted because it has an inappropriate status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coreErrorMessage"}}}},"common_response_Unauthorized_401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"common_response_Forbidden_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coreErrorMessage"}}}},"approvals_response_NotFound_404":{"description":"Resource cannot be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coreErrorMessage"}}}}},"schemas":{"coreErrorMessage":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Error message."},"errorCode":{"type":"string","description":"code of the error."},"details":{"description":"Details information.","type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}}}}},"paths":{"/approval/{tenant}/approvals/{approvalId}":{"delete":{"summary":"Deleting a single approval","operationId":"DELETE-approval-remove-approval","responses":{"204":{"description":"No Content"},"400":{"$ref":"#/components/responses/approvals_response_DeleteBadRequest_400"},"401":{"$ref":"#/components/responses/common_response_Unauthorized_401"},"403":{"$ref":"#/components/responses/common_response_Forbidden_403"},"404":{"$ref":"#/components/responses/approvals_response_NotFound_404"}},"tags":["Approvals"],"description":"Deletes a single approval document.\nTo delete an approval, a customer must be a *Requestor* or an *Approver* to have the required `approval.approval_manage_own` scope. The approval can only be deleted if its status is `PENDING`. The approval status is changed to `CLOSED` during deletion.\n\nIn case of any validation problems, the below `errorCodes` can be returned:\n - **APPROVAL-404001**: Approval does not exist."}}}}
```
## Updating a single approval
> Partially updates a single approval document with given information. To update the approval, the user must be a \*Requestor\* or an \*Approver\* to have the required \`approval.approval\_manage\_own\` scope.\
> \
> 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)\
> Approval can be updated only when status is PENDING.\
> \
> In case of any validation problems, the below \`errorCodes\` can be returned:\
> \- \*\*APPROVAL-400002\*\*: Approval status cannot be changed to the new value\
> \- \*\*APPROVAL-400003\*\*: Incorrect value of the approval status\
> \- \*\*APPROVAL-400004\*\*: Not matching combination of approval action and resource type \
> \- \*\*APPROVAL-400005\*\*: Approval has been already permitted\
> \- \*\*APPROVAL-400007\*\*: Not supported patch operation\
> \- \*\*APPROVAL-400009\*\*: Approval process has been finished and cannot be updated\
> \- \*\*APPROVAL-400010\*\*: Incorrect patch operation\
> \- \*\*APPROVAL-404001\*\*: Approval does not exist
```json
{"openapi":"3.0.0","info":{"title":"Approval Service","version":"0.0.1"},"tags":[{"name":"Approvals"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"CustomerAccessToken":[]}],"components":{"securitySchemes":{"CustomerAccessToken":{"type":"http","scheme":"bearer","description":"To generate a customer access token, go to the [Logging in a customer](https://developer.emporix.io/api-references/api-guides/companies-and-customers/customer-management/api-reference/authentication-and-authorization#post-customer-tenant-login) endpoint."}},"responses":{"approvals_response_BadRequest_400":{"description":"Bad request due to validation, incorrect parameters, etc.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coreErrorMessage"}}}},"common_response_Unauthorized_401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"common_response_Forbidden_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coreErrorMessage"}}}},"approvals_response_NotFound_404":{"description":"Resource cannot be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coreErrorMessage"}}}}},"schemas":{"coreErrorMessage":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Error message."},"errorCode":{"type":"string","description":"code of the error."},"details":{"description":"Details information.","type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}}},"updateApprovalRequest":{"type":"array","description":"Approval partial update operation list.","items":{"type":"object","properties":{"op":{"anyOf":[{"enum":["ADD","REMOVE","REPLACE"]}],"type":"string"},"path":{"anyOf":[{"enum":["/status","/details*","/comment","/approverComment","/resource/deliveryWindow*"]}],"type":"string"},"value":{"anyOf":[{"$ref":"#/components/schemas/approvalStatus"},{"type":"string","description":"Value of the string type."},{"type":"object","description":"Any part of the details object."},{"type":"object","description":"Any part of the delivery window object."}]}},"required":["op","path"]}},"approvalStatus":{"title":"A status of the approval","description":"Base schema for the approval status.","type":"string","enum":["PENDING","APPROVED","CLOSED","EXPIRED","DECLINED"]}},"requestBodies":{"approvalUpdateBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/updateApprovalRequest"}}}}}},"paths":{"/approval/{tenant}/approvals/{approvalId}":{"patch":{"summary":"Updating a single approval","operationId":"PATCH-approval-update-approval","responses":{"204":{"description":"No Content."},"400":{"$ref":"#/components/responses/approvals_response_BadRequest_400"},"401":{"$ref":"#/components/responses/common_response_Unauthorized_401"},"403":{"$ref":"#/components/responses/common_response_Forbidden_403"},"404":{"$ref":"#/components/responses/approvals_response_NotFound_404"}},"tags":["Approvals"],"description":"Partially updates a single approval document with given information. To update the approval, the user must be a *Requestor* or an *Approver* to have the required `approval.approval_manage_own` scope.\n\nSingle update may contain multiple partial updates in the form of an array. It contains the allowed operations list:\n - `add` (adding an item to the items list)\n - `remove` (removing an item from the items list)\n - `replace` (replacing an item with given id with new definition)\nApproval can be updated only when status is PENDING.\n\nIn case of any validation problems, the below `errorCodes` can be returned:\n - **APPROVAL-400002**: Approval status cannot be changed to the new value\n - **APPROVAL-400003**: Incorrect value of the approval status\n - **APPROVAL-400004**: Not matching combination of approval action and resource type \n - **APPROVAL-400005**: Approval has been already permitted\n - **APPROVAL-400007**: Not supported patch operation\n - **APPROVAL-400009**: Approval process has been finished and cannot be updated\n - **APPROVAL-400010**: Incorrect patch operation\n - **APPROVAL-404001**: Approval does not exist\n","requestBody":{"$ref":"#/components/requestBodies/approvalUpdateBody"}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://developer.emporix.io/api-references/api-guides/companies-and-customers/approval-service/approval-api-reference/approvals.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.