# Referral Coupon Management
## Retrieving customer's referral coupon
> Retrieves the referral coupon of a given customer in the database.\
> \
> When the existing customer shares the referral code with a potential customer, the referred customer can benefit from the discount in a form of a fixed monetary amount.
```json
{"openapi":"3.0.0","info":{"title":"Coupon Service","version":"0.0.1"},"tags":[{"name":"Referral Coupon Management"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":[]}],"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":{"referralCoupon":{"title":"Coupon","description":"Coupons describe voucher alike commerce capabilities.","type":"object","properties":{"code":{"type":"string","description":"e.g.: WINTER-SALE, 10OFF (read-only)"},"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.\n","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"}]},"allowAnonymous":{"type":"boolean","description":"Specifies if the coupon can be redeemed by anonymous users.","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},"restrictions":{"type":"object","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"}}},"issuedTo":{"type":"string","description":"The Id of the customer who originally received the coupon (seller-only)."},"referralCoupon":{"$ref":"#/components/schemas/referralCouponProperty"},"redemptionCount":{"type":"number","description":"The number of times a specific coupon has been redeemed. Read-only, set through server (seller-only)."},"status":{"enum":["INACTIVE","VALID","EXPIRED","USED"],"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.","type":"string"},"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"},"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":["discountType","issuedTo","status","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."}}},"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"]}}}}}},"paths":{"/coupon/{tenant}/referral-coupons/{customerNumber}":{"get":{"summary":"Retrieving customer's referral coupon","tags":["Referral Coupon Management"],"responses":{"200":{"description":"The referral coupon has been successfully retrieved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/referralCoupon"}}}},"204":{"description":"No content if there is no referral 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 the referral coupon of a given customer in the database.\n\nWhen the existing customer shares the referral code with a potential customer, the referred customer can benefit from the discount in a form of a fixed monetary amount.\n","operationId":"GET-coupon-retrieve-referral-coupon"}}}}
```
## Creating a referral coupon code for a given customer
> Creates a referral coupon code for a specific customer in the database. If the coupon code exists, returns it without creating a new coupon.\
> \
> \*\*Note\*\*: There can only be one referral coupon generated per customer.\
> \
> When the existing customer shares the referral code with a potential customer, the referred customer can benefit from the discount in a form of a fixed monetary amount.
```json
{"openapi":"3.0.0","info":{"title":"Coupon Service","version":"0.0.1"},"tags":[{"name":"Referral Coupon Management"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":[]}],"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":{"referralCoupon":{"title":"Coupon","description":"Coupons describe voucher alike commerce capabilities.","type":"object","properties":{"code":{"type":"string","description":"e.g.: WINTER-SALE, 10OFF (read-only)"},"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.\n","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"}]},"allowAnonymous":{"type":"boolean","description":"Specifies if the coupon can be redeemed by anonymous users.","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},"restrictions":{"type":"object","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"}}},"issuedTo":{"type":"string","description":"The Id of the customer who originally received the coupon (seller-only)."},"referralCoupon":{"$ref":"#/components/schemas/referralCouponProperty"},"redemptionCount":{"type":"number","description":"The number of times a specific coupon has been redeemed. Read-only, set through server (seller-only)."},"status":{"enum":["INACTIVE","VALID","EXPIRED","USED"],"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.","type":"string"},"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"},"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":["discountType","issuedTo","status","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."}}},"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"]}}}}}},"paths":{"/coupon/{tenant}/referral-coupons/{customerNumber}":{"post":{"summary":"Creating a referral coupon code for a given customer","tags":["Referral Coupon Management"],"responses":{"200":{"description":"The referral coupon code has been successfully retrieved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/referralCoupon"}}}},"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":"Creates a referral coupon code for a specific customer in the database. If the coupon code exists, returns it without creating a new coupon.\n\n**Note**: There can only be one referral coupon generated per customer.\n\nWhen the existing customer shares the referral code with a potential customer, the referred customer can benefit from the discount in a form of a fixed monetary amount.\n","operationId":"POST-coupon-create-referral-coupon-code"}}}}
```
---
# 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/referral-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.