PHPackages                             mihaighita/heartland-retail - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. mihaighita/heartland-retail

ActiveLibrary[HTTP & Networking](/categories/http)

mihaighita/heartland-retail
===========================

A PHP client library for the Heartland Retail (retail.heartland.us) REST API

v1.0.7(4mo ago)09MITPHPPHP ^8.2

Since Feb 24Pushed 4mo agoCompare

[ Source](https://github.com/mihaighita/heartland-retail-php)[ Packagist](https://packagist.org/packages/mihaighita/heartland-retail)[ Docs](https://github.com/mihaighita/heartland-retail-php)[ RSS](/packages/mihaighita-heartland-retail/feed)WikiDiscussions main Synced today

READMEChangelog (2)Dependencies (6)Versions (9)Used By (0)

Heartland Retail PHP Client
===========================

[](#heartland-retail-php-client)

[![License: MIT](https://camo.githubusercontent.com/08cef40a9105b6526ca22088bc514fbfdbc9aac1ddbf8d4e6c750e3a88a44dca/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d626c75652e737667)](LICENSE)[![PHP Version](https://camo.githubusercontent.com/e2df0db5111cc996698331f261bf2635d5d982b997163dd61bcd20b2f000f216/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253545382e322d3838393242462e737667)](https://www.php.net/)

A complete, PHP 8.2+ client library for the [Heartland Retail REST API](https://dev.retail.heartland.us/).

---

Features
--------

[](#features)

- **Full API coverage** — Items, Customers, Inventory, Sales, Purchasing, Promotions, Gift Cards, Webhooks, Users & Roles, Tax, Locations, Reports, Custom Fields
- **OAuth 2.0 authorization-code flow** built-in
- **Typed exceptions** — `AuthenticationException`, `AuthorizationException`, `NotFoundException`, `ValidationException`, `RateLimitException`, `TransportException`
- **Automatic rate-limit retry** with `Retry-After` support and exponential back-off on 5xx
- **Proactive throttling** — optional `requestsPerSecond` cap
- **Auto-pagination** — `->all()` helpers transparently walk every page and `yield` records
- **PSR-4** autoloading, strict types throughout
- **TLS enforced** — `CURLOPT_SSL_VERIFYPEER` is always `true`; no option to disable it
- **Sensitive parameter redaction** — access tokens are marked with `#[\SensitiveParameter]`

---

Installation
------------

[](#installation)

```
composer require mihaighita/heartland-retail
```

Requires **PHP 8.2+**, `ext-curl`, and `ext-json`.

---

Quick Start
-----------

[](#quick-start)

```
use HeartlandRetail\Client;

$client = Client::withToken(
    accessToken:       'your_token_here',
    subdomain:         'yourstore',       // → https://yourstore.retail.heartland.us/api
    requestsPerSecond: 5.0                // optional: proactive throttle
);

// Get a single item
$item = $client->items()->get(1234);
echo $item->get('description');

// Search customers
foreach ($client->customers()->search(['email' => 'jane@example.com']) as $c) {
    echo $c['first_name'] . ' ' . $c['last_name'];
}

// Walk ALL items without managing pagination yourself
foreach ($client->items()->all(['active' => true]) as $item) {
    // $item is an associative array
}
```

---

OAuth 2.0 Setup
---------------

[](#oauth-20-setup)

```
use HeartlandRetail\Auth\OAuthClient;
use HeartlandRetail\Client;

$oauth = new OAuthClient(clientId: 'xxx', clientSecret: 'yyy');

// 1. Redirect the user
$state = bin2hex(random_bytes(16));
$_SESSION['oauth_state'] = $state;
header('Location: ' . $oauth->getAuthorizationUrl($redirectUri, $scopes, $state));

// 2. In your callback
if ($_GET['state'] !== $_SESSION['oauth_state']) { die('CSRF'); }
$token  = $oauth->exchangeCodeForToken($_GET['code'], $redirectUri);
$host   = $oauth->lookupAccountHost($token->accessToken);
$client = new Client($token->baseUrlFor($host), $token->accessToken);
```

---

Filters
-------

[](#filters)

```
$client->items()->search([
    'active'      => true,                   // q[active]=1
    'price'       => ['>=', 10.00],          // q[price][>=]=10
    'description' => ['~', 'shirt'],         // q[description][~]=shirt
]);
```

Supported operators: `=`, `!=`, ``, `=`, `~` (contains), `!~` (not contains)

---

Error Handling
--------------

[](#error-handling)

```
use HeartlandRetail\Exception\{
    AuthenticationException,
    AuthorizationException,
    NotFoundException,
    ValidationException,
    RateLimitException,
    TransportException
};

try {
    $client->items()->get(99999);
} catch (AuthenticationException $e) { /* expired/invalid token */ }
  catch (NotFoundException $e)       { /* 404                   */ }
  catch (ValidationException $e)     { print_r($e->getErrors()); }
  catch (RateLimitException $e)      { /* exhausted all retries */ }
  catch (TransportException $e)      { /* network / cURL error  */ }
```

---

License
-------

[](#license)

[MIT](LICENSE)

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance78

Regular maintenance activity

Popularity4

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity52

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

8

Last Release

122d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/e465c0ea59a5e6e4e28ad4ba5b25d846aef392f2c3821abd763e602411a68bac?d=identicon)[mihaighita](/maintainers/mihaighita)

---

Tags

apirestecommerceposinventoryheartlandretailpoint-of-sale

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/mihaighita-heartland-retail/health.svg)

```
[![Health](https://phpackages.com/badges/mihaighita-heartland-retail/health.svg)](https://phpackages.com/packages/mihaighita-heartland-retail)
```

###  Alternatives

[jlevers/selling-partner-api

PHP client for Amazon's Selling Partner API

4335.4M2](/packages/jlevers-selling-partner-api)[bigcommerce/api

Enables PHP applications to communicate with the Bigcommerce API.

1481.1M8](/packages/bigcommerce-api)[pixelpeter/laravel5-woocommerce-api-client

Laravel 5 wrapper for the Woocommerce REST API

123105.4k](/packages/pixelpeter-laravel5-woocommerce-api-client)[highsidelabs/walmart-api

A PHP client for Walmart's Marketplace, 1P Supplier, and Content Provider APIs.

318.4k](/packages/highsidelabs-walmart-api)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)