Reward Points Service

Download OpenAPI specification:Download

E-mail: documentation@emporix.com

Collect reward points and exchange them for coupons.

KeyFeatures:

Grant points to customers after they complete an order, or reward chosen customers irrespective of the orders made
Define the exchange rate between points and currency when collecting points
Points account balance per customer
Redeem points in exchange for coupon codes

Key Benefits:

Increase customer loyalty
Reward customers for their spending
Increase customer spending

Redeem Options Management

Creating redemption options

Sets up a reward points redemption option that contains instructions for transforming these points into a coupon. Customers are required to choose this option to convert the reward points and create a coupon based on the pre-established rules.

Note: Only employees have the authority to configure the redemption options.

Required scopes

rewardspoints.rewardpoints_manage

SecurityCustomerAccessToken

Request

path Parameters

tenant

required

string

Tenant name.

Request Body schema: application/json

id	string ID of the redemption option to be used at reward points exchange
type required	string Option type, typically 'coupon'.
name required	string Name of the redeem option that can be presented to customer
description	string Description of the redeem option that can be presented to customer
points required	integer Points to deduct from customer's account at coupon creation
	object (Coupon API) Coupons describe voucher-like commerce capabilities.
pointsAfterCoupon	integer
	object

Responses

200

400

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

401

403

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

500

Internal error

post/{tenant}/redeemOptions

Request samples

application/json

{"type": "coupon",
"name": "10 Euro Gutschein",
"description": "Für 90 Punkte können Sie sich einen Gutschein über 10 Euro generieren lassen. Diesen Gutschein können Sie auch an Freunde und Bekannte weitergeben.",
"points": 90,
"coupon": {"name": "Gutschein über 10 Euro (eingelöste Bonuspunkte)",
"description": "Gutschein über 10 Euro aus 1000 Bonuspunkte",
"discountType": "ABSOLUTE",
"discountAbsolute": {"amount": 10,
"currency": "EUR"
},
"allowAnonymous": true,
"maxRedemptions": 1,
"status": "VALID"
}
}

Response samples

200
400
401
403
500

application/json

[{"points": 30,
"type": "coupon",
"name": "persönlicher 20 Euro Gutschein",
"description": "Ein persönlicher Gutschein zum einlösen auf Lieferladen.de (nur gültig im Lieferladen.de Stuttgart Shop)"
}
]

Retrieving redemption options

Retrieves all available reward points redemption options configured for customers to use.

Note: This public API endpoint is accessible to all customers.

SecurityOAuth2

Request

path Parameters

tenant

required

string

Tenant name.

Responses

200

Returns all configured reward points redemption options

401

403

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

500

Internal error

get/{tenant}/redeemOptions

Request samples

Response samples

200
401
403
500

application/json

[{"id": "5f905280df6b3b0013b6c541",
"type": "coupon",
"name": "10 Euro Gutschein",
"description": "Für 90 Punkte können Sie sich einen Gutschein über 10 Euro generieren lassen. Diesen Gutschein können Sie auch an Freunde und Bekannte weitergeben.",
"points": 90,
"coupon": {"name": "Gutschein über 10 Euro (eingelöste Bonuspunkte)",
"description": "Gutschein über 10 Euro aus 1000 Bonuspunkte",
"discountType": "ABSOLUTE",
"discountAbsolute": {"amount": 10,
"currency": "EUR"
},
"allowAnonymous": true,
"maxRedemptions": 1,
"status": "VALID"
},
"metadata": {"version": 1,
"createdAt": "2023-07-25T13:28:25.960Z",
"modifiedAt": "2023-07-25T13:28:25.960Z"
}
}
]

Deleting redemption options

Deletes a reward points redemption option for a given tenant.

Note: Only employees have the authority to delete the redemption options.

Required scopes

rewardspoints.rewardpoints_manage

SecurityCustomerAccessToken

Request

path Parameters

redeemOptionId required	string Unique identifier of a redeem option.
tenant required	string Tenant name.

Responses

204

Deletes given redeem option by id

401

403

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

500

Internal error

delete/{tenant}/redeemOptions/{redeemOptionId}

Request samples

Response samples

401
403
500

application/json

{"fault": {"faultstring": "Invalid access token",
"detail": {"errorcode": "oauth.v2.InvalidAccessToken"
}
}
}

Updating redemption options

Updates a reward points redemption option for a given tenant.

Note: Only employees have the authority to update the redemption options.

Required scopes

rewardspoints.rewardpoints_manage

SecurityCustomerAccessToken

Request

path Parameters

redeemOptionId required	string Unique identifier of a redeem option.
tenant required	string Tenant name.

Request Body schema: application/json

id	string ID of the redemption option to be used at reward points exchange
type required	string Option type, typically 'coupon'.
name required	string Name of the redeem option that can be presented to customer
description	string Description of the redeem option that can be presented to customer
points required	integer Points to deduct from customer's account at coupon creation
	object (Coupon API) Coupons describe voucher-like commerce capabilities.
pointsAfterCoupon	integer
	object

Responses

200

Updates given redeem option by id

400

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

401

403

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

409

The resource requested for update has changed.

500

Internal error

put/{tenant}/redeemOptions/{redeemOptionId}

Request samples

application/json

{"type": "coupon",
"name": "10 Euro Gutschein",
"description": "Für 90 Punkte können Sie sich einen Gutschein über 10 Euro generieren lassen. Diesen Gutschein können Sie auch an Freunde und Bekannte weitergeben.",
"points": 90,
"coupon": {"name": "Gutschein über 10 Euro (eingelöste Bonuspunkte)",
"description": "Gutschein über 10 Euro aus 1000 Bonuspunkte",
"discountType": "ABSOLUTE",
"discountAbsolute": {"amount": 10,
"currency": "EUR"
},
"allowAnonymous": true,
"maxRedemptions": 1,
"status": "VALID"
},
"metadata": {"version": 1
}
}

Response samples

400
401
403
409
500

application/json

{"type": "about:blank",
"title": "Bad Request",
"status": 400,
"detail": "Invalid request content.",
"instance": "/customer/61443563/addPoints"
}

Reward Points Management

Retrieving reward points of all customers

Retrieves a detailed summary of added and redeemed reward points for all customers of a given tenant. The tenant name is selected based on the access token.

Note: Only employees are authorized to perform this action.

Required scopes

rewardspoints.rewardpoints_view

SecurityOAuth2

Responses

200

401

403

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

500

Internal error

get/summaryBatch

Request samples

Response samples

200
401
403
500

application/json

[{"customerId": "20242913",
"activePoints": 2000,
"summary": {"addedPointsList": [{"id": "1c32ce73-8765-42a7-92af-ff370a0a59d6",
"reference-id": "<string>",
"description": "<string>",
"points": 2000,
"createdAt": "2023-05-11T18:32:18.591+00:00",
"allPointsAfterCreation": 2000,
"usedPoints": 140,
"validUntil": "2023-11-11T12:00:50.406+00:00",
"usedWith": ["d85c0570-1d51-4611-bf2f-c67452384626",
"b5085a36-a5f0-450d-a011-9f92902f3900"
]
},
{"id": "b9919f33-3a0b-4fd7-acdb-217edd4fc110",
"reference-id": null,
"description": "Chargeback - redeemed voucher could not be created.",
"points": 50,
"createdAt": "2023-05-11T18:32:38.564+00:00",
"allPointsAfterCreation": 2000,
"usedPoints": 0,
"validUntil": "2026-05-11T18:32:38.564+00:00",
"usedWith": [ ]
},
{"id": "42cd0799-9965-4983-8548-e7ad79160572",
"reference-id": null,
"description": "Chargeback - redeemed voucher could not be created.",
"points": 90,
"createdAt": "2023-05-11T18:32:50.981+00:00",
"allPointsAfterCreation": 2000,
"usedPoints": 0,
"validUntil": "2026-05-11T18:32:50.981+00:00",
"usedWith": [ ]
}
],
"redeemedPointsList": [{"id": "d85c0570-1d51-4611-bf2f-c67452384626",
"description": "test desc",
"points": 50,
"createdAt": "2023-05-11T18:32:38.501+00:00",
"allPointsAfterCreation": 1950
},
{"id": "b5085a36-a5f0-450d-a011-9f92902f3900",
"description": "For 90 points you can have a voucher for 10 euros generated. You can also pass this voucher on to friends and acquaintances.",
"points": 90,
"createdAt": "2023-05-11T18:32:50.946+00:00",
"allPointsAfterCreation": 1910
}
]
}
}
]

Retrieving reward points of a customer

Fetches the number of reward points for a particular customer of a given tenant. The tenant name is retrieved from the access token.

Note: Only employees are authorized to perform this action.

Required scopes

rewardspoints.rewardpoints_view

SecurityOAuth2

Request

path Parameters

customerId

required

string

Unique identifier of a customer, generated when the customer is created through the Customer Service.

Responses

200

400

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

403

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

500

Internal error

get/customer/{customerId}

Request samples

Response samples

200
400
403
500

application/json

2000

Creating a new reward points entry for a customer

Creates a new reward points entry for a particular customer of a given tenant. The tenant name is retrieved from the access token.

Required scopes

rewardspoints.rewardpoints_manage

SecurityOAuth2

Request

path Parameters

customerId

required

string

Unique identifier of a customer, generated when the customer is created through the Customer Service.

query Parameters

siteCode

string

Default: "main"

Site code, defined when a site is created.

Request Body schema: application/json

customerId	string
	object (addedPoints)

Responses

200

400

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

401

403

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

409

500

Internal error

post/customer/{customerId}

Request samples

application/json

{"customerId": "C4289081720",
"startPoints": {"id": "12345fee-0b83-48aa-95dc-11e3dcf84aaa",
"reference-id": "123456",
"description": "points added",
"points": 20,
"createdAt": "2019-08-24T14:15:22Z",
"allPointsAfterCreation": 20,
"usedPoints": 5,
"validUntil": "2019-08-24T14:15:22Z",
"usedWith": ["5237bcac-c548-4e49-8626-03dab65376d6"
]
}
}

Response samples

400
401
403
409
500

application/json

{"type": "about:blank",
"title": "Bad Request",
"status": 400,
"detail": "Invalid request content.",
"instance": "/customer/61443563/addPoints"
}

Deleting reward points of a customer

Deletes a reward points entry of a specified customer for a given tenant. The tenant name is retrieved from the access token.

Required scopes

rewardspoints.rewardpoints_manage

SecurityOAuth2

Request

path Parameters

customerId

required

string

Unique identifier of a customer, generated when the customer is created through the Customer Service.

Responses

200

401

403

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

500

Internal error

delete/customer/{customerId}

Request samples

Response samples

401
403
500

application/json

{"fault": {"faultstring": "Invalid access token",
"detail": {"errorcode": "oauth.v2.InvalidAccessToken"
}
}
}

Retrieving a reward points summary for a single customer

Retrieves a detailed summary of added and redeemed reward points of a single specified customer for a given tenant. The tenant name is retrieved from the access token.

Note: Only employees are authorized to perform this action.

Required scopes

rewardspoints.rewardpoints_view

SecurityOAuth2

Request

path Parameters

customerId

required

string

Unique identifier of a customer, generated when the customer is created through the Customer Service.

Responses

200

401

403

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

404

Entity not found.

500

Internal error

get/customer/{customerId}/summary

Request samples

Response samples

200
401
403
404
500

application/json

{"customerId": "123",
"activePoints": 1153,
"summary": {"addedPointsList": [{"id": "zzpscd12uimlmybtthb",
"reference-id": "B7011746",
"description": "Bonuspunkte für Bestellung B7011746",
"points": 209,
"createdAt": "2020-09-03T09:45:02.248+00:00",
"allPointsAfterCreation": 209,
"usedPoints": 209,
"validUntil": "2023-09-02T22:00:00.000+00:00",
"usedWith": ["e7522b99-2448-44b5-8f68-8bffcc207d18"
]
},
{"id": "c9joe623gl4obochkrmy8i",
"reference-id": "B7011745",
"description": "Bonuspunkte für Bestellung B7011745",
"points": 209,
"createdAt": "2020-09-03T09:45:02.318+00:00",
"allPointsAfterCreation": 418,
"usedPoints": 209,
"validUntil": "2023-09-02T22:00:00.000+00:00",
"usedWith": ["e7522b99-2448-44b5-8f68-8bffcc207d18"
]
}
],
"redeemedPointsList": [{"id": "e7522b99-2448-44b5-8f68-8bffcc207d18",
"description": "Für 600 Punkte können Sie sich einen Gutschein über 5 Euro generieren lassen. Diesen Gutschein können Sie auch an Freunde und Bekannte weitergeben.",
"points": 600,
"createdAt": "2020-09-03T12:44:22.747+00:00",
"allPointsAfterCreation": 2953
}
]
}
}

Adding reward points for a customer

Adds reward points to a specific customer's account for a given tenant. The tenant name is retrieved from the access token.

Note: Only employees are authorized to perform this action.

Required scopes

rewardspoints.rewardpoints_manage

SecurityOAuth2

Request

path Parameters

customerId

required

string

Unique identifier of a customer, generated when the customer is created through the Customer Service.

query Parameters

siteCode

string

Default: "main"

Site code, defined when a site is created.

Request Body schema: application/json

id	string
reference-id	string or null Order Id for which the points were created
description	string Auto-generated description
points required	integer Number of points added in the operation
createdAt	string <date-time>
validUntil	string <date-time> The date until when the points can be redeemed
allPointsAfterCreation	integer Number of points after creation
usedPoints	integer Number of points already used
usedWith	Array of strings

Responses

201

400

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

401

403

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

500

Internal error

post/customer/{customerId}/addPoints

Request samples

application/json

{"id": "12345fee-0b83-48aa-95dc-11e3dcf84aaa",
"reference-id": "123456",
"description": "points added",
"points": 123,
"createdAt": "2023-10-24T14:15:22Z",
"allPointsAfterCreation": 56778,
"usedPoints": 5,
"validUntil": "2029-08-24T14:15:22Z",
"usedWith": ["5237bcac-c548-4e49-8626-03dab65376d6"
]
}

Response samples

400
401
403
500

application/json

{"type": "about:blank",
"title": "Bad Request",
"status": 400,
"detail": "Invalid request content.",
"instance": "/customer/61443563/addPoints"
}

Redeeming reward points of a customer

Redeems reward points for a specified customer for a given tenant without generating a coupon. The tenant name is retrieved from the access token.

Note: Only employees are authorized to perform this action.

Required scopes

rewardspoints.rewardpoints_manage

SecurityOAuth2

Request

path Parameters

customerId

required

string

Unique identifier of a customer

Request Body schema: application/json

id	string Identifier of the redeemed points
description	string A comment for the redeem operation
points required	integer The amount of the redeemed points
createdAt	string <date-time> Timestamp when the points were redeemed
allPointsAfterCreation	integer Number of points after creation

Responses

201

400

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

401

403

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

500

Internal error

post/customer/{customerId}/redeemPoints

Request samples

application/json

{"description": "points redeemed",
"points": 50
}

Response samples

400
401
403
500

application/json

{"type": "about:blank",
"title": "Bad Request",
"status": 400,
"detail": "Invalid request content.",
"instance": "/customer/61443563/addPoints"
}

Signed-In Customer Reward Points

Retrieving reward points of a signed-in customer

Fetches the number of reward points of a currently signed-in customer.

Note: This public API endpoint is accessible to all customers.

SecurityCustomerAccessToken

Responses

200

401

403

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

500

Internal error

get/public/customer

Request samples

Response samples

200
401
403
500

application/json

1153

Retrieving a reward points summary of a signed-in customer

Retrieves a detailed summary of added and redeemed reward points of a signed-in customer.

Note: This public API endpoint is accessible to all customers.

SecurityCustomerAccessToken

Responses

200

401

403

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

500

Internal error

get/public/customer/summary

Request samples

Response samples

200
401
403
500

application/json

{"customerId": "123",
"activePoints": 1153,
"summary": {"addedPointsList": [{"id": "zzpscd12uimlmybtthb",
"reference-id": "B7011746",
"description": "Bonuspunkte für Bestellung B7011746",
"points": 209,
"createdAt": "2020-09-03T09:45:02.248+00:00",
"allPointsAfterCreation": 209,
"usedPoints": 209,
"validUntil": "2023-09-02T22:00:00.000+00:00",
"usedWith": ["e7522b99-2448-44b5-8f68-8bffcc207d18"
]
},
{"id": "c9joe623gl4obochkrmy8i",
"reference-id": "B7011745",
"description": "Bonuspunkte für Bestellung B7011745",
"points": 209,
"createdAt": "2020-09-03T09:45:02.318+00:00",
"allPointsAfterCreation": 418,
"usedPoints": 209,
"validUntil": "2023-09-02T22:00:00.000+00:00",
"usedWith": ["e7522b99-2448-44b5-8f68-8bffcc207d18"
]
}
],
"redeemedPointsList": [{"id": "e7522b99-2448-44b5-8f68-8bffcc207d18",
"description": "Für 600 Punkte können Sie sich einen Gutschein über 5 Euro generieren lassen. Diesen Gutschein können Sie auch an Freunde und Bekannte weitergeben.",
"points": 600,
"createdAt": "2020-09-03T12:44:22.747+00:00",
"allPointsAfterCreation": 2953
}
]
}
}

Redeeming a logged-in customer's reward points for a coupon code

Gets the logged-in customer's reward points, swaps them for a coupon code by using the given redemption option ID, and returns a coupon code.

Note: This public API endpoint is accessible to all customers and is meant to be used on the storefront.

SecurityCustomerAccessToken

Request

query Parameters

siteCode

string

Default: "main"

Site code, defined when a site is created.

Request Body schema: application/json

id

required

string

The ID of the redeem option used to convert points into a coupon.

Responses

200

400

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

403

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

404

Entity not found.

500

Internal error

post/public/customer/redeem

Request samples

application/json

{"id": "575937654bf757001d8496c9"
}

Response samples

200
400
403
404
500

application/json

{"code": "LLS-232394"
}