POST /vouchers/group
Requires authentication with server access token.
Create a new voucher group. A voucher group is a template from which vouchers can be generated, it describes what kind of access its vouchers grant.
Once a voucher group is created, you must generate individual vouchers to hand out.
In order to use this endpoint, your client must have a voucher_prefix
. This field is set by Schibsted account administrators, if it is not set, you will get an error like "Set generator used, but no client voucher prefix set". If this happens, contact support.
See also
- The Voucher group object
POST
/voucher_handoutGET
/voucher/{voucherCode}POST
/vouchers/generate/{voucherGroupId}GET
/vouchers/group/{voucherGroupId}POST
/vouchers/group/{voucherGroupId}GET
/vouchers/groupsPOST
/vouchers/handout/{voucherGroupId}
Help us improve
Did you spot an error? Or maybe you just have a suggestion for how we can improve? Leave us a comment.
Request
POST /api/2/vouchers/group
title | requiredThe voucher group's title |
---|---|
type | required |
campaignId | optionalID of the campaign vouchers will be used with |
productId | optionalIf creating a giveaway voucher group, this is the ID of the product vouchers will grant access to |
description | optionalA textual description of the vouchers |
unique | optionalIf 1, each user receives a unique voucher code that can only redeemed once. If 0, a shared voucher will be issued, and the |
limit | optionalThe maximum number of times the voucher can be redeemed, if it is a shared voucher |
voucherCode | optionalA unique string |
Example request
curl
Minimal example
curl https://login.schibsted.com/api/2/vouchers/group \
-X POST \
-H "Authorization: Bearer [access token]" \
-d "title=Freebies for all" \
-d "type=discount"
With all parameters
curl https://login.schibsted.com/api/2/vouchers/group \
-X POST \
-H "Authorization: Bearer [access token]" \
-d "title=Freebies for all" \
-d "type=discount" \
-d "campaignId=23494" \
-d "productId=1337" \
-d "description=Some information" \
-d "unique=1" \
-d "limit=10" \
-d "voucherCode=My voucher"
Response
This endpoint supports the JSON and JSON-P response formats.
Success: 200 OK
Returns the newly created voucher group object
Voucher group
Voucher groups are templates from which vouchers can be generated. Individual vouchers are not complete on their own - you need a voucher's group to fully identify its functionality. Voucher groups may have several limitations, like how many vouchers can be generated (for unique one-off vouchers), or how many times a shared voucher (same code used many times) may be used.
Two vouchers are supported: Giveaway and Campaign. Giveaway voucher groups are connected to a product and redeeming a voucher from this group will create a subscription or grant digital content access. The campaign version is used in connection to Campaigns that require vouchers to be activated in the purchase flow.
voucherGroupId ✓ | integer (as string)Unique ID of the voucher group |
---|---|
clientId ✓ | stringID of the client that owns the voucher group and its vouchers |
discountId ✓ | integer (as string)ID of discount to apply |
campaignId ✓ | integer (as string)Unique ID, used by 'campaign' voucher groups |
productId ✓ | integer (as string)Used by 'campaign' voucher groups |
type ✓ | Voucher typeThe type of the voucher group and all its vouchers |
unique ✓ | booleanIf |
limit ✓ | integer (as string)The maximum number of vouchers that may be generated, or the number of times a shared voucer may be used. 0 means no limit |
title ✓ | stringA descriptive name of the voucher, suitable for presentation to end-users |
description ✓ | stringA description of the intention of the voucher group |
createdBy ✓ | integer (as string)The |
updated ✓ | datetimeWhen the voucher group was last modified |
created ✓ | dateimeWhen the voucher group was created |
The check mark ✓ indicates that the field always contains a valid non-empty value.
Voucher
Vouchers are mainly described by the voucher group they belong to. Shared vouchers can be redeemed multiple times and as such never changes its status to redeemed. Unique vouchers have unique codes for each user and can only be redeemed once.
voucherId ✓ | integer (as string)Unique ID of the voucher. Endpoints only ever use the |
---|---|
voucherGroupId ✓ | integer (as string)ID of the voucher group the voucher belongs to |
userId ✓ | integer (as string)
|
type ✓ | Voucher typeVoucher group type |
count | integer (as string)Number of time the voucher has been redeemed. Only available for shared vouchers. |
voucherCode ✓ | stringA unique string that gives access to this voucher |
status ✓ | Voucher status |
handoutBy ✓ | integer (as string)
|
createdBy ✓ | integer (as string)
|
updated ✓ | datetimeWhen the voucher was last updated (i.e. had its status changed) |
created ✓ | datetimeWhen the voucher was created |
The check mark ✓ indicates that the field always contains a valid non-empty value.
Voucher type
An enum, with the following possible values:
| Campaign, redeems as a campaign purchase |
---|---|
| Voucher as payment method |
| Giveaway, when redeemed, the user is given the product directly, without creating an order (thus, no there will be no receipt generated from the system). For testing purposes only, not available in production. |
| Free with order, redeemer is given product and order is created for 0 value. Replaced by |
Voucher status
An enum, with the following possible values:
| Voucher is expired and can no longer be redeemed |
---|---|
| Voucher is generated and may be either used or handed out |
| Voucher is handed out. If the userId field is set, only this user may redeem it |
| Voucher is redeemed and can no longer be used. Kept only for historic reasons |
Failure cases
Some HTTP response codes are used for multiple error situations. There is no consistent way to tell these apart, but the error object will contain a textual explanation of the reason for the error. For explanation on OAuth related failures and errors see OAuth authentication failures.
- 401 Unauthorized You don't have administration rights for this client.
- 401 Unauthorized Your client doesn't have administration rights for this client.
- 403 Forbidden Client is not authorized to access this API endpoint. Contact Schibsted account to request access.
- 403 Forbidden Requesting IP is not whitelisted
- 403 Forbidden Access token rejected
- 404 Not Found Unknown client ID
- 404 Not Found Client ID mismatch. The client making the request is no the owner of this resource, and does not have administrative privileges for it.
- 420 Request Ratelimit exceeded
Sample response
JSON
{
"clientId": "[Your client ID]",
"createdBy": "[ID of admin user, or client]",
"discountId": null,
"title": "Freebies for all",
"voucherGroupId": "47",
"productId": null,
"created": "2014-08-06 11:47:25",
"unique": "1",
"updated": "2014-08-06 11:47:25",
"limit": null,
"type": "8",
"campaignId": null,
"description": null
}
JSON-P
callback({
"clientId": "[Your client ID]",
"createdBy": "[ID of admin user, or client]",
"discountId": null,
"title": "Freebies for all",
"voucherGroupId": "47",
"productId": null,
"created": "2014-08-06 11:47:25",
"unique": "1",
"updated": "2014-08-06 11:47:25",
"limit": null,
"type": "8",
"campaignId": null,
"description": null
});
Comments/feedback
Do you have questions, or just want to contribute some newly gained insight? Want to share an example? Please leave a comment. Our team reads and responds to every question. Additionally, your experience can help others using Schibsted account, and it can help us continuously improve our documentation.