Storefront API Vouchers

The Storefront API Vouchers allows voucher codes to be redeemed and removed in the storefront. The API automatically checks whether a code is valid and, after redemption, returns the updated shopping cart values (e.g. discounts and totals) as well as notices/error messages if needed.

Supported methods

List of all supported methods.

Command	Endpoints	GET	PUT	POST	DELETE
Read voucher data	`voucher/get`
Redeem voucher	`voucher/redeem`
Delete voucher	`voucher/delete`

Error format

All errors are answered with HTTP 400 and the following body:

{
  "error": "actionFailed",
  "detail": "Action Failed",
  "actionErrors": [
    { "code": "invalidVoucherId", "subCode": "", "field": "id", "text": "…", "details": {} }
  ]
}

error = invalidParameters for errors in parameters/field types (details in paramErrors, key = parameter name, value {"type": "missing" | "invalidFormat" | "invalidValue" | "unknownField" | …}).
error = actionFailed for functional errors. The error codes listed in the following tables then appear in actionErrors[].code.
A call with a wrong HTTP method is answered with HTTP 404 (not 405).
If the session (x-session) is missing, the response is HTTP 400.

Methods for vouchers

These methods allow you to check, redeem, and remove vouchers directly in the shopping cart or checkout.

GET voucher/get

This call reads master data for a voucher code (e.g. value, currency, minimum order value). This information can be used in the shopping cart and checkout to check a voucher before redeeming it and to display info such as amount and conditions. Example call for the voucher with the voucher number 7G3M-L2UU-CK1B-A2J2:

GET https://<your-shop>.de/api/v1/voucher/get?id=7G3M-L2UU-CK1B-A2J2

Parameter overview

Query parameters

Parameter	Type	Description
`id`	String	Required field Voucher code to be queried.

Example response

{
  "currency": "EUR",
  "id": "7G3M-L2UU-CK1B-A2J2",
  "minOrderValue": 0,
  "taxId": "19",
  "value": 10.5
}

Field	Type	Description
`id`	string	Voucher code.
`value`	float	Currently effective value (absolute value plus calculated percentage share, capped by `maxDiscountValue`). If the minimum order value is not reached, the value is 0.
`currency`	string	Currency of the voucher.
`taxId`	string	Tax key of the voucher.
`usedValue`	float	Already spent value. Only present if set.
`minOrderValue`	float	Minimum order value. Only present if set.
`maxDiscountValue`	float	Maximum discount amount for percentage vouchers. Only present if set.
`validFrom` / `validUntil`	string (ISO 8601)	Validity period. Only present if set.

POST voucher/redeem

This call redeems a voucher code for the current shopping cart and returns information about the redeemed voucher and the remaining value. This command can be used in the shopping cart or checkout to offset the voucher or to display the redeemed amount and, if applicable, the remaining value. Example call for redeeming the voucher 7G3M-L2UU-CK1B-A2J2:

POST https://<your-shop>.de/api/v1/voucher/redeem

Example request

{
  "id": "7G3M-L2UU-CK1B-A2J2"
}

Parameter overview

Header parameters

Parameter	Description
`x-session`	Required field ID of the current session. More information: Storefront API Basics

Body parameters

Parameter	Type	Description
`id`	string	Required field Voucher code to be redeemed.

Example response

{
  "info": {
    "totalUsedValue": 0,
    "totalValue": 10.5,
    "vouchers": [
      {
        "currency": "EUR",
        "id": "7G3M-L2UU-CK1B-A2J2",
        "taxId": "19",
        "usedValue": 0,
        "value": 10.5
      }
    ]
  }
}

Ineffective vouchers voucher/redeem only checks the validity of the code, not its effect on the current shopping cart. A voucher can be redeemed without error and still result in a 0.00 discount. Therefore, after redeeming, check ineffectiveVoucherErrors and isOrderBlockedByIneffectiveVoucher from the checkout data.

Code	Meaning
`noValidProducts`	The shopping cart contains no product for which the voucher is valid.
`minOrderValueNotReached`	The minimum order value of the voucher is not reached.

Each entry has the fields code, subCode (always empty), field (always empty), text (translated message text), and details.voucherId (missing if the error refers to the sum of several vouchers). If isOrderBlockedByIneffectiveVoucher = true, the shop rejects the order confirmation with the error code voucherIneffective.

Error codes

Error code	Description
`invalidVoucherId`	The specified ID is not a valid voucher code.
`deactivated`	The voucher has been deactivated.
`expired`	The voucher has expired.
`notYetValid`	The voucher is not yet valid.
`maxCountExceeded`	The maximum number of vouchers per order has been reached. The upper limit is configured per shop. The default value is 1. The currently valid value is in the `maximumCount` field of the voucher overview.
`valueSpent`	The total value of the voucher has already been spent.
`currencyMismatch`	The voucher currency does not match the shop currency.
`invalidCustomer`	The voucher may not be redeemed by this customer.
`invalidSubshop`	The voucher may not be redeemed in this subshop.
`missingId`	No voucher code was passed.
`duplicateId`	This voucher code is already redeemed in the shopping cart.
`expressCheckoutNotAllowed`	An express checkout is active - vouchers may not be changed at the moment.
`insuffientAmount`	The available voucher value is not sufficient. (Spelling as in the code, with the missing “ic”.)
`repoUpdateFailed`	The voucher could not be updated for technical reasons.
`invalidVoucherConfiguration`	The voucher is misconfigured (no type stored).

DELETE voucher/delete

This call removes a redeemed voucher code from the current shopping cart and updates the voucher overview. This command can be used in the shopping cart or checkout to undo an accidentally redeemed or unwanted voucher application. Example call for removing the voucher with the code 7G3M-L2UU-CK1B-A2J2:

DELETE https://<your-shop>.de/api/v1/voucher/delete

Example request

{
  "id": "7G3M-L2UU-CK1B-A2J2"
}

Parameter overview

Header parameters

Parameter	Description
`x-session`	Required field ID of the current session. More information: Storefront API Basics

Body parameters

Parameter	Type	Description
`id`	String	Required field Voucher code to be removed.

Example response

{
  "info": {
    "totalUsedValue": 0,
    "totalValue": 0,
    "vouchers": []
  }
}

Error codes

Error code	Description
`invalidVoucherId`	The specified ID is not a valid voucher code.
`expressCheckoutNotAllowed`	An express checkout is active - the voucher may not be removed at the moment.

Interfaces

Admin Interface API

Storefront API

More

Supported methods

Error format

Methods for vouchers

GET voucher/get

Parameter overview

Query parameters

Example response

POST voucher/redeem

Example request

Parameter overview

Header parameters

Body parameters

Example response

Error codes

DELETE voucher/delete

Example request

Parameter overview

Header parameters

Body parameters

Example response

Error codes

​Supported methods

​Error format

​Methods for vouchers

​GET voucher/get

​Parameter overview

​Query parameters

​Example response

​POST voucher/redeem

​Example request

​Parameter overview

​Header parameters

​Body parameters

​Example response

​Error codes

​DELETE voucher/delete

​Example request

​Parameter overview

​Header parameters

​Body parameters

​Example response

​Error codes

Supported methods

Error format

Methods for vouchers

GET voucher/get

Parameter overview

Query parameters

Example response

POST voucher/redeem

Example request

Parameter overview

Header parameters

Body parameters

Example response

Error codes

DELETE voucher/delete

Example request

Parameter overview

Header parameters

Body parameters

Example response

Error codes