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`

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

Body 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
}

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
      }
    ]
  }
}

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 redeemable vouchers per order has been reached.
`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.

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.

Interfaces

Admin Interface API

Storefront API

More

Supported methods

Methods for vouchers

GET voucher/get

Parameter overview

Body 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

​Methods for vouchers

​GET voucher/get

​Parameter overview

​Body 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

Methods for vouchers

GET voucher/get

Parameter overview

Body 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