Payment Services

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

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

required

The voucher group's title

type

required

Voucher type

campaignId

optional

ID of the campaign vouchers will be used with

productId

optional

If creating a giveaway voucher group, this is the ID of the product vouchers will grant access to

description

optional

A textual description of the vouchers

unique

optional

If 1, each user receives a unique voucher code that can only redeemed once. If 0, a shared voucher will be issued, and the limit can be used to control the number of times it can be redeemed.

limit

optional

The maximum number of times the voucher can be redeemed, if it is a shared voucher

voucherCode

optional

A 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 ✓

string

ID 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 type

The type of the voucher group and all its vouchers

unique ✓

boolean

If true, the voucher group will generate unique vouchers that may only be used once. If false, the voucher group will have exactly one voucher that is shared

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 ✓

string

A descriptive name of the voucher, suitable for presentation to end-users

description ✓

string

A description of the intention of the voucher group

createdBy ✓

integer (as string)

The userId of the user that created the voucher group

updated ✓

datetime

When the voucher group was last modified

created ✓

dateime

When 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 voucherCode to access vouchers

voucherGroupId ✓

integer (as string)

ID of the voucher group the voucher belongs to

userId ✓

integer (as string)

userId of the user that redeemed the voucher or that the voucher is handed out to

type ✓

Voucher type

Voucher group type

count

integer (as string)

Number of time the voucher has been redeemed. Only available for shared vouchers.

voucherCode ✓

string

A unique string that gives access to this voucher

status ✓

Voucher status

handoutBy ✓

integer (as string)

userId of the user that handed out the voucher

createdBy ✓

integer (as string)

userId of the user that generated the voucher

updated ✓

datetime

When the voucher was last updated (i.e. had its status changed)

created ✓

datetime

When 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:

"5"

Campaign, redeems as a campaign purchase

"8"

Voucher as payment method

"3"

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.

"6"

Free with order, redeemer is given product and order is created for 0 value. Replaced by 8

Voucher status

An enum, with the following possible values:

"-1"

Voucher is expired and can no longer be redeemed

"0"

Voucher is generated and may be either used or handed out

"1"

Voucher is handed out. If the userId field is set, only this user may redeem it

"2"

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.