README

Official Voucherify SDK for PHP

Migration from 0.x | Setup | Error handling | Contributing | Changelog

Setup

Add Voucherify dependency into your composer.json:

"rspective/voucherify": "v2.0.*"

Update project dependencies:

$ composer install

Log-in to Voucherify web interace and obtain your Application Keys from Configuration:

require_once('vendor/autoload.php');

use Voucherify\VoucherifyClient;
use Voucherify\ClientException;

$apiID  = "YOUR-APPLICATION-ID";
$apiKey = "YOUR-CLIENT-SECRET-KEY";

$client = new VoucherifyClient($apiID, $apiKey);

Versioning

All requests will use your account API settings, unless you override the API version. The changelog lists every available version.

$apiVersion = "v2018-08-01";

$client = new VoucherifyClient($apiID, $apiKey, $apiVersion);

Check versioning.

Custom API URL

By default client is sending request to https://api.voucherify.io. You can override $apiUrl while creating client instance if you want to use Voucherify running in a specific region

$apiVersion = null;
$apiUrl = "https://<region>.api.voucherify.io";

$client = new VoucherifyClient($apiID, $apiKey, $apiVersion, $apiUrl);

Custom Headers

It is possible to send custom headers in Voucherify API request.

$apiVersion = null;
$apiUrl = null;
$customHeaders = [
    "X-Custom-1" => "Value-1"
];

$client = new VoucherifyClient($apiID, $apiKey, $apiVersion, $apiUrl, $customHeaders);

# RESULT:
#   x-custom-1: Value-1

Special: Voucherify-Channel customization

$apiVersion = null;
$apiUrl = null;
$customHeaders = [
    "V-Voucherify-Channel" => "Value-1"
];

$client = new VoucherifyClient($apiID, $apiKey, $apiVersion, $apiUrl, $customHeaders);

# RESULT:
#   x-voucherify-channel: PHP-SDK-Value-1

PHP autoloading

When you aren't using composer you can load Voucherify module by including autoload.php file from /src directory.

require_once('{voucherify_src_path}/autoload.php');

use Voucherify\VoucherifyClient;
use Voucherify\ClientException;

$client = new VoucherifyClient($apiID, $apiKey);

API

This SDK is fully consistent with restufl API Voucherify provides. Detalied description and example responses you will find at official docs. Method headers point to more detalied params description you can use.

Vouchers API

Methods are provided within $client->vouchers->* namespace.

Create Voucher
Get Voucher
Update Voucher
Delete Voucher
List Vouchers
Enable Voucher
Disable Voucher
Add balance to Gift-Card Voucher
Import Vouchers

Check voucher object.

Create Voucher

$client->vouchers->create($voucher);

Get Voucher

$client->vouchers->get($code);

Update Voucher

$client->vouchers->update($voucher_update);

Delete Voucher

$client->vouchers->delete($code);
$client->vouchers->delete($code, $force);

List Vouchers

$client->vouchers->getList();
$client->vouchers->getList($params);

Enable Voucher

$client->vouchers->enable($code);

Disable Voucher

$client->vouchers->disable($code);

Add balance to Gift-Card Voucher

$client->vouchers->addBalance($code, $balance);

Import Vouchers

$client->vouchers->import($vouchers);

Campaigns API

Methods are provided within $client->campaigns->* namespace.

Create Campaign
Get Campaign
Add Voucher to Campaign
Add Voucher with certain code to Campaign
Import Vouchers to Campaign
Delete Campaign

Create Campaign

$client->campaigns->create($campaign);

Get Campaign

$client->campaigns->get($name);

Add Voucher to Campaign

$client->campaigns->addVoucher($campaignName);
$client->campaigns->addVoucher($campaignName, $params);

Add Voucher with certain code to Campaign

$client->campaigns->addVoucherWithCode($campaignName, $code);
$client->campaigns->addVoucherWithCode($campaignName, $code, $params);

Import Vouchers to Campaign

$client->campaigns->importVouchers($campaignName, $vouchers);

Delete Campaign

$client->campaigns->delete($campaignName);

Distributions API

Methods are provided within $client->distributions->* namespace.

Publish Voucher
Create Export
Get Export
Delete Export
List Publications

Publish Voucher

$client->distributions->publish($campaign_name);
$client->distributions->publish($params);

Create Export

$client->distributions->createExport($params);

Get Export

$client->distributions->getExport($exportId);

Delete Export

$client->distributions->deleteExport($exportId);

List Publications

$client->distributions->getPublications();
$client->distributions->getPublications($params);

Validations API

Methods are provided within $client->validations->* namespace.

Validate Voucher
Validate Promotion Campaign

Validate Voucher

$client->validations->validate($code);
$client->validations->validate($code, $params);

// OR

$client->validations->validateVoucher($code);
$client->validations->validateVoucher($code, $params);

Validate Promotion Campaign

$client->validations->validate($params);

Redemptions API

Methods are provided within $client->redemptions->* namespace.

Redeem Voucher
Redeem Promotion's Tier
Get Redemption
List Redemptions
Get Voucher's Redemptions
Rollback Redemption

Check redemption rollback object.

Redeem Voucher

$client->redemptions->redeem($code);
$client->redemptions->redeem($code, $params);

Redeem Promotion's Tier

$client->redemptions->redeem($promotionsTier, $params);

Get Redemption

$client->redemptions->get($redemptionId);

List Redemptions

$client->redemptions->getList();
$client->redemptions->getList($params);

Get Voucher's Redemptions

$client->redemptions->getForVoucher($code);

Rollback Redemption

$client->redemptions->rollback($redemption_id);
$client->redemptions->rollback($redemption_id, $params);
$client->redemptions->rollback($redemption_id, $reason);

Customers API

Methods are provided within $client->customers->* namespace.

Create Customer
Get Customer
Update Customer
Delete Customer
List Customers

Check customer object.

Create Customer

$client->customers->create($customer);

Get Customer

$client->customers->get($customer_id);

Update Customer

$client->customers->update($customer_update);

Delete Customer

$client->customers->delete($customer_id);

List Customers

$client->customers->getList();
$client->customers->getList($params);

Orders API

Methods are provided within $client->orders->* namespace.

Create Order
Get Order
Update Order
List Orders

Check customer object.

Create Order

$client->orders->create($order);

Get Order

$client->orders->get($order_id);

Update Order

$client->orders->update($order_update);

List Orders

$client->orders->getList();

Products API

Methods are provided within $client->products->* namespace.

Create Product
Get Product
List Products
Update Product
Delete Product
Create SKU
Get SKU
List SKUs
Update SKU
Delete SKU

Check product object.

Check sku object.

Create Product

$client->products->create($product);

Get Product

$client->products->get($product_id);

List Products

$client->products->getList();

Update Product

$client->products->update($product_update);

Delete Product

$client->products->delete($product_id);
$client->products->delete($product_id, $force);

Create SKU

$client->products->createSku($product_id, $sku);

Get SKU

$client->products->getSku($product_id, $sku_id);

List SKUs

$client->products->getSkus($product_id);

Update SKU

$client->products->updateSku($product_id, $sku_update);

Delete SKU

$client->products->deleteSku($product_id, $sku_id);
$client->products->deleteSku($product_id, $sku_id, $force);

Validation Rules API

Methods are provided within $client->validationRules->* namespace.

Create Validation Rule
Get Validation Rule
Update Validation Rule
Delete Validation Rule

Check validation rule object.

Create Validation Rule

$client->validationRules->create($rule);

Get Validation Rule

$client->validationRules->get($rule_id);

List Validation Rules

$client->validationRules->getList();

Update Validation Rule

$client->validationRules->update($rule_update);

Delete Validation Rule

$client->validationRules->delete($rule_id);

Create Validation Rule Assignment

$client->validationRules->createAssignment($rule_id, $assignment);

List Validation Rule Assignments

$client->validationRules->getAssignments($rule_id);

Delete Validation Rule Assignment

$client->validationRules->deleteAssignment($rule_id, $assignment_id);

Segments API

Methods are provided within $client->segments->* namespace.

Create Segment
Get Segment
Delete Segment

Check segment object.

Create Segment

$client->segments->create($params);

Get Segment

$client->segments->get($segment_id);

Delete Segment

$client->segments->delete($segment_id);

Events API

Methods are provided within $client->customEvents->* namespace.

Track Custom Event

Check event object.

Track Custom Event

$client->customEvent->track($event, $customer);

Promotions API

Methods are provided within $client->promotions->* namespace.

Create Promotion Campaign
Validate Promotion Campaign
List Promotion's Tiers
Create Promotion's Tier
Redeem Promotion's Tier
Update Promotion's Tier
Delete Promotion's Tier
List Available Promotion Tiers

Check promotion campaign object.

Check promotion's tier object.

Create Promotion Campaign

$client->promotions->create($promotionCampaign);

Validate Promotion Campaign

$client->promotions->validate($validationContext);

List Promotion's Tiers

$client->promotions->tiers->getList($promotionCampaignId);

Create Promotion's Tier

$client->promotions->tiers->create($promotionCampaignId, $promotionsTier);

Redeem Promotion's Tier

$client->promotions->tiers->redeem($promotionsTierId, $redemptionContext);

Update Promotion's Tier

$client->promotions->tiers->update($promotionTierId);

Delete Promotion's Tier

$client->promotions->tiers->delete($promotionTierId);

List Available Promotion Tiers

$client->promotions->tiers->getAvailable();

Async Actions API

Methods are provided within $client->asyncActions->* namespace.

Get Async Action
List Async Actions

Get Async Action

$client->asyncActions->get($id);

List Async Actions

$client->asyncActions->getList();
$client->asyncActions->getList($params);

Utils

To use utils you have to import Voucherify Utils class.

require_once('vendor/autoload.php');

use Voucherify\Utils;

Available methods:

Verify Webhook Signature

Utils::verifyWebhookSignature($signature, $message, $secretKey)

Migration from 0.x

Version 1.x of the PHP is fully backward compatible with version 0.x. Changes made in version 1.x mostly relate to grouping methods within namespaces. So all you need to do is to follow the list bellow and just replace deprecated methods with their namespaced equivalent.

Deprecated methods

$client->vouchers($params) - $client->vouchers->getList
$client->get($code) - $client->vouchers->get
$client->create($voucher) - $client->vouchers->create
$client->update($voucher_update) - $client->vouchers->update
$client->delete($code, $force) - $client->vouchers->delete
$client->disable($code) - $client->vouchers->disable
$client->enable($code) - $client->vouchers->enable
$client->redemption($code) - $client->redemptions->getForVoucher
$client->publish($campaign_name|$params) - $client->distributions->publish
$client->redeem($code, $tracking_id|$params) - $client->redemptions->redeem
$client->redemptions($params) - $client->redemptions->getList
$client->rollback($redemption_id, $params) - $client->redemptions->rollback
$client->customer->* - changed namespace to $client->customers->*

Error handling

VoucherifyClient will throw custom ClientException object. To get sutructure described in our API reference please use:

try {
    ...
}
catch (ClientException $e) {
    $error = $e->getError();
}

Logging

VoucherifyClient has method setLogger() which can be used to set PSR-3 logger interface.

Set own logger if you want to preview curl request and response data.

$logger = /* Initialaze logger i.e Monolog, Analog */

$client = new VoucherifyClient($apiID, $apiKey);
$client->setLogger($logger);

Connection Options

Use setConnectionOptions() method to set client connection options.

Options:

timeout - curl 'CURLOPT_TIMEOUT_MS'
connectTimeout - curl 'CURLOPT_CONNECTTIMEOUT'

$options = [
    "timeout" => 1500,
    "connectTimeout" => 2
];

$client = new VoucherifyClient($apiID, $apiKey);
$client->setConnectionOptions($options);

Use case - CodeIgniter

Simple example of adding Voucherify to your CodeIgniter project.

Setup

Download voucherify /src directory to application/third_party/voucherify.

Custom Library

Create new library file in /application/libraries directory, i.e. Coupons.php.

<?php defined('BASEPATH') OR exit('No direct script access allowed');

$src_voucherify = APPPATH . "third_party/voucherify/autoload.php";

include($src_voucherify);

use Voucherify\VoucherifyClient;
use Voucherify\ClientException;

class Coupons {

    public $voucherify;

    public function __construct() {
        $apiID  = "YOUR-APPLICATION-ID";
        $apiKey = "YOUR-CLIENT-SECRET-KEY";

        $this->voucherify = new VoucherifyClient($apiId, $apiKey);
    }
}

Using Voucherify

Load new library and start using voucherify client.

<?php defined('BASEPATH') OR exit('No direct script access allowed');

class Voucher extends CI_Controller {

    public function index()
    {
        $this->load->library('coupons');

        $voucherCode = "TEST-VOUCHER-CODE";
        $voucher = $this->coupons->voucherify->get($voucherCode);

        ...
    }
}

Contributing

Bug reports and pull requests are welcome through GitHub Issues.

Changelog

2022-05-16 - 2.2.0 - Add CustomEvents support
2022-03-11 - 2.1.0 - Add AsyncActions support and a $customHeaders param
2019-07-19 - 2.0.0 - Hide API versioning in $apiUrl param
2018-12-28 - 1.7.10 - Add Validation Rule Assignments
2018-03-18 - 1.7.9 - Add Utils with verifyWebhookSignature method
2018-02-18 - 1.7.8 - Product delete force option support
2018-02-13 - 1.7.7 - Fix Promotions Tiers getAvailable method param
2018-02-13 - 1.7.6 - Promotions Tiers getAvailable method
2018-02-11 - 1.7.4 - Customers getList method
2018-01-14 - 1.7.3 - Promotions API
2017-07-24 - 1.7.2 - Fix get publications missing params
2017-07-23 - 1.7.1 - Api Client conneciton options
2017-07-12 - 1.7.0 - Orders API
2017-07-10 - 1.6.2 - PHP autoloading support
2017-07-07 - 1.6.1 - Remove Psr/Log dependency
2017-06-26 - 1.6.0 - Api Client logger support
2017-06-21 - 1.5.0 - Custom API URL support
2017-05-02 - 1.4.0 - API Version Header support
2017-05-02 - 1.3.0 - Validation rules API, Segments API, Products API
2017-04-27 - 1.2.0 - Validations API, Redemptions-Get, Distributions-Export
2017-04-26 - 1.1.0 - Campaigns API, Vouchers import method
2017-04-19 - 1.0.2 - Unit tests, bug fixes
2017-03-17 - 1.0.1 - Vouchers addBalance method
2017-02-19 - 1.0.0 - Namespace refectoring
2016-09-13 - 0.11.0 - Added new API method for voucher - publish
2016-09-13 - 0.10.0 - Added new API method for voucher - delete
2016-09-13 - 0.9.1 - Fix to maintain builder pattern.
2016-07-20 - 0.9.0 - Voucher code pattern.
2016-07-19 - 0.8.0 - Voucher update method.
2016-06-23 - 0.7.0 - Gift vouchers.
2016-04-27 - 0.6.0 - Added new API methods for customer - create, get, update, delete.
2016-04-27 - 0.5.0 - Rollback redemption.
2016-04-18 - 0.4.0 - List vouchers. Filter by customer.
2016-04-07 - 0.3.0 - List redemptions.
2016-04-04 - 0.2.2 - Updated API URL.
2016-03-03 - 0.2.1 - Fixed a typo (diasble -> disable).
2016-01-21 - 0.2.0 - Added new API methods - create, disable and enable.
2015-12-11 - 0.1.1 - New discount model. Added UNIT - a new discount type.
2015-12-02 - 0.1.0 - First version:
- Authentication
- Voucher informations: get, redemption
- Voucher operations: redeem

rspective / voucherify

Maintainers

Details

README

Official Voucherify SDK for PHP

Setup

Versioning

Custom API URL

Custom Headers

PHP autoloading

API

Vouchers API

Campaigns API

Distributions API

Validations API

Redemptions API

Customers API

Orders API

Products API

Validation Rules API

Segments API

Events API

Promotions API

Async Actions API

Utils

Verify Webhook Signature

Migration from 0.x

Deprecated methods

Error handling

Logging

Connection Options

Use case - CodeIgniter

Setup

Custom Library

Using Voucherify

Contributing

Changelog