Coupon Service

Coupon-v2 Service Api

This is the documentation for version v2.0 of the API. Last update on Jul 2, 2021.

Base URL
https://api.emporix.io/coupon-v2

Coupons

Retrieves a list of coupons

Retrieves a list of coupons. The caller must have the coupon.coupon_manage scope assigned when retrieving a coupons.

Headers
  • authorization Required / string

    Bearer token

Path parameters
  • tenant Required / string

    The tenant that the caller is acting upon.

    Please note that this value is always lowercase.

Query parameters
  • showDeleted boolean

    Includes deleted coupons in the result.

  • sort string

    The list of comma-separated properties used to sort the results.
    By default, the column values are sorted in ascending order.
    Can either be in the form of fieldName or fieldName:asc,fieldName:desc.
    If you want to sort by localized attributes, you must use the following form:
    fieldName.language or fieldName.language:asc,fieldName.language:desc.

  • pageNumber integer

    The page number to be retrieved where the size of the pages must be specified by the pageSize parameter.
    The number of the first page is 1.

    Minimum value is 1. Default value is 1.

  • pageSize integer

    The number of documents being retrieved on the page.

    Minimum value is 1. Default value is 16.

  • totalCount boolean

    This parameter requests to return the total number of object in the collection fulfilling
    the criteria together with the response. This number will be returned in the 'items-count'
    header.

  • q string

    The simple query criteria based on available fields to limit returned results or a set of modified documents.

Responses
  • 200 array[object]

    List of properties

    • items-count integer

      The total number of objects that fulfil the criteria.

    • code string
    • name string
    • description string
    • discountType string
    • disctountAbsolute object
      • amount number
      • currency string
    • allowAnonymous boolean
    • maxRedemptions integer
    • redemptionCount integer
    • restrictions object
      • validFrom string(date-time)
      • validUntil string(date-time)
      • minOrderValue object
        • amount number
        • currency string
    • issuedTo string
    • status string
    • metadata object
      • status string
  • 400 object

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

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 403 object

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

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 500 object

    Some server side error occurred.

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

GET /{tenant}/coupons
$ curl \
 -X GET https://api.emporix.io/coupon-v2/{tenant}/coupons \
 -H "authorization: string"
Response example (200)
# Headers
items-count: 42

# Payload
[
  {
    "code": "ENG2OC?",
    "name": "Winter Sale 2014",
    "description": "Great Winter Discount of 25 USD in December 2014 and January 2015 for all Orders over 50 USD",
    "discountType": "ABSOLUTE",
    "discountAbsolute": {
      "amount": 24.99,
      "currency": "USD"
    },
    "allowAnonymous": false,
    "maxRedemptions": -1,
    "redemptionCount": 30,
    "restrictions": {
      "validFrom": "2014-12-01T00:00:00.000Z",
      "validUntil": "2015-01-31T23:59:59.999Z",
      "minOrderValue": {
        "amount": 49.99,
        "currency": "USD"
      }
    },
    "issuedTo": "C01234567989",
    "status": "VALID",
    "metadata": {
      "version": 1
    }
  }
]
Response example (400)
{
  "status": 400,
  "message": "There are validation problems, see details section for more information",
  "type": "validation_violation",
  "details": [
    {
      "field": "q",
      "message": "not a valid query",
      "type": "invalid_query_parameter"
    }
  ]
}
Response example (403)
{
  "status": 403,
  "message": "Not allowed to access this resource",
  "type": "insufficient_permissions"
}
Response example (500)
{
  "status": 500,
  "message": "Something went wrong while processing the request. Please contact the administrator.",
  "type": "internal_service_error"
}

Creates a coupon

Creates a coupon.

Requires scope coupon.coupon_manage.

Headers
  • authorization Required / string

    Bearer token

Path parameters
  • tenant Required / string

    The tenant that the caller is acting upon.

    Please note that this value is always lowercase.

Body
  • code string

    e.g.: WINTER-SALE, 10OFF. If not provided, a code will be auto generated.

  • name Required / string

    Localized name

  • description string

    Localized description

  • discountType

    'PERCENT' for relative values or 'ABSOLUTE' for float values, referring to a specific currency.

    Values are PERCENT and ABSOLUTE.

  • discountPercentage number

    A discount percentage within the range [0.00, 100.00]. Required if type is 'PERCENT'.

    Minimum value is 0, maximum value is 100.

  • discountAbsolute object

    Defines an amount in a specific currency

    • amount number

      The total amount in the specified currency.

      Minimum value is 0. Default value is 0.

    • currency string

      ISO 4217 currency code, e.g.: USD, EUR, CHF

      Default value is USD.

  • allowAnonymous boolean

    Can the coupon be redeemed by anonymous user

  • maxRedemptions number

    Maximum number of redemptions; -1 designates 'unlimited' (seller-only)

    Default value is -1.

  • maxRedemptionsPerCustomer number

    Maximum number of redemptions per customer; -1 designates 'unlimited'. Cannot be specified for coupons which can be redeemed by anonymous users.

    Default value is -1.

  • restrictions object
    • validFor array[string]

      A list of customer identifiers, which can redeem the coupon. Cannot be specified for coupons which can be redeemed by anonymous users.

    • validFrom string(date-time)

      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 string(date-time)

      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 object

      Defines an amount in a specific currency

      • amount number

        The total amount in the specified currency.

        Minimum value is 0. Default value is 0.

      • currency string

        ISO 4217 currency code, e.g.: USD, EUR, CHF

        Default value is USD.

  • issuedTo string

    The Id of the customer who originally received the coupon (seller-only).

Responses
  • 201 object

    The collection resource has been successfully created.

    • Location string

      The Location of the new resource which was created by the request.
      The value consists of a single absolute URI.

    • id string
    • link string
  • 400 object

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

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 403 object

    Given authorization scopes are not sufficient and do not match required scopes.

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 409 object

    Creation failed because there was a conflict with another resource. Any details will be provided within the response payload.

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 500 object

    Some server side error occurred.

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

POST /{tenant}/coupons
$ curl \
 -X POST https://api.emporix.io/coupon-v2/{tenant}/coupons \
 -H "Content-Type: application/json" \
 -H "authorization: string" \
 -d '{"code":"ENG2OC?","name":"Winter Sale 2018","description":"Great Winter Discount of 25 USD in December 2018 and January 2019 for all Orders over 50 USD","discountType":"ABSOLUTE","discountAbsolute":{"amount":24.99,"currency":"USD"},"allowAnonymous":false,"maxRedemptions":-1,"maxRedemptionsPerCustomer":-1,"restrictions":{"validFor":["C0123456789","C0123456788"],"validFrom":"2014-12-01T00:00:00.000Z","validUntil":"2015-01-31T23:59:59.999Z","minOrderValue":{"amount":49.99,"currency":"USD"}},"is...}'
Request payload example
# Headers
authorization: string

# Payload
{
  "code": "ENG2OC?",
  "name": "Winter Sale 2018",
  "description": "Great Winter Discount of 25 USD in December 2018 and January 2019 for all Orders over 50 USD",
  "discountType": "ABSOLUTE",
  "discountAbsolute": {
    "amount": 24.99,
    "currency": "USD"
  },
  "allowAnonymous": false,
  "maxRedemptions": -1,
  "maxRedemptionsPerCustomer": -1,
  "restrictions": {
    "validFor": [
      "C0123456789",
      "C0123456788"
    ],
    "validFrom": "2014-12-01T00:00:00.000Z",
    "validUntil": "2015-01-31T23:59:59.999Z",
    "minOrderValue": {
      "amount": 49.99,
      "currency": "USD"
    }
  },
  "issuedTo": "C01234567989"
}
Response example (201)
# Headers
Location: string

# Payload
{
  "id": "ENG2OC?",
  "link": "https://api.emporix.io/coupon-v2/tenant-name/coupons/ENG2OC0"
}
Response example (400)
{
  "status": 400,
  "message": "There are validation problems, see details section for more information",
  "type": "validation_violation",
  "details": [
    {
      "field": "tenant",
      "message": "must be between 3 and 16 characters",
      "type": "invalid_header"
    }
  ]
}
Response example (403)
{
  "status": 403,
  "message": "Given request does not have required scopes. It is not authorized to perform this operation.",
  "type": "insufficient_permissions"
}
Response example (409)
{
  "status": 409,
  "message": "The requested resource could not be created due to server-side validation.",
  "type": "conflict_resource"
}
Response example (500)
{
  "status": 500,
  "message": "Something went wrong while processing the request. Please contact the administrator.",
  "type": "internal_service_error"
}

Redemptions

Retrieves a list of redemptions

Retrieves a list of redemptions.

Requires scope coupon.coupon_manage.

Headers
  • authorization Required / string

    Bearer token

Path parameters
  • tenant Required / string

    The tenant that the caller is acting upon.

    Please note that this value is always lowercase.

Query parameters
  • sort string

    The list of comma-separated properties used to sort the results.
    By default, the column values are sorted in ascending order.
    Can either be in the form of fieldName or fieldName:asc,fieldName:desc.
    If you want to sort by localized attributes, you must use the following form:
    fieldName.language or fieldName.language:asc,fieldName.language:desc.

  • pageNumber integer

    The page number to be retrieved where the size of the pages must be specified by the pageSize parameter.
    The number of the first page is 1.

    Minimum value is 1. Default value is 1.

  • pageSize integer

    The number of documents being retrieved on the page.

    Minimum value is 1. Default value is 16.

  • totalCount boolean

    This parameter requests to return the total number of object in the collection fulfilling
    the criteria together with the response. This number will be returned in the 'items-count'
    header.

  • q string

    The simple query criteria based on available fields to limit returned results or a set of modified documents.

Responses
  • 200 array[object]

    List of redemptions

    • items-count integer

      The total number of objects that fulfil the criteria.

    • id string
    • code Required / string
    • customerNumber string
    • orderCode string
    • orderTotal Required / object

      Defines an amount in a specific currency

      • amount number

        The total amount in the specified currency.

        Minimum value is 0. Default value is 0.

      • currency string

        ISO 4217 currency code, e.g.: USD, EUR, CHF

        Default value is USD.

    • discount Required / object

      Defines an amount in a specific currency

      • amount number

        The total amount in the specified currency.

        Minimum value is 0. Default value is 0.

      • currency string

        ISO 4217 currency code, e.g.: USD, EUR, CHF

        Default value is USD.

    • redeemedAt Required / string(date-time)
    • documentFormatVersion number
  • 400 object

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

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 403 object

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

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 404

    A coupon with the provided code does not exist.

  • 500 object

    Some server side error occurred.

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

GET /{tenant}/coupons/{code}/redemptions
$ curl \
 -X GET https://api.emporix.io/coupon-v2/{tenant}/coupons/{code}/redemptions \
 -H "authorization: string"
Response example (200)
# Headers
items-count: 42

# Payload
[
  {
    "id": "60588baca917ae6d2c54cb95",
    "code": "ENG2OC0",
    "customerNumber": "C0123456789",
    "orderCode": "X23RFSU",
    "orderTotal": {
      "amount": 49.99,
      "currency": "USD"
    },
    "discount": {
      "amount": 10,
      "currency": "USD"
    },
    "redeemedAt": "2021-03-22T12:21:00.553Z"
  },
  {
    "id": "60588fdda917ae6e64286d8b",
    "code": "ENG2OC0",
    "customerNumber": "C0123456789",
    "orderCode": "X23RFSU",
    "orderTotal": {
      "amount": 49.99,
      "currency": "USD"
    },
    "discount": {
      "amount": 10,
      "currency": "USD"
    }
  }
]
Response example (400)
{
  "status": 400,
  "message": "There are validation problems, see details section for more information",
  "type": "validation_violation",
  "details": [
    {
      "field": "q",
      "message": "not a valid query",
      "type": "invalid_query_parameter"
    }
  ]
}
Response example (403)
{
  "status": 403,
  "message": "Not allowed to access this resource",
  "type": "insufficient_permissions"
}
Response example (500)
{
  "status": 500,
  "message": "Something went wrong while processing the request. Please contact the administrator.",
  "type": "internal_service_error"
}

Invalidate the coupon based on its validity scope

Invalidate the coupon based on its validity scope.Redemption is not possible when the coupon has exceeded its maximum
number allowed redemptions. To be redeemed a coupon needs to be already valid and not expired yet.

See /{tenant}/coupons/{code} endpoint description for information on required scopes.

Additionally, if coupon.coupon_redeem_on_behalf scope is present, the service will use the customer identification
specified in the request body (customerNumber attribute) instead of the one associated with current
authentication token.

Headers
  • authorization Required / string

    Bearer token

Path parameters
  • tenant Required / string

    The tenant that the caller is acting upon.

    Please note that this value is always lowercase.

Body
  • customerNumber string

    The customer Id of the user, e.g. C0123456789. Can be specified only if coupon.coupon_redeem_on_behalf scope is present.

  • orderCode string

    The order Id of the order for which a coupon has been redeemed.

  • orderTotal Required / object

    Defines an amount in a specific currency

    • amount number

      The total amount in the specified currency.

      Minimum value is 0. Default value is 0.

    • currency string

      ISO 4217 currency code, e.g.: USD, EUR, CHF

      Default value is USD.

  • discount Required / object

    Defines an amount in a specific currency

    • amount number

      The total amount in the specified currency.

      Minimum value is 0. Default value is 0.

    • currency string

      ISO 4217 currency code, e.g.: USD, EUR, CHF

      Default value is USD.

Responses
  • 201 object

    The collection resource has been successfully created.

    • Location string

      The Location of the new resource which was created by the request.
      The value consists of a single absolute URI.

    • id string
    • link string
  • 400 object

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

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 403 object

    Given authorization scopes are not sufficient and do not match required scopes.

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 404

    A coupon with the provided code does not exist.

  • 409 object

    A concurrency operation issue occured.
    The redemption operation needs to be repeated.
    No data has been changed.

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 500 object

    Some server side error occurred.

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

POST /{tenant}/coupons/{code}/redemptions
$ curl \
 -X POST https://api.emporix.io/coupon-v2/{tenant}/coupons/{code}/redemptions \
 -H "Content-Type: application/json" \
 -H "authorization: string" \
 -d '{"customerNumber":"C0123456789","orderCode":"X23RFSU","orderTotal":{"currency":"USD","amount":49.99},"discount":{"currency":"USD","amount":10}}'
Request payload example
# Headers
authorization: string

# Payload
{
  "customerNumber": "C0123456789",
  "orderCode": "X23RFSU",
  "orderTotal": {
    "currency": "USD",
    "amount": 49.99
  },
  "discount": {
    "currency": "USD",
    "amount": 10
  }
}
Response example (201)
# Headers
Location: string

# Payload
{
  "id": "6058912da917ae6f360f2557",
  "link": "https://api.emporix.io/coupon-v2/tenant-name/coupons/ENG20C0/redemptions/6058912da917ae6f360f2557"
}
Response example (400)
{
  "status": 400,
  "message": "There are validation problems, see details section for more information",
  "type": "validation_violation",
  "details": [
    {
      "field": "tenant",
      "message": "must be between 3 and 16 characters",
      "type": "invalid_header"
    }
  ]
}
Response example (403)
{
  "status": 403,
  "message": "Given request does not have required scopes. It is not authorized to perform this operation.",
  "type": "insufficient_permissions"
}
Response example (409)
{
  "status": 409,
  "message": "The requested resource could not be created due to server-side validation.",
  "type": "conflict_resource"
}
Response example (500)
{
  "status": 500,
  "message": "Something went wrong while processing the request. Please contact the administrator.",
  "type": "internal_service_error"
}

Root

Retrieves coupon details

Retrieves coupon details.

No scopes required.

Headers
  • authorization Required / string

    Bearer token

Path parameters
  • tenant Required / string

    The tenant that the caller is acting upon.

    Please note that this value is always lowercase.

Query parameters
  • customerNumber Required / string

    Customer number (ID) of customer on behalf of which we request coupon information.

Responses
  • 200 object

    A coupon has been successfully retrieved.

    • id string
    • code string

      e.g.: WINTER-SALE, 10OFF (read-only)

    • name Required / string

      Localized name

    • description string

      Localized coupon description

    • discountType Required /

      'PERCENT' for relative values or 'ABSOLUTE' for float values, referring to a specific currency.

      Values are PERCENT and ABSOLUTE.

    • discountPercentage number

      A discount percentage within the range [0.00, 100.00]. Required if type is 'PERCENT'.

      Minimum value is 0, maximum value is 100.

    • discountAbsolute object

      Defines an amount in a specific currency

      • amount number

        The total amount in the specified currency.

        Minimum value is 0. Default value is 0.

      • currency string

        ISO 4217 currency code, e.g.: USD, EUR, CHF

        Default value is USD.

    • allowAnonymous boolean

      Can the coupon be redeemed by anonymous user

    • maxRedemptions number

      Maximum number of redemptions; -1 designates 'unlimited' (seller-only)

      Default value is -1.

    • maxRedemptionsPerCustomer number

      Maximum number of redemptions per customer; -1 designates 'unlimited'. Cannot be specified for coupons which can be redeemed by anonymous users.

      Default value is -1.

    • restrictions object
      • validFor array[string]

        A list of customer identifiers, which can redeem the coupon. Cannot be specified for coupons which can be redeemed by anonymous users.

      • validFrom string(date-time)

        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 string(date-time)

        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 object

        Defines an amount in a specific currency

        • amount number

          The total amount in the specified currency.

          Minimum value is 0. Default value is 0.

        • currency string

          ISO 4217 currency code, e.g.: USD, EUR, CHF

          Default value is USD.

    • issuedTo string

      The Id of the customer who originally received the coupon (seller-only).

    • redemptionCount number

      The number of times a specific coupon has been redeemed. Read-only, set through server. (seller-only)

    • status Required /

      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.

      Values are INACTIVE, VALID, EXPIRED, and USED.

    • links array[object]

      Hypermedia reference to coupon actions (read-only, customer-only)

      • rel Required / string

        Link relation type

      • title Required / string

        Link title

      • href Required / string

        Target URI of the link

      • type Required / string

        A content type of the referenced resource

    • deleted boolean

      Flag to mark a coupon as deleted (a.k.a. Soft delete). It is a read-only and seller-only attribute

    • documentFormatVersion number
    • metadata object
      • mixins object
        • Additional properties: string(uri)
      • version number
      • Additional properties are NOT allowed
  • 400 object

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

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 404 object

    The requested resource does not exist.

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 500 object

    Some server side error occurred.

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

GET /{tenant}/coupons/{code}
$ curl \
 -X GET https://api.emporix.io/coupon-v2/{tenant}/coupons/{code}?customerNumber=string \
 -H "authorization: string"
Response example (200)
{
  "code": "ENG2OC?",
  "name": "Winter Sale 2018",
  "description": "Great Winter Discount of 25 USD in December 2018 and January 2019 for all Orders over 50 USD",
  "discountType": "ABSOLUTE",
  "discountAbsolute": {
    "amount": 24.99,
    "currency": "USD"
  },
  "allowAnonymous": false,
  "maxRedemptions": -1,
  "redemptionCount": 30,
  "restrictions": {
    "validFrom": "2018-12-01T00:00:00.000Z",
    "validUntil": "2019-01-31T23:59:59.999Z",
    "minOrderValue": {
      "amount": 49.99,
      "currency": "USD"
    }
  },
  "issuedTo": "C01234567989",
  "status": "VALID",
  "metadata": {
    "version": 1
  }
}
Response example (400)
{
  "status": 400,
  "message": "There are validation problems, see details section for more information",
  "type": "validation_violation",
  "details": [
    {
      "field": "tenant",
      "message": "must be between 3 and 16 characters",
      "type": "invalid_header"
    }
  ]
}
Response example (404)
{
  "status": 404,
  "message": "The requested URI does not map to a single element resource.",
  "type": "element_resource_non_existing"
}
Response example (500)
{
  "status": 500,
  "message": "Something went wrong while processing the request. Please contact the administrator.",
  "type": "internal_service_error"
}

Updates an existing coupon

Updates an existing coupon.

Requires scope coupon.coupon_manage.

Headers
  • authorization Required / string

    Bearer token

Path parameters
  • tenant Required / string

    The tenant that the caller is acting upon.

    Please note that this value is always lowercase.

Query parameters
  • partial Required / boolean

    If true, a partial update will be supported, otherwise the full object replacement will be performed.

    This parameter isDEPRECATED. For partial updates, please usePATCH method instead.

Body
  • id string
  • code string

    e.g.: WINTER-SALE, 10OFF (read-only)

  • name Required / string

    Localized name

  • description string

    Localized coupon description

  • discountType Required /

    'PERCENT' for relative values or 'ABSOLUTE' for float values, referring to a specific currency.

    Values are PERCENT and ABSOLUTE.

  • discountPercentage number

    A discount percentage within the range [0.00, 100.00]. Required if type is 'PERCENT'.

    Minimum value is 0, maximum value is 100.

  • discountAbsolute object

    Defines an amount in a specific currency

    • amount number

      The total amount in the specified currency.

      Minimum value is 0. Default value is 0.

    • currency string

      ISO 4217 currency code, e.g.: USD, EUR, CHF

      Default value is USD.

  • allowAnonymous boolean

    Can the coupon be redeemed by anonymous user

  • maxRedemptions number

    Maximum number of redemptions; -1 designates 'unlimited' (seller-only)

    Default value is -1.

  • maxRedemptionsPerCustomer number

    Maximum number of redemptions per customer; -1 designates 'unlimited'. Cannot be specified for coupons which can be redeemed by anonymous users.

    Default value is -1.

  • restrictions object
    • validFor array[string]

      A list of customer identifiers, which can redeem the coupon. Cannot be specified for coupons which can be redeemed by anonymous users.

    • validFrom string(date-time)

      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 string(date-time)

      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 object

      Defines an amount in a specific currency

      • amount number

        The total amount in the specified currency.

        Minimum value is 0. Default value is 0.

      • currency string

        ISO 4217 currency code, e.g.: USD, EUR, CHF

        Default value is USD.

  • issuedTo string

    The Id of the customer who originally received the coupon (seller-only).

  • redemptionCount number

    The number of times a specific coupon has been redeemed. Read-only, set through server. (seller-only)

  • status Required /

    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.

    Values are INACTIVE, VALID, EXPIRED, and USED.

  • links array[object]

    Hypermedia reference to coupon actions (read-only, customer-only)

    • rel Required / string

      Link relation type

    • title Required / string

      Link title

    • href Required / string

      Target URI of the link

    • type Required / string

      A content type of the referenced resource

  • deleted boolean

    Flag to mark a coupon as deleted (a.k.a. Soft delete). It is a read-only and seller-only attribute

  • documentFormatVersion number
  • metadata object
    • mixins object
      • Additional properties: string(uri)
    • version number
    • Additional properties are NOT allowed
Responses
  • 200

    Coupon updated

  • 400 object

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

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 403 object

    Given authorization scopes are not sufficient and do not match required scopes.

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 404 object

    The requested resource does not exist.

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 409 object

    Creation failed because there was a conflict with another resource. Any details will be provided within the response payload.

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 500 object

    Some server side error occurred.

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

PUT /{tenant}/coupons/{code}
$ curl \
 -X PUT https://api.emporix.io/coupon-v2/{tenant}/coupons/{code}?partial=true \
 -H "Content-Type: application/json" \
 -H "authorization: string" \
 -d '{"code":"ENG2OC?","name":"Winter Sale 2018","description":"Great Winter Discount of 25 USD in December 2018 and January 2019 for all Orders over 50 USD","discountType":"ABSOLUTE","discountAbsolute":{"amount":24.99,"currency":"USD"},"allowAnonymous":false,"maxRedemptions":-1,"maxRedemptionsPerCustomer":-1,"restrictions":{"validFor":["C0123456789","C0123456788"],"validFrom":"2018-12-01T00:00:00.000Z","validUntil":"2019-01-31T23:59:59.999Z","minOrderValue":{"amount":49.99,"currency":"USD"}},"is...}'
Request payload example
# Headers
authorization: string

# Payload
{
  "code": "ENG2OC?",
  "name": "Winter Sale 2018",
  "description": "Great Winter Discount of 25 USD in December 2018 and January 2019 for all Orders over 50 USD",
  "discountType": "ABSOLUTE",
  "discountAbsolute": {
    "amount": 24.99,
    "currency": "USD"
  },
  "allowAnonymous": false,
  "maxRedemptions": -1,
  "maxRedemptionsPerCustomer": -1,
  "restrictions": {
    "validFor": [
      "C0123456789",
      "C0123456788"
    ],
    "validFrom": "2018-12-01T00:00:00.000Z",
    "validUntil": "2019-01-31T23:59:59.999Z",
    "minOrderValue": {
      "amount": 49.99,
      "currency": "USD"
    }
  },
  "issuedTo": "C01234567989"
}
Response example (400)
{
  "status": 400,
  "message": "There are validation problems, see details section for more information",
  "type": "validation_violation",
  "details": [
    {
      "field": "tenant",
      "message": "must be between 3 and 16 characters",
      "type": "invalid_header"
    }
  ]
}
Response example (403)
{
  "status": 403,
  "message": "Given request does not have required scopes. It is not authorized to perform this operation.",
  "type": "insufficient_permissions"
}
Response example (404)
{
  "status": 404,
  "message": "The requested URI does not map to a single element resource.",
  "type": "element_resource_non_existing"
}
Response example (409)
{
  "status": 409,
  "message": "The requested resource could not be updated due to server-side validation.",
  "type": "conflict_resource"
}
Response example (500)
{
  "status": 500,
  "message": "Something went wrong while processing the request. Please contact the administrator.",
  "type": "internal_service_error"
}

Deletes an existing coupon

Deletes an existing coupon.

Requires scope coupon.coupon_manage.

Headers
  • authorization Required / string

    Bearer token

Path parameters
  • tenant Required / string

    The tenant that the caller is acting upon.

    Please note that this value is always lowercase.

Responses
  • 204

    Coupon with given coupon code has been successfully deleted.

  • 400 object

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

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 403 object

    Given authorization scopes are not sufficient and do not match required scopes.

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 404 object

    A coupon with the provided code does not exist.

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 500 object

    Some server side error occurred.

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

DELETE /{tenant}/coupons/{code}
$ curl \
 -X DELETE https://api.emporix.io/coupon-v2/{tenant}/coupons/{code} \
 -H "authorization: string"
Response example (400)
{
  "status": 400,
  "message": "There are validation problems, see details section for more information",
  "type": "validation_violation",
  "details": [
    {
      "field": "tenant",
      "message": "must be between 3 and 16 characters",
      "type": "invalid_header"
    }
  ]
}
Response example (403)
{
  "status": 403,
  "message": "Given request does not have required scopes. It is not authorized to perform this operation.",
  "type": "insufficient_permissions"
}
Response example (404)
{
  "status": 404,
  "message": "The requested URI does not map to a single element resource.",
  "type": "element_resource_non_existing"
}
Response example (500)
{
  "status": 500,
  "message": "Something went wrong while processing the request. Please contact the administrator.",
  "type": "internal_service_error"
}

Updates an existing coupon

Updates an existing coupon.

Requires scope coupon.coupon_manage.

Headers
  • authorization Required / string

    Bearer token

Path parameters
  • tenant Required / string

    The tenant that the caller is acting upon.

    Please note that this value is always lowercase.

Body
  • id string
  • code string

    e.g.: WINTER-SALE, 10OFF (read-only)

  • name Required / string

    Localized name

  • description string

    Localized coupon description

  • discountType Required /

    'PERCENT' for relative values or 'ABSOLUTE' for float values, referring to a specific currency.

    Values are PERCENT and ABSOLUTE.

  • discountPercentage number

    A discount percentage within the range [0.00, 100.00]. Required if type is 'PERCENT'.

    Minimum value is 0, maximum value is 100.

  • discountAbsolute object

    Defines an amount in a specific currency

    • amount number

      The total amount in the specified currency.

      Minimum value is 0. Default value is 0.

    • currency string

      ISO 4217 currency code, e.g.: USD, EUR, CHF

      Default value is USD.

  • allowAnonymous boolean

    Can the coupon be redeemed by anonymous user

  • maxRedemptions number

    Maximum number of redemptions; -1 designates 'unlimited' (seller-only)

    Default value is -1.

  • maxRedemptionsPerCustomer number

    Maximum number of redemptions per customer; -1 designates 'unlimited'. Cannot be specified for coupons which can be redeemed by anonymous users.

    Default value is -1.

  • restrictions object
    • validFor array[string]

      A list of customer identifiers, which can redeem the coupon. Cannot be specified for coupons which can be redeemed by anonymous users.

    • validFrom string(date-time)

      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 string(date-time)

      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 object

      Defines an amount in a specific currency

      • amount number

        The total amount in the specified currency.

        Minimum value is 0. Default value is 0.

      • currency string

        ISO 4217 currency code, e.g.: USD, EUR, CHF

        Default value is USD.

  • issuedTo string

    The Id of the customer who originally received the coupon (seller-only).

  • redemptionCount number

    The number of times a specific coupon has been redeemed. Read-only, set through server. (seller-only)

  • status Required /

    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.

    Values are INACTIVE, VALID, EXPIRED, and USED.

  • links array[object]

    Hypermedia reference to coupon actions (read-only, customer-only)

    • rel Required / string

      Link relation type

    • title Required / string

      Link title

    • href Required / string

      Target URI of the link

    • type Required / string

      A content type of the referenced resource

  • deleted boolean

    Flag to mark a coupon as deleted (a.k.a. Soft delete). It is a read-only and seller-only attribute

  • documentFormatVersion number
  • metadata object
    • mixins object
      • Additional properties: string(uri)
    • version number
    • Additional properties are NOT allowed
Responses
  • 200

    The coupon has been successfully updated.

  • 400 object

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

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 403 object

    Given authorization scopes are not sufficient and do not match required scopes.

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 404 object

    The requested resource does not exist.

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 409 object

    Creation failed because there was a conflict with another resource. Any details will be provided within the response payload.

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 500 object

    Some server side error occurred.

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

PATCH /{tenant}/coupons/{code}
$ curl \
 -X PATCH https://api.emporix.io/coupon-v2/{tenant}/coupons/{code} \
 -H "Content-Type: application/json" \
 -H "authorization: string" \
 -d '{"name":"Winter Sale 2018","discountType":"ABSOLUTE","discountAbsolute":{"amount":24.99,"currency":"USD"},"restrictions":{"validFor":["C0123456789","C0123456788","C9876543210"],"validFrom":"2018-12-01T00:00:00.000Z","validUntil":"2019-01-31T23:59:59.999Z","minOrderValue":{"amount":39.99,"currency":"USD"}},"status":"VALID","metadata":{"version":1}}'
Request payload example
# Headers
authorization: string

# Payload
{
  "name": "Winter Sale 2018",
  "discountType": "ABSOLUTE",
  "discountAbsolute": {
    "amount": 24.99,
    "currency": "USD"
  },
  "restrictions": {
    "validFor": [
      "C0123456789",
      "C0123456788",
      "C9876543210"
    ],
    "validFrom": "2018-12-01T00:00:00.000Z",
    "validUntil": "2019-01-31T23:59:59.999Z",
    "minOrderValue": {
      "amount": 39.99,
      "currency": "USD"
    }
  },
  "status": "VALID",
  "metadata": {
    "version": 1
  }
}
Response example (400)
{
  "status": 400,
  "message": "There are validation problems, see details section for more information",
  "type": "validation_violation",
  "details": [
    {
      "field": "tenant",
      "message": "must be between 3 and 16 characters",
      "type": "invalid_header"
    }
  ]
}
Response example (403)
{
  "status": 403,
  "message": "Given request does not have required scopes. It is not authorized to perform this operation.",
  "type": "insufficient_permissions"
}
Response example (404)
{
  "status": 404,
  "message": "The requested URI does not map to a single element resource.",
  "type": "element_resource_non_existing"
}
Response example (409)
{
  "status": 409,
  "message": "The requested resource could not be updated due to server-side validation.",
  "type": "conflict_resource"
}
Response example (500)
{
  "status": 500,
  "message": "Something went wrong while processing the request. Please contact the administrator.",
  "type": "internal_service_error"
}

Retrieves a single redemption

Retrieves a single redemption.

With scope coupon.coupon_manage it is possible to access any redemption. With scope coupon.coupon_redeem it is
possible to access only redemption created by current user. With scope coupon.coupon_redeem_on_behalf it is possible
to access redemption of behalf of customer, using the customerNumber query parameter.

Headers
  • authorization Required / string

    Bearer token

Path parameters
  • tenant Required / string

    The tenant that the caller is acting upon.

    Please note that this value is always lowercase.

Query parameters
  • customerNumber Required / string

    Customer number (ID) of customer on behalf of which we request redemption details.

Responses
  • 200 object
    • id string
    • code Required / string
    • customerNumber string
    • orderCode string
    • orderTotal Required / object

      Defines an amount in a specific currency

      • amount number

        The total amount in the specified currency.

        Minimum value is 0. Default value is 0.

      • currency string

        ISO 4217 currency code, e.g.: USD, EUR, CHF

        Default value is USD.

    • discount Required / object

      Defines an amount in a specific currency

      • amount number

        The total amount in the specified currency.

        Minimum value is 0. Default value is 0.

      • currency string

        ISO 4217 currency code, e.g.: USD, EUR, CHF

        Default value is USD.

    • redeemedAt Required / string(date-time)
    • documentFormatVersion number
  • 400 object

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

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 403 object

    Given authorization scopes are not sufficient and do not match required scopes.

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 404

    A redemption with the provided code does not exist.

GET /{tenant}/coupons/{code}/redemptions/{id}
$ curl \
 -X GET https://api.emporix.io/coupon-v2/{tenant}/coupons/{code}/redemptions/{id}?customerNumber=string \
 -H "authorization: string"
Response example (200)
{
  "id": "44e5e382414ee7ae27b30b72",
  "code": "WINTER-SALE-2017",
  "customerNumber": "C0123456789",
  "orderCode": "X23RFSU",
  "orderTotal": {
    "currency": "USD",
    "amount": 49.99
  },
  "discount": {
    "currency": "USD",
    "amount": 10
  },
  "redeemedAt": "2017-01-31T23:59:59.999Z"
}
Response example (400)
{
  "status": 400,
  "message": "There are validation problems, see details section for more information",
  "type": "validation_violation",
  "details": [
    {
      "field": "tenant",
      "message": "must be between 3 and 16 characters",
      "type": "invalid_header"
    }
  ]
}
Response example (403)
{
  "status": 403,
  "message": "Given request does not have required scopes. It is not authorized to perform this operation.",
  "type": "insufficient_permissions"
}

Deletes previously created redemption

Deletes previously created redemption.

Requires scope coupon.coupon_manage.

Headers
  • authorization Required / string

    Bearer token

Path parameters
  • tenant Required / string

    The tenant that the caller is acting upon.

    Please note that this value is always lowercase.

Responses
  • 204

    A redemption with the provided code has been successfully deleted.

  • 400 object

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

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 403 object

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

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 404

    A redemption with the provided code does not exist.

DELETE /{tenant}/coupons/{code}/redemptions/{id}
$ curl \
 -X DELETE https://api.emporix.io/coupon-v2/{tenant}/coupons/{code}/redemptions/{id} \
 -H "authorization: string"
Response example (400)
{
  "status": 400,
  "message": "There are validation problems, see details section for more information",
  "type": "validation_violation",
  "details": [
    {
      "field": "tenant",
      "message": "must be between 3 and 16 characters",
      "type": "invalid_header"
    }
  ]
}
Response example (403)
{
  "status": 403,
  "message": "Not allowed to access this resource",
  "type": "insufficient_permissions"
}

Validation

Checks whether the coupon can be successfully redeemed

Checks whether the coupon can be successfully redeemed. Performs all checks which are performed during actual
redemption, but does not result in a redeemed coupon. Only the status of the validation is reported.

See /{tenant}/coupons/{code} endpoint description for information on required scopes.

Additionally, if coupon.coupon_redeem_on_behalf scope is present, the service will use the customer identification
specified in the request body (customerNumber attribute) instead of the one associated with current
authentication token.

Headers
  • authorization Required / string

    Bearer token

Path parameters
  • tenant Required / string

    The tenant that the caller is acting upon.

    Please note that this value is always lowercase.

Body
  • customerNumber string

    The customer Id of the user, e.g. C0123456789. Can be specified only if coupon.coupon_redeem_on_behalf scope is present.

  • orderCode string

    The order Id of the order for which a coupon has been redeemed.

  • orderTotal Required / object

    Defines an amount in a specific currency

    • amount number

      The total amount in the specified currency.

      Minimum value is 0. Default value is 0.

    • currency string

      ISO 4217 currency code, e.g.: USD, EUR, CHF

      Default value is USD.

  • discount Required / object

    Defines an amount in a specific currency

    • amount number

      The total amount in the specified currency.

      Minimum value is 0. Default value is 0.

    • currency string

      ISO 4217 currency code, e.g.: USD, EUR, CHF

      Default value is USD.

Responses
  • 200

    A coupon can be successfully redeemed.

  • 400 object

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

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 403 object

    Given authorization scopes are not sufficient and do not match required scopes.

    • status Required / integer

      original HTTP error code, should be consistent with the response HTTP code

      Minimum value is 100, maximum value is 599.

    • type Required / string

      classification of the error type, lower case with underscore eg validation_failure

    • message string

      descriptive error message for debugging

    • moreInfo string(uri)

      link to documentation to investigate further and finding support

    • details array[object]

      list of problems causing this error

      • field string

        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 Required / string

        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.

      • message string

        descriptive error detail message for debugging

      • moreInfo string(uri)

        link to documentation to investigate further and finding support for error detail

  • 404

    A coupon with the provided code does not exist.

POST /{tenant}/coupons/{code}/validation
$ curl \
 -X POST https://api.emporix.io/coupon-v2/{tenant}/coupons/{code}/validation \
 -H "Content-Type: application/json" \
 -H "authorization: string" \
 -d '{"orderCode":"X23RFSU","orderTotal":{"currency":"USD","amount":49.99},"discount":{"currency":"USD","amount":10}}'
Request payload example
# Headers
authorization: string

# Payload
{
  "orderCode": "X23RFSU",
  "orderTotal": {
    "currency": "USD",
    "amount": 49.99
  },
  "discount": {
    "currency": "USD",
    "amount": 10
  }
}
Response example (400)
{
  "status": 400,
  "message": "There are validation problems, see details section for more information",
  "type": "validation_violation",
  "details": [
    {
      "field": "tenant",
      "message": "must be between 3 and 16 characters",
      "type": "invalid_header"
    }
  ]
}
Response example (403)
{
  "status": 403,
  "message": "Given request does not have required scopes. It is not authorized to perform this operation.",
  "type": "insufficient_permissions"
}