PHP SDK for Voucherify - coupons, vouchers, promo codes
PHP
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
docs/images
src
test
.gitignore
LICENSE.md
README.md
composer.json
composer.lock
phpunit.xml

README.md

Official Voucherify SDK for PHP


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

API: Vouchers | Campaigns | Distributions | Validations | Redemptions | Customers | Orders | Products | Validation Rules | Segments | Promotions | Utils

Setup

Add Voucherify dependency into your composer.json:

"rspective/voucherify": "v1.7.*"

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 = "v2017-04-05";

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

Check versioning.

Custom API URL

By default client is sending request to https://api.voucherify.io/v1. You can override default api url while creating client instance.

$apiVersion = null;
$apiUrl = "https://custom-api-url";

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

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.

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

$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

$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

$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.

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.

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.

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.

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.

Check validation rule object.

Create Validation Rule

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

Get Validation Rule

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

Update Validation Rule

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

Delete Validation Rule

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

Segments API

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

Check segment object.

Create Segment

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

Get Segment

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

Delete Segment

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

Promotions API

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

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();

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


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

  • 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