Voucher API

1. Issuing a voucher to user

URL endpoint: https://stamps.co.id/api/vouchers/issue

Allowed Method: POST

Require Authentication: Yes

A. Request

You can add issue a voucher by calling the API with these parameters.

Parameter	Required	Description
user	Yes	A string indicating user’s email address or member ID
voucher_template	Yes	Integer indicating the voucher template ID
start_date	Yes	Date string to indicate voucher’s valid start date (e.g. 2013-02-15)
quantity	Yes	Integer indicating voucher quantity to be given
notes	No	Note tied to the voucher
value	No	Float indicating voucher value to be given, Required if voucher template value type is dynamic
per_page	No	Integer, Determines the number of vouchers to be returned per API call.
last_voucher_id	No	Integer, Specifies the ID of the last voucher from which the API should start retrieving vouchers.

Here’s an example of how the API call might look like in JSON format

{
    "user": "customer@stamps.co.id",
    "voucher_template": 1,
    "start_date": "2013-02-15",
    "quantity": 1,
    "notes": "Special voucher for e-magazine readers",
    "value": 200
}

Example of API call request using cURL

$ curl -X POST -H "Content-Type: application/json" -H "Authorization: <token_type> <token>" -d '{ "user": "customer@stamps.co.id", "voucher_template": 1, "start_date": "2013-02-15", "quantity": 1, "notes": "Special voucher for e-magazine readers", "value": "200"}' https://stamps.co.id/api/vouchers/issue

B. Response

In response to this API call, Stamps will return response with the following data (in JSON):

Variable	Description
customer	An object containing customer information after successful request. Contains id and email.
voucher	An object containing the information on the voucher created with the request. Contains id, start_date, end_date, quantity, and notes.
errors	Errors encountered when processing request (if any)

C. Example Response

On successful balance update:

HTTP/1.0 200 OK
Vary: Accept
Content-Type: application/json
Allow: POST, OPTIONS
 [Redacted Header]

{
  "voucher": {
    "id": 123054,
    "start_date": "2014-11-20",
    "end_date": "2014-11-30",
    "quantity": 1,
    "notes": "Special voucher for e-magazine readers",
    "value": 200
  },
  "customer": {
    "id": 6,
    "email": "customer@stamps.co.id"
  }
}

2. Validating a Voucher

URL endpoint: https://stamps.co.id/api/vouchers/validate

Allowed Method: GET

Require Authentication: Yes

A. Request

You can add issue a voucher by calling the API with these parameters.

Parameter	Required	Description
voucher_code	Yes	A string indicating voucher code
merchant	Yes	Integer indicating the voucher template ID
store	Yes	Integer indicating store ID to be queried for reward
user	No	User identifier, will validate voucher owner if provided
transaction_value	No	Transaction value that will be used for redemption

Example of API call request using cURL

$ curl -H 'Authorization: <token_type> <token>' 'https://stamps.co.id/api/vouchers/validate?merchant=123&voucher_code=VC-ABC&store=123'

B. Response

In response to this API call, Stamps will return response with the following data (in JSON):

Variable	Description
user	An object containing customer information.
voucher	An object voucher information.
errors	Errors encountered when processing request (if any)

C. Example Response

On successful balance update:

  HTTP/1.0 200 OK
  Vary: Accept
  Content-Type: application/json
  Allow: GET
    [Redacted Header]

    {
    "is_redeemable": true,
    "user": {
        "email": "foo@bar.com",
        "name": "Alice",
        "phone": "+628123123123"
    },
    "voucher": {
        "extra_data": {
            "discount": 1000,
        },
        "id": 123,
        "name": "Rp. 100,000 Discount",
        "value": 100000,
        "start_date": "2021-04-26",
        "end_date": "2021-05-24",
        "validity": "Dynamic"
    }
}

The voucher is not owned by the user provided in the parameter:

HTTP/1.0 400 BAD REQUEST
Vary: Accept
Content-Type: application/json
[Redacted Header]

{
    "detail": "user: This voucher is not owned by Alice",
    "error_message": "user: This voucher is not owned by Alice",
    "error_code": "invalid_voucher_owner",
    "errors": {
        "user": "This voucher is not owned by Alice"
    }
}

3. Get Vouchers by Merchant Group

URL endpoint: https://stamps.co.id/api/vouchers/by-merchant-group

Allowed Method: GET

Require Authentication: Yes

A. Request

You can get user’s vouchers in a merchant group by calling the API with these parameters.

Parameter	Required	Description
user	Yes	A string indicating customer’s email or Member ID
image_size	No	Voucher image size. Defaults to 200px x 200px
landscape_image_size	No	Voucher image landscape size. Defaults to 545px x 300px
channel	No	Integer indicating channel number to be queried for user’s vouchers.

Example of API call request using cURL

$ curl -H 'Authorization: <token_type> <token>' 'https://stamps.co.id/api/vouchers/by-merchant-group?user=customer@stamps.co.id&channel=2'

B. Response

In response to this API call, Stamps will return response with the following data (in JSON):

Variable	Description
vouchers	An array containing information on user’s vouchers.

C. Example Response

On a successful API call:

HTTP/1.0 200 OK
Vary: Accept
Content-Type: application/json
Allow: POST, OPTIONS
 [Redacted Header]

{
  "vouchers": [
    {
        "id": 1,
        "code": "VC-ABC",
        "is_active": true,
        "quantity": 1,
        "value": 200,
        "notes": "",
        "start_date": "2022-03-28",
        "end_date": "2022-04-28",
        "constraint": {
            "channels": [1, 2, 3, 4]
        },
        "template": {
            "id": 1,
            "name": "March Surprise Voucher",
            "type": 1,
            "short_description": "Get 50% off on your next purchase",
            "picture_url": "foo.png",
            "landscape_picture_url": "foo_landscape.png",
            "merchant_id": 1,
            "merchant_code": "M-ABC",
            "extra_data": null
        },
    },
    {
        "id": 2,
        "code": "VC-DEF",
        "is_active": true,
        "quantity": 2,
        "notes": "",
        "value": 200,
        "start_date": "2022-02-14",
        "end_date": "2022-02-28",
        "constraint": {
            "channels": [1, 2, 3, 6]
        },
        "template": {
            "id": 2,
            "name": "Valentine Voucher",
            "type": 1,
            "short_description": "Get 50% off on your next purchase",
            "picture_url": "foo.png",
            "landscape_picture_url": "foo_landscape.png",
            "merchant_id": 1,
            "merchant_code": "M-ABC",
            "extra_data": {}
        }
    }
  ]
}

4. Get Vouchers Count by Merchant Group

URL endpoint: https://stamps.co.id/api/vouchers/count-by-merchant-group

Allowed Method: GET

Require Authentication: Yes

A. Request

You can get user’s vouchers count in a merchant group by calling the API with these parameters.

Parameter	Required	Description
user	Yes	A string indicating customer’s email or Member ID

Example of API call request using cURL

$ curl -H 'Authorization: <token_type> <token>' 'https://stamps.co.id/api/vouchers/count-by-merchant-group?user=customer@stamps.co.id'

B. Response

In response to this API call, Stamps will return response with the following data (in JSON):

Variable	Description
count	Number of voucher a user has in a merchant group.

C. Example Response

On a successful API call:

HTTP/1.0 200 OK
Vary: Accept
Content-Type: application/json
Allow: POST, OPTIONS
 [Redacted Header]

{
  "count": 12,
}

5. Get Voucher Details

URL endpoint: https://stamps.co.id/api/vouchers/details

Allowed Method: GET

Require Authentication: Yes

A. Request

Get user’s voucher’s details.

Parameter	Required	Description
user	Yes	A string indicating customer’s email or Member ID
code	Yes	A string indicating voucher code
image_size	No	Voucher image size. Defaults to 200px x 200px
landscape_image_size	No	Voucher image landscape size. Defaults to 545px x 300px

Example of API call request using cURL

$ curl -H 'Authorization: <token_type> <token>' 'https://stamps.co.id/api/vouchers/details?user=customer@stamps.co.id&code=ABCD123'

B. Response

In response to this API call, Stamps will return response with the following data (in JSON):

Variable	Description
voucher	An object containing voucher information.

C. Example Response

On a successful API call:

HTTP/1.0 200 OK
Vary: Accept
Content-Type: application/json
Allow: POST, OPTIONS
 [Redacted Header]

{
    "id": 2,
    "code": "VC-DEF",
    "is_active": true,
    "quantity": 2,
    "notes": "",
    "value": 200,
    "terms_and_conditions": "",
    "start_date": "2022-02-14",
    "end_date": "2022-02-28",
    "constraint": {
        "channels": [1, 2, 3, 6]
    },
    "template": {
        "id": 2,
        "name": "Valentine Voucher",
        "type": 1,
        "short_description": "Get 50% off on your next purchase",
        "description": "Get 50% off on your next purchase",
        "instructions": "",
        "terms_and_conditions": "",
        "picture_url": "foo.png",
        "landscape_picture_url": "foo_landscape.png",
        "merchant_id": 1,
        "merchant_code": "M-ABC",
        "extra_data": {}
    }
}

Miscellaneous

Voucher Template Type Mapping

Code	Description
1	Cross Promotion
2	Regular
3	Promotion
4	Signup
5	Birthday
6	Referral
7	Pregenerated
8	Anniversary

Channel Type

Integer Value	Description
1	Mobile app
2	POS
3	Kiosk
4	Web
5	Android
6	iOS