Payment Services

GET /vouchers/group/{voucherGroupId}

Requires authentication with server access token.

Retrieve a specific voucher group.

Request

GET /api/2/vouchers/group/{voucherGroupId}

voucherGroupId

required path parameter

ID of the voucher group

Example request

cURL
curl https://login.schibsted.com/api/2/vouchers/group/324673248 -G \
   -d "oauth_token=[access token]"
Java
SpidOAuthToken token = spidClient.getServerToken();
String responseJSON = spidClient.
    GET(token, "/vouchers/group/324673248").
    getResponseBody();

This example is an excerpt, see a full example

PHP
<?php
$client->auth();
echo var_dump($client->api("/vouchers/group/324673248"));

This example is an excerpt, see a full example

Clojure
(ns example
  (:require [spid-client-clojure.core :as spid]))

(let [client (spid/create-client "[client-id]" "[secret]")
      token (spid/create-server-token client)]
  (spid/GET client token "/vouchers/group/324673248"))

Response

This endpoint supports the JSON and JSON-P response formats.

Success: 200 OK

Returns the voucher group

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 SPiD to request access.
  • 403 Forbidden Requesting IP is not whitelisted
  • 403 Forbidden Client does not have access to this voucher group
  • 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.
  • 404 Not Found Voucher group not found
  • 420 Request Ratelimit exceeded

Sample response

JSON
{
  "clientId": "[Your client ID]",
  "createdBy": "[ID of admin user, or client]",
  "generatedVouchers": 0,
  "discountId": null,
  "title": "Freebies for all",
  "voucherGroupId": "47",
  "productId": null,
  "availableVouchers": 0,
  "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]",
  "generatedVouchers": 0,
  "discountId": null,
  "title": "Freebies for all",
  "voucherGroupId": "47",
  "productId": null,
  "availableVouchers": 0,
  "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. SPiD reads and responds to every question. Additionally, your experience can help others using SPiD, and it can help us continuously improve our documentation.