# Coupon Management
## Retrieving list of coupons by criteria
> Retrieves a list of coupons by the specified criteria. Supports sorting and paging.
```json
{"openapi":"3.0.0","info":{"title":"Coupon Service","version":"0.0.1"},"tags":[{"name":"Coupon Management"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["coupon.coupon_manage","coupon.coupon_read"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"coupon.coupon_read":"Needed to read coupons.","coupon.coupon_manage":"Needed to manage coupons.","coupon.coupon_redeem":"Needed to redeem coupons.","coupon.coupon_redeem_on_behalf":"Needed to redeem coupons on behalf of another customer."}}}}},"headers":{"Total-Count":{"required":false,"description":"The total number of objects that fulfil the criteria.\n","schema":{"type":"integer"}}},"schemas":{"coupons":{"type":"array","items":{"$ref":"#/components/schemas/coupon-with-id-and-status"}},"coupon-with-id-and-status":{"allOf":[{"$ref":"#/components/schemas/coupon"},{"type":"object","properties":{"code":{"type":"string","description":"e.g.: WINTER-SALE, 10OFF (read-only)."},"referralCoupon":{"$ref":"#/components/schemas/referralCouponProperty"},"status":{"type":"string","description":"Current status of the coupon (read-only). 'INACTIVE': the coupon is only valid in the future; 'VALID': can be used; 'EXPIRED': the coupon validity period has expired; 'USED': the maximum number of redemptions for the coupon has been reached.","enum":["VALID","INACTIVE","EXPIRED","USED"]}}}]},"coupon":{"allOf":[{"$ref":"#/components/schemas/base-coupon"},{"type":"object","properties":{"legalEntityRedemptions":{"type":"array","items":{"type":"object","properties":{"legalEntityId":{"type":"string","description":"The id of the legal entity to which customer is assigned."},"count":{"type":"number","description":"The number of times a specific coupon has been redeemed in the context of the given legal entity."}}}},"redemptionCount":{"type":"number","description":"The number of times a specific coupon has been redeemed. Read-only, set through server. (seller-only)."},"referralCoupon":{"$ref":"#/components/schemas/referralCouponProperty"},"deleted":{"description":"Flag to mark a coupon as deleted (a.k.a. Soft delete). It is a read-only and seller-only attribute.","type":"boolean"}},"required":["name","discountType"]}]},"base-coupon":{"title":"Coupon response/update payload","description":"Coupons describe voucher alike commerce capabilities, e.g. 10% off winter accessories.","type":"object","properties":{"name":{"type":"string","description":"Coupon name."},"description":{"type":"string","description":"Coupon description."},"discountType":{"enum":["PERCENT","ABSOLUTE","FREE_SHIPPING"],"description":"'PERCENT' for relative values, 'ABSOLUTE' for float values, referring to a specific currency, 'FREE_SHIPPING' for reducing the shipping cost to 0.","type":"string"},"discountPercentage":{"type":"number","description":"A discount percentage within the range [0.00, 100.00]. Must be specified only if type is 'PERCENT'.","minimum":0,"maximum":100},"discountAbsolute":{"type":"object","description":"Must be specified only if type is 'ABSOLUTE'. Defines the amount that should be substracted from the cart subtotal.","properties":{"amount":{"type":"number","description":"Total amount in the specified currency."},"currency":{"type":"string","description":"ISO 4217 currency code, e.g.: USD, EUR, CHF."}}},"allowAnonymous":{"type":"boolean","description":"Specifies if the coupon can be redeemed by anonymous user. If set to false, only logged-in customers can redeem it.","default":false},"maxRedemptions":{"type":"number","description":"Maximum number of redemptions; -1 designates 'unlimited' (seller-only).","default":-1},"maxRedemptionsPerCustomer":{"type":"number","description":"Maximum number of redemptions per customer; -1 designates 'unlimited'. Cannot be specified for coupons which can be redeemed by anonymous users.","default":-1},"discountCalculationType":{"type":"string","enum":["TOTAL","SUBTOTAL"],"description":"Determines whether the coupon is applied to the total or subtotal value of the order.","default":"SUBTOTAL"},"categoryRestricted":{"$ref":"#/components/schemas/categoryRestricted"},"segmentRestricted":{"$ref":"#/components/schemas/segmentRestricted"},"restrictions":{"$ref":"#/components/schemas/restrictions"},"issuedTo":{"type":"string","description":"The Id of the customer who originally received the coupon (seller-only)."},"mixins":{"type":"object","description":"The field contains mixins values.","additionalProperties":true},"metadata":{"type":"object","additionalProperties":false,"properties":{"version":{"description":"Version of the document. Set to 0 after creating a document. Increments by 1 after every update.","type":"number"},"mixins":{"type":"object","description":"Links to the mixin schemas.","additionalProperties":{"type":"string"}}}}}},"categoryRestricted":{"type":"boolean","description":"Defines if the coupon has category restrictions.\n***\nInfo: Cannot be combined together with the segment restrictions.\n","default":false},"segmentRestricted":{"type":"boolean","description":"Defines if the coupon has segment restrictions. If the value is set to `true`, the `restrictions.segments` must be provided.\n***\nInfo: Cannot be combined neither with the category restrictions nor with customers restrictions.\n","default":false},"restrictions":{"type":"object","description":"Restrictions of the coupon.","properties":{"validFor":{"type":"array","description":"A list of customer identifiers for whom the coupon can be redeemed. Cannot be specified for coupons which can be redeemed by anonymous users.","items":{"type":"string"}},"validFrom":{"type":"string","format":"date-time","description":"Must be provided in ISO 8601 format (http://www.iso.org/iso/home/standards/iso8601.htm), e.g. '2015-01-31T23:59:59.999Z'."},"validUntil":{"type":"string","format":"date-time","description":"Must be provided in ISO 8601 format (http://www.iso.org/iso/home/standards/iso8601.htm), e.g. '2015-01-31T23:59:59.999Z'."},"minOrderValue":{"$ref":"#/components/schemas/currency-amount"},"includedCategories":{"type":"array","description":"The list of product's categories to which this coupon applies to. Must be defined only if the `categoryRestricted` flag is set to true. Must be disjoint with excludedCategories list.","items":{"type":"string"}},"excludedCategories":{"type":"array","description":"The list of product's categories to which this coupon does not apply to. Can be defined only if the `categoryRestricted` flag is set to true. Must be disjoint with includedCategories list.","items":{"type":"string"}},"segments":{"type":"array","description":"The list of segments to which this coupon applies to. Can be defined only if the `segmentRestricted` flag is set to true.","items":{"type":"string"}}}},"currency-amount":{"type":"object","title":"Money amount","description":"Defines an amount in a specific currency.","properties":{"amount":{"type":"number","default":0,"minimum":0,"description":"Total amount in the specified currency."},"currency":{"type":"string","default":"USD","pattern":"^[A-Z]{3}$","description":"ISO 4217 currency code, e.g.: USD, EUR, CHF."}}},"referralCouponProperty":{"type":"boolean","description":"Indicates if the coupon is type of referral coupon. This property is read only."}},"responses":{"trait_queryable_400":{"description":"Request syntactically incorrect. Details of the error are included in the response payload.","content":{"application/json":{"schema":{"title":"error","description":"Schema for API specified errors.","type":"object","properties":{"status":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error type, lower case with underscore eg validation_failure.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"errorDetail","description":"Schema for specific error cause.","type":"object","properties":{"field":{"description":"A bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific.","type":"string"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.","type":"string"},"message":{"description":"Descriptive error detail message for debugging.","type":"string"},"moreInfo":{"type":"string","description":"Link to documentation to investigate further and finding support for error detail."}},"required":["type"]}}},"required":["status","type"]}}}},"trait_unauthorized_401":{"description":"Example response","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"trait_restricted_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"title":"error","description":"Schema for API specified errors.","type":"object","properties":{"status":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error type, lower case with underscore eg validation_failure.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"}},"required":["status","type"]}}}},"trait_internal_500":{"description":"Some server side error occurred.\n","content":{"application/json":{"schema":{"title":"error","description":"Schema for API specified errors.","type":"object","properties":{"status":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error type, lower case with underscore eg validation_failure.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"errorDetail","description":"Schema for specific error cause.","type":"object","properties":{"field":{"description":"A bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific.","type":"string"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.","type":"string"},"message":{"description":"Descriptive error detail message for debugging.","type":"string"},"moreInfo":{"type":"string","description":"Link to documentation to investigate further and finding support for error detail."}},"required":["type"]}}},"required":["status","type"]}}}}},"parameters":{"trait_sortable_sort":{"name":"sort","in":"query","description":"The list of comma-separated properties used to sort the results.\nBy default, the column values are sorted in ascending order.\nCan either be in the form of fieldName or fieldName:asc,fieldName:desc.\nIf you want to sort by localized attributes, you must use the following form:\nfieldName.language or fieldName.language:asc,fieldName.language:desc.\n","schema":{"type":"string"}},"trait_paged_pageNumber":{"name":"pageNumber","in":"query","description":"The page number to be retrieved where the size of the pages must be specified by the pageSize parameter.\nThe number of the first page is 1.\n","schema":{"default":1,"minimum":1,"type":"integer"}},"trait_paged_pageSize":{"name":"pageSize","in":"query","description":"The number of documents being retrieved on the page.\n","schema":{"default":16,"minimum":1,"type":"integer"}},"trait_countable_totalCount":{"name":"totalCount","in":"query","description":"This parameter requests to return the total number of object in the collection fulfilling\nthe criteria together with the response. This number will be returned in the 'items-count'\nheader.\n","schema":{"type":"boolean"}},"trait_queryable_q":{"name":"q","in":"query","description":"The simple query criteria based on available fields to limit returned results or a set of modified documents.\n","schema":{"type":"string"}},"show_deleted":{"name":"showDeleted","in":"query","description":"Includes deleted coupons in the result.\n","schema":{"type":"boolean","default":false}}}},"paths":{"/coupon/{tenant}/coupons":{"get":{"summary":"Retrieving list of coupons by criteria","tags":["Coupon Management"],"responses":{"200":{"description":"The list of coupons has been retrieved successfully.\n","headers":{"Items-Count":{"$ref":"#/components/headers/Total-Count"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/coupons"}}}},"400":{"$ref":"#/components/responses/trait_queryable_400"},"401":{"$ref":"#/components/responses/trait_unauthorized_401"},"403":{"$ref":"#/components/responses/trait_restricted_403"},"500":{"$ref":"#/components/responses/trait_internal_500"}},"description":"Retrieves a list of coupons by the specified criteria. Supports sorting and paging.\n","operationId":"GET-coupon-list-specified-coupons","parameters":[{"$ref":"#/components/parameters/trait_sortable_sort"},{"$ref":"#/components/parameters/trait_paged_pageNumber"},{"$ref":"#/components/parameters/trait_paged_pageSize"},{"$ref":"#/components/parameters/trait_countable_totalCount"},{"$ref":"#/components/parameters/trait_queryable_q"},{"$ref":"#/components/parameters/show_deleted"}]}}}}
```
## Creating a new coupon
> Creates a coupon.\
> \
> By default, the coupon code is saved in uppercase. To ensure that the code is saved both in upper and lower case, set the \`enableCouponCodeCaseSensitivity\` configuration to true in the configuration service or System Preferences.
```json
{"openapi":"3.0.0","info":{"title":"Coupon Service","version":"0.0.1"},"tags":[{"name":"Coupon Management"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["coupon.coupon_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"coupon.coupon_read":"Needed to read coupons.","coupon.coupon_manage":"Needed to manage coupons.","coupon.coupon_redeem":"Needed to redeem coupons.","coupon.coupon_redeem_on_behalf":"Needed to redeem coupons on behalf of another customer."}}}}},"schemas":{"resource-location":{"type":"object","properties":{"id":{"type":"string","description":"Identifier of the link."},"yrn":{"type":"string","description":"Identifier of the link in the system's notation."}}},"coupon-creation":{"title":"Coupon creation payload","description":"Coupon creation schema.","type":"object","properties":{"code":{"type":"string","description":"e.g.: WINTER-SALE, 10OFF. If not provided, a code will be auto generated."},"name":{"type":"string","description":"Coupon name."},"description":{"type":"string","description":"Coupon description."},"discountType":{"enum":["PERCENT","ABSOLUTE","FREE_SHIPPING"],"default":"ABSOLUTE","description":"'PERCENT' for relative values, 'ABSOLUTE' for float values, referring to a specific currency, 'FREE_SHIPPING' for reducing the shipping cost to 0.","type":"string"},"discountPercentage":{"type":"number","description":"A discount percentage within the range [0.00, 100.00]. Must be specified only if type is 'PERCENT'.","minimum":0,"maximum":100},"discountAbsolute":{"allOf":[{"$ref":"#/components/schemas/currency-amount"},{"description":"Must be specified only if type is 'ABSOLUTE'. Defines the amount that should be substracted from the cart subtotal."}]},"allowAnonymous":{"type":"boolean","description":"Specifies if the coupon can be redeemed by anonymous user. If set to false, only logged-in customers can redeem it.","default":false},"maxRedemptions":{"type":"number","description":"Maximum number of redemptions; -1 designates 'unlimited' (seller-only).","default":-1},"maxRedemptionsPerCustomer":{"type":"number","description":"Maximum number of redemptions per customer; -1 designates 'unlimited'. Cannot be specified for coupons which can be redeemed by anonymous users.","default":-1},"discountCalculationType":{"type":"string","enum":["TOTAL","SUBTOTAL"],"description":"Determines whether the coupon is applied to the total or subtotal value of the order.","default":"SUBTOTAL"},"categoryRestricted":{"$ref":"#/components/schemas/categoryRestricted"},"segmentRestricted":{"$ref":"#/components/schemas/segmentRestricted"},"restrictions":{"$ref":"#/components/schemas/restrictions"},"issuedTo":{"type":"string","description":"The Id of the customer who originally received the coupon (seller-only)."},"mixins":{"type":"object","description":"The field contains mixins values.","additionalProperties":true},"metadata":{"type":"object","additionalProperties":false,"properties":{"version":{"description":"Version of the document. Set to 0 after creating a document. Increments by 1 after every update.","type":"number"},"mixins":{"type":"object","description":"Links to the mixin schemas.","additionalProperties":{"type":"string"}}}}},"required":["name"]},"currency-amount":{"type":"object","title":"Money amount","description":"Defines an amount in a specific currency.","properties":{"amount":{"type":"number","default":0,"minimum":0,"description":"Total amount in the specified currency."},"currency":{"type":"string","default":"USD","pattern":"^[A-Z]{3}$","description":"ISO 4217 currency code, e.g.: USD, EUR, CHF."}}},"categoryRestricted":{"type":"boolean","description":"Defines if the coupon has category restrictions.\n***\nInfo: Cannot be combined together with the segment restrictions.\n","default":false},"segmentRestricted":{"type":"boolean","description":"Defines if the coupon has segment restrictions. If the value is set to `true`, the `restrictions.segments` must be provided.\n***\nInfo: Cannot be combined neither with the category restrictions nor with customers restrictions.\n","default":false},"restrictions":{"type":"object","description":"Restrictions of the coupon.","properties":{"validFor":{"type":"array","description":"A list of customer identifiers for whom the coupon can be redeemed. Cannot be specified for coupons which can be redeemed by anonymous users.","items":{"type":"string"}},"validFrom":{"type":"string","format":"date-time","description":"Must be provided in ISO 8601 format (http://www.iso.org/iso/home/standards/iso8601.htm), e.g. '2015-01-31T23:59:59.999Z'."},"validUntil":{"type":"string","format":"date-time","description":"Must be provided in ISO 8601 format (http://www.iso.org/iso/home/standards/iso8601.htm), e.g. '2015-01-31T23:59:59.999Z'."},"minOrderValue":{"$ref":"#/components/schemas/currency-amount"},"includedCategories":{"type":"array","description":"The list of product's categories to which this coupon applies to. Must be defined only if the `categoryRestricted` flag is set to true. Must be disjoint with excludedCategories list.","items":{"type":"string"}},"excludedCategories":{"type":"array","description":"The list of product's categories to which this coupon does not apply to. Can be defined only if the `categoryRestricted` flag is set to true. Must be disjoint with includedCategories list.","items":{"type":"string"}},"segments":{"type":"array","description":"The list of segments to which this coupon applies to. Can be defined only if the `segmentRestricted` flag is set to true.","items":{"type":"string"}}}}},"responses":{"trait_queryable_400":{"description":"Request syntactically incorrect. Details of the error are included in the response payload.","content":{"application/json":{"schema":{"title":"error","description":"Schema for API specified errors.","type":"object","properties":{"status":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error type, lower case with underscore eg validation_failure.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"errorDetail","description":"Schema for specific error cause.","type":"object","properties":{"field":{"description":"A bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific.","type":"string"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.","type":"string"},"message":{"description":"Descriptive error detail message for debugging.","type":"string"},"moreInfo":{"type":"string","description":"Link to documentation to investigate further and finding support for error detail."}},"required":["type"]}}},"required":["status","type"]}}}},"trait_unauthorized_401":{"description":"Example response","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"trait_restricted_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"title":"error","description":"Schema for API specified errors.","type":"object","properties":{"status":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error type, lower case with underscore eg validation_failure.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"}},"required":["status","type"]}}}},"trait_conflict_409":{"description":"Creation failed because there was a conflict with another resource. Details of the error are included in the response payload.\n","content":{"application/json":{"schema":{"title":"error","description":"Schema for API specified errors.","type":"object","properties":{"status":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error type, lower case with underscore eg validation_failure.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"}},"required":["status","type"]}}}},"trait_internal_500":{"description":"Some server side error occurred.\n","content":{"application/json":{"schema":{"title":"error","description":"Schema for API specified errors.","type":"object","properties":{"status":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error type, lower case with underscore eg validation_failure.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"errorDetail","description":"Schema for specific error cause.","type":"object","properties":{"field":{"description":"A bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific.","type":"string"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.","type":"string"},"message":{"description":"Descriptive error detail message for debugging.","type":"string"},"moreInfo":{"type":"string","description":"Link to documentation to investigate further and finding support for error detail."}},"required":["type"]}}},"required":["status","type"]}}}}}},"paths":{"/coupon/{tenant}/coupons":{"post":{"summary":"Creating a new coupon","tags":["Coupon Management"],"responses":{"201":{"description":"The resource has been successfully created.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/resource-location"}}}},"400":{"$ref":"#/components/responses/trait_queryable_400"},"401":{"$ref":"#/components/responses/trait_unauthorized_401"},"403":{"$ref":"#/components/responses/trait_restricted_403"},"409":{"$ref":"#/components/responses/trait_conflict_409"},"500":{"$ref":"#/components/responses/trait_internal_500"}},"description":"Creates a coupon.\n\nBy default, the coupon code is saved in uppercase. To ensure that the code is saved both in upper and lower case, set the `enableCouponCodeCaseSensitivity` configuration to true in the configuration service or System Preferences.\n","operationId":"POST-coupon-create-coupon","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/coupon-creation"}}},"required":true}}}}}
```
## Retrieving information about particular coupon by code
> Retrieves coupon details.\
> \*\*\*\
> \
> \### Additional scopes info\
> \* The \`coupon.coupon\_redeem\_on\_behalf\` scope is only required if the service should use the customer identification specified in the request query (\`customerNumber\` attribute) instead of the one associated with current authentication token.
```json
{"openapi":"3.0.0","info":{"title":"Coupon Service","version":"0.0.1"},"tags":[{"name":"Coupon Management"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["coupon.coupon_redeem_on_behalf"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"coupon.coupon_read":"Needed to read coupons.","coupon.coupon_manage":"Needed to manage coupons.","coupon.coupon_redeem":"Needed to redeem coupons.","coupon.coupon_redeem_on_behalf":"Needed to redeem coupons on behalf of another customer."}}}}},"schemas":{"coupon":{"allOf":[{"$ref":"#/components/schemas/base-coupon"},{"type":"object","properties":{"legalEntityRedemptions":{"type":"array","items":{"type":"object","properties":{"legalEntityId":{"type":"string","description":"The id of the legal entity to which customer is assigned."},"count":{"type":"number","description":"The number of times a specific coupon has been redeemed in the context of the given legal entity."}}}},"redemptionCount":{"type":"number","description":"The number of times a specific coupon has been redeemed. Read-only, set through server. (seller-only)."},"referralCoupon":{"$ref":"#/components/schemas/referralCouponProperty"},"deleted":{"description":"Flag to mark a coupon as deleted (a.k.a. Soft delete). It is a read-only and seller-only attribute.","type":"boolean"}},"required":["name","discountType"]}]},"base-coupon":{"title":"Coupon response/update payload","description":"Coupons describe voucher alike commerce capabilities, e.g. 10% off winter accessories.","type":"object","properties":{"name":{"type":"string","description":"Coupon name."},"description":{"type":"string","description":"Coupon description."},"discountType":{"enum":["PERCENT","ABSOLUTE","FREE_SHIPPING"],"description":"'PERCENT' for relative values, 'ABSOLUTE' for float values, referring to a specific currency, 'FREE_SHIPPING' for reducing the shipping cost to 0.","type":"string"},"discountPercentage":{"type":"number","description":"A discount percentage within the range [0.00, 100.00]. Must be specified only if type is 'PERCENT'.","minimum":0,"maximum":100},"discountAbsolute":{"type":"object","description":"Must be specified only if type is 'ABSOLUTE'. Defines the amount that should be substracted from the cart subtotal.","properties":{"amount":{"type":"number","description":"Total amount in the specified currency."},"currency":{"type":"string","description":"ISO 4217 currency code, e.g.: USD, EUR, CHF."}}},"allowAnonymous":{"type":"boolean","description":"Specifies if the coupon can be redeemed by anonymous user. If set to false, only logged-in customers can redeem it.","default":false},"maxRedemptions":{"type":"number","description":"Maximum number of redemptions; -1 designates 'unlimited' (seller-only).","default":-1},"maxRedemptionsPerCustomer":{"type":"number","description":"Maximum number of redemptions per customer; -1 designates 'unlimited'. Cannot be specified for coupons which can be redeemed by anonymous users.","default":-1},"discountCalculationType":{"type":"string","enum":["TOTAL","SUBTOTAL"],"description":"Determines whether the coupon is applied to the total or subtotal value of the order.","default":"SUBTOTAL"},"categoryRestricted":{"$ref":"#/components/schemas/categoryRestricted"},"segmentRestricted":{"$ref":"#/components/schemas/segmentRestricted"},"restrictions":{"$ref":"#/components/schemas/restrictions"},"issuedTo":{"type":"string","description":"The Id of the customer who originally received the coupon (seller-only)."},"mixins":{"type":"object","description":"The field contains mixins values.","additionalProperties":true},"metadata":{"type":"object","additionalProperties":false,"properties":{"version":{"description":"Version of the document. Set to 0 after creating a document. Increments by 1 after every update.","type":"number"},"mixins":{"type":"object","description":"Links to the mixin schemas.","additionalProperties":{"type":"string"}}}}}},"categoryRestricted":{"type":"boolean","description":"Defines if the coupon has category restrictions.\n***\nInfo: Cannot be combined together with the segment restrictions.\n","default":false},"segmentRestricted":{"type":"boolean","description":"Defines if the coupon has segment restrictions. If the value is set to `true`, the `restrictions.segments` must be provided.\n***\nInfo: Cannot be combined neither with the category restrictions nor with customers restrictions.\n","default":false},"restrictions":{"type":"object","description":"Restrictions of the coupon.","properties":{"validFor":{"type":"array","description":"A list of customer identifiers for whom the coupon can be redeemed. Cannot be specified for coupons which can be redeemed by anonymous users.","items":{"type":"string"}},"validFrom":{"type":"string","format":"date-time","description":"Must be provided in ISO 8601 format (http://www.iso.org/iso/home/standards/iso8601.htm), e.g. '2015-01-31T23:59:59.999Z'."},"validUntil":{"type":"string","format":"date-time","description":"Must be provided in ISO 8601 format (http://www.iso.org/iso/home/standards/iso8601.htm), e.g. '2015-01-31T23:59:59.999Z'."},"minOrderValue":{"$ref":"#/components/schemas/currency-amount"},"includedCategories":{"type":"array","description":"The list of product's categories to which this coupon applies to. Must be defined only if the `categoryRestricted` flag is set to true. Must be disjoint with excludedCategories list.","items":{"type":"string"}},"excludedCategories":{"type":"array","description":"The list of product's categories to which this coupon does not apply to. Can be defined only if the `categoryRestricted` flag is set to true. Must be disjoint with includedCategories list.","items":{"type":"string"}},"segments":{"type":"array","description":"The list of segments to which this coupon applies to. Can be defined only if the `segmentRestricted` flag is set to true.","items":{"type":"string"}}}},"currency-amount":{"type":"object","title":"Money amount","description":"Defines an amount in a specific currency.","properties":{"amount":{"type":"number","default":0,"minimum":0,"description":"Total amount in the specified currency."},"currency":{"type":"string","default":"USD","pattern":"^[A-Z]{3}$","description":"ISO 4217 currency code, e.g.: USD, EUR, CHF."}}},"referralCouponProperty":{"type":"boolean","description":"Indicates if the coupon is type of referral coupon. This property is read only."}},"responses":{"trait_queryable_400":{"description":"Request syntactically incorrect. Details of the error are included in the response payload.","content":{"application/json":{"schema":{"title":"error","description":"Schema for API specified errors.","type":"object","properties":{"status":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error type, lower case with underscore eg validation_failure.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"errorDetail","description":"Schema for specific error cause.","type":"object","properties":{"field":{"description":"A bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific.","type":"string"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.","type":"string"},"message":{"description":"Descriptive error detail message for debugging.","type":"string"},"moreInfo":{"type":"string","description":"Link to documentation to investigate further and finding support for error detail."}},"required":["type"]}}},"required":["status","type"]}}}},"trait_unauthorized_401":{"description":"Example response","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"trait_notFound_404":{"description":"The requested resource does not exist.\n","content":{"application/json":{"schema":{"title":"error","description":"Schema for API specified errors.","type":"object","properties":{"status":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error type, lower case with underscore eg validation_failure.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"}},"required":["status","type"]}}}},"trait_internal_500":{"description":"Some server side error occurred.\n","content":{"application/json":{"schema":{"title":"error","description":"Schema for API specified errors.","type":"object","properties":{"status":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error type, lower case with underscore eg validation_failure.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"errorDetail","description":"Schema for specific error cause.","type":"object","properties":{"field":{"description":"A bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific.","type":"string"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.","type":"string"},"message":{"description":"Descriptive error detail message for debugging.","type":"string"},"moreInfo":{"type":"string","description":"Link to documentation to investigate further and finding support for error detail."}},"required":["type"]}}},"required":["status","type"]}}}}},"parameters":{"customer_number":{"name":"customerNumber","in":"query","required":false,"description":"Customer number (ID) of customer on behalf of which we request coupon information.\nNeeded only in case of retrieving coupon eligible for other customer than the caller.\n","schema":{"type":"string"}}}},"paths":{"/coupon/{tenant}/coupons/{code}":{"get":{"summary":"Retrieving information about particular coupon by code","tags":["Coupon Management"],"responses":{"200":{"description":"The coupon has been successfully retrieved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coupon"}}}},"400":{"$ref":"#/components/responses/trait_queryable_400"},"401":{"$ref":"#/components/responses/trait_unauthorized_401"},"404":{"$ref":"#/components/responses/trait_notFound_404"},"500":{"$ref":"#/components/responses/trait_internal_500"}},"description":"Retrieves coupon details.\n***\n\n### Additional scopes info\n* The `coupon.coupon_redeem_on_behalf` scope is only required if the service should use the customer identification specified in the request query (`customerNumber` attribute) instead of the one associated with current authentication token.\n","operationId":"GET-coupon-retrieve-coupon","parameters":[{"$ref":"#/components/parameters/customer_number"}]}}}}
```
## Updating the coupon by code
> Updates an existing coupon.
```json
{"openapi":"3.0.0","info":{"title":"Coupon Service","version":"0.0.1"},"tags":[{"name":"Coupon Management"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["coupon.coupon_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"coupon.coupon_read":"Needed to read coupons.","coupon.coupon_manage":"Needed to manage coupons.","coupon.coupon_redeem":"Needed to redeem coupons.","coupon.coupon_redeem_on_behalf":"Needed to redeem coupons on behalf of another customer."}}}}},"responses":{"trait_queryable_400":{"description":"Request syntactically incorrect. Details of the error are included in the response payload.","content":{"application/json":{"schema":{"title":"error","description":"Schema for API specified errors.","type":"object","properties":{"status":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error type, lower case with underscore eg validation_failure.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"errorDetail","description":"Schema for specific error cause.","type":"object","properties":{"field":{"description":"A bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific.","type":"string"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.","type":"string"},"message":{"description":"Descriptive error detail message for debugging.","type":"string"},"moreInfo":{"type":"string","description":"Link to documentation to investigate further and finding support for error detail."}},"required":["type"]}}},"required":["status","type"]}}}},"trait_unauthorized_401":{"description":"Example response","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"trait_restricted_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"title":"error","description":"Schema for API specified errors.","type":"object","properties":{"status":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error type, lower case with underscore eg validation_failure.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"}},"required":["status","type"]}}}},"trait_notFound_404":{"description":"The requested resource does not exist.\n","content":{"application/json":{"schema":{"title":"error","description":"Schema for API specified errors.","type":"object","properties":{"status":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error type, lower case with underscore eg validation_failure.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"}},"required":["status","type"]}}}},"trait_conflict_409":{"description":"Creation failed because there was a conflict with another resource. Details of the error are included in the response payload.\n","content":{"application/json":{"schema":{"title":"error","description":"Schema for API specified errors.","type":"object","properties":{"status":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error type, lower case with underscore eg validation_failure.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"}},"required":["status","type"]}}}},"trait_internal_500":{"description":"Some server side error occurred.\n","content":{"application/json":{"schema":{"title":"error","description":"Schema for API specified errors.","type":"object","properties":{"status":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error type, lower case with underscore eg validation_failure.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"errorDetail","description":"Schema for specific error cause.","type":"object","properties":{"field":{"description":"A bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific.","type":"string"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.","type":"string"},"message":{"description":"Descriptive error detail message for debugging.","type":"string"},"moreInfo":{"type":"string","description":"Link to documentation to investigate further and finding support for error detail."}},"required":["type"]}}},"required":["status","type"]}}}}},"schemas":{"base-coupon":{"title":"Coupon response/update payload","description":"Coupons describe voucher alike commerce capabilities, e.g. 10% off winter accessories.","type":"object","properties":{"name":{"type":"string","description":"Coupon name."},"description":{"type":"string","description":"Coupon description."},"discountType":{"enum":["PERCENT","ABSOLUTE","FREE_SHIPPING"],"description":"'PERCENT' for relative values, 'ABSOLUTE' for float values, referring to a specific currency, 'FREE_SHIPPING' for reducing the shipping cost to 0.","type":"string"},"discountPercentage":{"type":"number","description":"A discount percentage within the range [0.00, 100.00]. Must be specified only if type is 'PERCENT'.","minimum":0,"maximum":100},"discountAbsolute":{"type":"object","description":"Must be specified only if type is 'ABSOLUTE'. Defines the amount that should be substracted from the cart subtotal.","properties":{"amount":{"type":"number","description":"Total amount in the specified currency."},"currency":{"type":"string","description":"ISO 4217 currency code, e.g.: USD, EUR, CHF."}}},"allowAnonymous":{"type":"boolean","description":"Specifies if the coupon can be redeemed by anonymous user. If set to false, only logged-in customers can redeem it.","default":false},"maxRedemptions":{"type":"number","description":"Maximum number of redemptions; -1 designates 'unlimited' (seller-only).","default":-1},"maxRedemptionsPerCustomer":{"type":"number","description":"Maximum number of redemptions per customer; -1 designates 'unlimited'. Cannot be specified for coupons which can be redeemed by anonymous users.","default":-1},"discountCalculationType":{"type":"string","enum":["TOTAL","SUBTOTAL"],"description":"Determines whether the coupon is applied to the total or subtotal value of the order.","default":"SUBTOTAL"},"categoryRestricted":{"$ref":"#/components/schemas/categoryRestricted"},"segmentRestricted":{"$ref":"#/components/schemas/segmentRestricted"},"restrictions":{"$ref":"#/components/schemas/restrictions"},"issuedTo":{"type":"string","description":"The Id of the customer who originally received the coupon (seller-only)."},"mixins":{"type":"object","description":"The field contains mixins values.","additionalProperties":true},"metadata":{"type":"object","additionalProperties":false,"properties":{"version":{"description":"Version of the document. Set to 0 after creating a document. Increments by 1 after every update.","type":"number"},"mixins":{"type":"object","description":"Links to the mixin schemas.","additionalProperties":{"type":"string"}}}}}},"categoryRestricted":{"type":"boolean","description":"Defines if the coupon has category restrictions.\n***\nInfo: Cannot be combined together with the segment restrictions.\n","default":false},"segmentRestricted":{"type":"boolean","description":"Defines if the coupon has segment restrictions. If the value is set to `true`, the `restrictions.segments` must be provided.\n***\nInfo: Cannot be combined neither with the category restrictions nor with customers restrictions.\n","default":false},"restrictions":{"type":"object","description":"Restrictions of the coupon.","properties":{"validFor":{"type":"array","description":"A list of customer identifiers for whom the coupon can be redeemed. Cannot be specified for coupons which can be redeemed by anonymous users.","items":{"type":"string"}},"validFrom":{"type":"string","format":"date-time","description":"Must be provided in ISO 8601 format (http://www.iso.org/iso/home/standards/iso8601.htm), e.g. '2015-01-31T23:59:59.999Z'."},"validUntil":{"type":"string","format":"date-time","description":"Must be provided in ISO 8601 format (http://www.iso.org/iso/home/standards/iso8601.htm), e.g. '2015-01-31T23:59:59.999Z'."},"minOrderValue":{"$ref":"#/components/schemas/currency-amount"},"includedCategories":{"type":"array","description":"The list of product's categories to which this coupon applies to. Must be defined only if the `categoryRestricted` flag is set to true. Must be disjoint with excludedCategories list.","items":{"type":"string"}},"excludedCategories":{"type":"array","description":"The list of product's categories to which this coupon does not apply to. Can be defined only if the `categoryRestricted` flag is set to true. Must be disjoint with includedCategories list.","items":{"type":"string"}},"segments":{"type":"array","description":"The list of segments to which this coupon applies to. Can be defined only if the `segmentRestricted` flag is set to true.","items":{"type":"string"}}}},"currency-amount":{"type":"object","title":"Money amount","description":"Defines an amount in a specific currency.","properties":{"amount":{"type":"number","default":0,"minimum":0,"description":"Total amount in the specified currency."},"currency":{"type":"string","default":"USD","pattern":"^[A-Z]{3}$","description":"ISO 4217 currency code, e.g.: USD, EUR, CHF."}}}},"parameters":{"partial":{"name":"partial","in":"query","required":true,"description":"If true, a partial update will be supported, otherwise the full object replacement will be performed.\n\nThis parameter is DEPRECATED. For partial updates, please use PATCH method instead.\n","schema":{"type":"boolean"}}}},"paths":{"/coupon/{tenant}/coupons/{code}":{"put":{"summary":"Updating the coupon by code","tags":["Coupon Management"],"responses":{"200":{"description":"The coupon has been successfully updated."},"400":{"$ref":"#/components/responses/trait_queryable_400"},"401":{"$ref":"#/components/responses/trait_unauthorized_401"},"403":{"$ref":"#/components/responses/trait_restricted_403"},"404":{"$ref":"#/components/responses/trait_notFound_404"},"409":{"$ref":"#/components/responses/trait_conflict_409"},"500":{"$ref":"#/components/responses/trait_internal_500"}},"description":"Updates an existing coupon.\n","operationId":"PUT-coupon-update-coupon","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/base-coupon"}}},"required":true},"parameters":[{"$ref":"#/components/parameters/partial"}]}}}}
```
## Deleting a coupon by code
> Deletes an existing coupon.
```json
{"openapi":"3.0.0","info":{"title":"Coupon Service","version":"0.0.1"},"tags":[{"name":"Coupon Management"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["coupon.coupon_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"coupon.coupon_read":"Needed to read coupons.","coupon.coupon_manage":"Needed to manage coupons.","coupon.coupon_redeem":"Needed to redeem coupons.","coupon.coupon_redeem_on_behalf":"Needed to redeem coupons on behalf of another customer."}}}}},"responses":{"trait_queryable_400":{"description":"Request syntactically incorrect. Details of the error are included in the response payload.","content":{"application/json":{"schema":{"title":"error","description":"Schema for API specified errors.","type":"object","properties":{"status":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error type, lower case with underscore eg validation_failure.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"errorDetail","description":"Schema for specific error cause.","type":"object","properties":{"field":{"description":"A bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific.","type":"string"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.","type":"string"},"message":{"description":"Descriptive error detail message for debugging.","type":"string"},"moreInfo":{"type":"string","description":"Link to documentation to investigate further and finding support for error detail."}},"required":["type"]}}},"required":["status","type"]}}}},"trait_unauthorized_401":{"description":"Example response","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"trait_restricted_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"title":"error","description":"Schema for API specified errors.","type":"object","properties":{"status":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error type, lower case with underscore eg validation_failure.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"}},"required":["status","type"]}}}},"trait_notFound_404":{"description":"The requested resource does not exist.\n","content":{"application/json":{"schema":{"title":"error","description":"Schema for API specified errors.","type":"object","properties":{"status":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error type, lower case with underscore eg validation_failure.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"}},"required":["status","type"]}}}},"trait_internal_500":{"description":"Some server side error occurred.\n","content":{"application/json":{"schema":{"title":"error","description":"Schema for API specified errors.","type":"object","properties":{"status":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error type, lower case with underscore eg validation_failure.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"errorDetail","description":"Schema for specific error cause.","type":"object","properties":{"field":{"description":"A bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific.","type":"string"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.","type":"string"},"message":{"description":"Descriptive error detail message for debugging.","type":"string"},"moreInfo":{"type":"string","description":"Link to documentation to investigate further and finding support for error detail."}},"required":["type"]}}},"required":["status","type"]}}}}}},"paths":{"/coupon/{tenant}/coupons/{code}":{"delete":{"summary":"Deleting a coupon by code","tags":["Coupon Management"],"responses":{"204":{"description":"Coupon with given code has been successfully deleted."},"400":{"$ref":"#/components/responses/trait_queryable_400"},"401":{"$ref":"#/components/responses/trait_unauthorized_401"},"403":{"$ref":"#/components/responses/trait_restricted_403"},"404":{"$ref":"#/components/responses/trait_notFound_404"},"500":{"$ref":"#/components/responses/trait_internal_500"}},"description":"Deletes an existing coupon.\n","operationId":"DELETE-coupon-remove-coupon"}}}}
```
## Partially updating the coupon by code
> Partially updates an existing coupon.
```json
{"openapi":"3.0.0","info":{"title":"Coupon Service","version":"0.0.1"},"tags":[{"name":"Coupon Management"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["coupon.coupon_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"coupon.coupon_read":"Needed to read coupons.","coupon.coupon_manage":"Needed to manage coupons.","coupon.coupon_redeem":"Needed to redeem coupons.","coupon.coupon_redeem_on_behalf":"Needed to redeem coupons on behalf of another customer."}}}}},"responses":{"trait_queryable_400":{"description":"Request syntactically incorrect. Details of the error are included in the response payload.","content":{"application/json":{"schema":{"title":"error","description":"Schema for API specified errors.","type":"object","properties":{"status":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error type, lower case with underscore eg validation_failure.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"errorDetail","description":"Schema for specific error cause.","type":"object","properties":{"field":{"description":"A bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific.","type":"string"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.","type":"string"},"message":{"description":"Descriptive error detail message for debugging.","type":"string"},"moreInfo":{"type":"string","description":"Link to documentation to investigate further and finding support for error detail."}},"required":["type"]}}},"required":["status","type"]}}}},"trait_unauthorized_401":{"description":"Example response","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"trait_restricted_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"title":"error","description":"Schema for API specified errors.","type":"object","properties":{"status":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error type, lower case with underscore eg validation_failure.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"}},"required":["status","type"]}}}},"trait_notFound_404":{"description":"The requested resource does not exist.\n","content":{"application/json":{"schema":{"title":"error","description":"Schema for API specified errors.","type":"object","properties":{"status":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error type, lower case with underscore eg validation_failure.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"}},"required":["status","type"]}}}},"trait_conflict_409":{"description":"Creation failed because there was a conflict with another resource. Details of the error are included in the response payload.\n","content":{"application/json":{"schema":{"title":"error","description":"Schema for API specified errors.","type":"object","properties":{"status":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error type, lower case with underscore eg validation_failure.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"}},"required":["status","type"]}}}},"trait_internal_500":{"description":"Some server side error occurred.\n","content":{"application/json":{"schema":{"title":"error","description":"Schema for API specified errors.","type":"object","properties":{"status":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error type, lower case with underscore eg validation_failure.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"errorDetail","description":"Schema for specific error cause.","type":"object","properties":{"field":{"description":"A bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific.","type":"string"},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","description":"Classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.","type":"string"},"message":{"description":"Descriptive error detail message for debugging.","type":"string"},"moreInfo":{"type":"string","description":"Link to documentation to investigate further and finding support for error detail."}},"required":["type"]}}},"required":["status","type"]}}}}},"schemas":{"base-coupon":{"title":"Coupon response/update payload","description":"Coupons describe voucher alike commerce capabilities, e.g. 10% off winter accessories.","type":"object","properties":{"name":{"type":"string","description":"Coupon name."},"description":{"type":"string","description":"Coupon description."},"discountType":{"enum":["PERCENT","ABSOLUTE","FREE_SHIPPING"],"description":"'PERCENT' for relative values, 'ABSOLUTE' for float values, referring to a specific currency, 'FREE_SHIPPING' for reducing the shipping cost to 0.","type":"string"},"discountPercentage":{"type":"number","description":"A discount percentage within the range [0.00, 100.00]. Must be specified only if type is 'PERCENT'.","minimum":0,"maximum":100},"discountAbsolute":{"type":"object","description":"Must be specified only if type is 'ABSOLUTE'. Defines the amount that should be substracted from the cart subtotal.","properties":{"amount":{"type":"number","description":"Total amount in the specified currency."},"currency":{"type":"string","description":"ISO 4217 currency code, e.g.: USD, EUR, CHF."}}},"allowAnonymous":{"type":"boolean","description":"Specifies if the coupon can be redeemed by anonymous user. If set to false, only logged-in customers can redeem it.","default":false},"maxRedemptions":{"type":"number","description":"Maximum number of redemptions; -1 designates 'unlimited' (seller-only).","default":-1},"maxRedemptionsPerCustomer":{"type":"number","description":"Maximum number of redemptions per customer; -1 designates 'unlimited'. Cannot be specified for coupons which can be redeemed by anonymous users.","default":-1},"discountCalculationType":{"type":"string","enum":["TOTAL","SUBTOTAL"],"description":"Determines whether the coupon is applied to the total or subtotal value of the order.","default":"SUBTOTAL"},"categoryRestricted":{"$ref":"#/components/schemas/categoryRestricted"},"segmentRestricted":{"$ref":"#/components/schemas/segmentRestricted"},"restrictions":{"$ref":"#/components/schemas/restrictions"},"issuedTo":{"type":"string","description":"The Id of the customer who originally received the coupon (seller-only)."},"mixins":{"type":"object","description":"The field contains mixins values.","additionalProperties":true},"metadata":{"type":"object","additionalProperties":false,"properties":{"version":{"description":"Version of the document. Set to 0 after creating a document. Increments by 1 after every update.","type":"number"},"mixins":{"type":"object","description":"Links to the mixin schemas.","additionalProperties":{"type":"string"}}}}}},"categoryRestricted":{"type":"boolean","description":"Defines if the coupon has category restrictions.\n***\nInfo: Cannot be combined together with the segment restrictions.\n","default":false},"segmentRestricted":{"type":"boolean","description":"Defines if the coupon has segment restrictions. If the value is set to `true`, the `restrictions.segments` must be provided.\n***\nInfo: Cannot be combined neither with the category restrictions nor with customers restrictions.\n","default":false},"restrictions":{"type":"object","description":"Restrictions of the coupon.","properties":{"validFor":{"type":"array","description":"A list of customer identifiers for whom the coupon can be redeemed. Cannot be specified for coupons which can be redeemed by anonymous users.","items":{"type":"string"}},"validFrom":{"type":"string","format":"date-time","description":"Must be provided in ISO 8601 format (http://www.iso.org/iso/home/standards/iso8601.htm), e.g. '2015-01-31T23:59:59.999Z'."},"validUntil":{"type":"string","format":"date-time","description":"Must be provided in ISO 8601 format (http://www.iso.org/iso/home/standards/iso8601.htm), e.g. '2015-01-31T23:59:59.999Z'."},"minOrderValue":{"$ref":"#/components/schemas/currency-amount"},"includedCategories":{"type":"array","description":"The list of product's categories to which this coupon applies to. Must be defined only if the `categoryRestricted` flag is set to true. Must be disjoint with excludedCategories list.","items":{"type":"string"}},"excludedCategories":{"type":"array","description":"The list of product's categories to which this coupon does not apply to. Can be defined only if the `categoryRestricted` flag is set to true. Must be disjoint with includedCategories list.","items":{"type":"string"}},"segments":{"type":"array","description":"The list of segments to which this coupon applies to. Can be defined only if the `segmentRestricted` flag is set to true.","items":{"type":"string"}}}},"currency-amount":{"type":"object","title":"Money amount","description":"Defines an amount in a specific currency.","properties":{"amount":{"type":"number","default":0,"minimum":0,"description":"Total amount in the specified currency."},"currency":{"type":"string","default":"USD","pattern":"^[A-Z]{3}$","description":"ISO 4217 currency code, e.g.: USD, EUR, CHF."}}}}},"paths":{"/coupon/{tenant}/coupons/{code}":{"patch":{"summary":"Partially updating the coupon by code","tags":["Coupon Management"],"responses":{"200":{"description":"The coupon has been successfully updated."},"400":{"$ref":"#/components/responses/trait_queryable_400"},"401":{"$ref":"#/components/responses/trait_unauthorized_401"},"403":{"$ref":"#/components/responses/trait_restricted_403"},"404":{"$ref":"#/components/responses/trait_notFound_404"},"409":{"$ref":"#/components/responses/trait_conflict_409"},"500":{"$ref":"#/components/responses/trait_internal_500"}},"description":"Partially updates an existing coupon.\n","operationId":"PATCH-coupon-update-coupon","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/base-coupon"}}},"required":true}}}}}
```
---
# 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/rewards-and-promotions/coupon/api-reference/coupon-management.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.