PHPackages                             cartboss/cartboss-php - 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. [Payment Processing](/categories/payments)
4. /
5. cartboss/cartboss-php

ActiveLibrary[Payment Processing](/categories/payments)

cartboss/cartboss-php
=====================

2.0.3(4y ago)1531MITPHPPHP >=7.3

Since Sep 9Pushed 3y ago1 watchersCompare

[ Source](https://github.com/CartBoss/cartboss-php)[ Packagist](https://packagist.org/packages/cartboss/cartboss-php)[ Docs](https://www.cartboss.io)[ RSS](/packages/cartboss-cartboss-php/feed)WikiDiscussions main Synced yesterday

READMEChangelog (6)Dependencies (4)Versions (12)Used By (0)

Requirements
------------

[](#requirements)

To use CartBoss SDK, the following things are required:

- Get yourself a free [CartBoss account](https://app.cartboss.io/account/register). No sign up costs.
- Add new [website](https://app.cartboss.io/sites/) to get API key.
- PHP >= 7.3
- Up-to-date OpenSSL (or other SSL/TLS toolkit)

Composer Installation
---------------------

[](#composer-installation)

By far the easiest way to install the CartBoss SDK is to require it with [Composer](http://getcomposer.org/doc/00-intro.md).

```
$ composer require cartboss/cartboss-php:^2.0

{
    "require": {
        "cartboss/cartboss-php": "^2.0"
    }
}

```

Before you begin
----------------

[](#before-you-begin)

Please take a few minutes to learn about basic CartBoss concepts.

### 1. Events

[](#1-events)

CartBoss is an event based service. Our SDK includes everything you need to build, validate and send events to CartBoss either in "real-time" or from your backend.

#### 1.1. AddToCart event

[](#11-addtocart-event)

AddToCart event occurs when visitor leaves your site without placing an order. It is up to you to decide when this makes sense for your case, but most common implementation is to send AddToCart event **every time** visitor updates one of the checkout fields (eg. First name, Phone, Cart items, ...).

AddToCart event is then processed by CartBoss and a queue of abandoned cart messages for provided phone number is created at our end. If there's no following Purchase event received, CartBoss will start sending messages accordingly to your abandoned cart automation setup.

It's perfectly fine to send multiple AddToCart events for same order.

#### 1.2. Purchase event

[](#12-purchase-event)

Purchase event occurs when visitor places an order. Purchase event is very similar to AddToCart event, with an addition of CartBoss Attribution token (explained below).

When CartBoss receives Purchase event for particular order, all remaining messages from abandoned cart sequence are destroyed and never sent. If enabled, a new post-purchase sequence is created.

Because of this, it is very important to make sure you send Purchase event for all "completed" orders from your backend (eg. cronjob). Basic implementation would include adding a new boolean field `send_cartboss_purchase` to your order table with default value set as false, updated to true once order is placed.

### 2. URL Interceptors

[](#2-url-interceptors)

Most text messages (SMS) sent by CartBoss to your contacts contain an urls that take them back to your site when clicked.

CartBoss "communicates" with your site through a few special URL query parameters prefixed with "cb\_\_". With the help of CartBoss SDK you can easily access intercepted values through registered listeners.

#### 2.1. Attribution Interceptor

[](#21-attribution-interceptor)

CartBoss's Attribution token (cb\_\_att) is a 64char hash injected into **all urls** pointing to your site. It helps CartBoss to distinct between organic and CartBoss-based purchases. Your main objective is to intercept, store and pass attribution token to Purchase event once order is successfully placed.

Example urls with Attribution Token injected:

```
https://www.your-site.com?cb__att=7zd1n87e8712z87nzdqs87z1278dnz1
https://store.your-site.com/path/?foo=bar&?cb__att=7zd1n87e8712z87nzdqs87z1278dnz1

```

#### 2.2. Discount Interceptor

[](#22-discount-interceptor)

CartBoss's Discount token (cb\_\_discount) is an encrypted and urlencoded array of three values (**type|code|value**). It enables you to send dynamic offers to your visitors (eg. *Hi Mike, order now and get 20% OFF of your entire order. Click here* ).

Example urls with Discount Token injected:

```
https://www.your-site.com?cb__discount=
https://store.your-site.com/path/?foo=bar&?cb__discount=

```

Discount interceptor validates, decodes and returns valid Coupon object if discount is provided through SMS message.

Example implementation
----------------------

[](#example-implementation)

Our code includes Example project which can be found at this link [Example project](https://github.com/CartBoss/cartboss-php/tree/main/examples). In case you need additional help, please contact us.

Getting started
---------------

[](#getting-started)

### 1. Initializing CartBoss SDK

[](#1-initializing-cartboss-sdk)

Initialize CartBoss SDK library with your API key. It is recommended to initialize CartBoss SDK and register URL interceptors on each request and as early as possible in your code.

```
$cartboss = new \CartBoss\Api\CartBoss("l33t87zd1n87e8712z87nzdqs87z1278dnz187wzne");
```

### 2. Registering Attribution interceptor

[](#2-registering-attribution-interceptor)

Every time **Attribution token** is intercepted and pushed to your implementation of `onAttributionIntercepted()`method, it's advised to store it into session/cart/order/database for later use, as you're going to attach it to Purchase event later on.

```
$cartboss->onAttributionIntercepted(function(Attribution $attribution) {
    print $attribution->isValid(); // bool
    print $attribution->getToken(); // n87e8712z87nzdqs87z12712z87nzdq78dnz187w

});
```

### 3. Registering Discount interceptor

[](#3-registering-discount-interceptor)

Every time **Discount token** is intercepted and pushed to your implementation of `onCouponIntercepted()` method, you should insert a new coupon (if it doesn't already exist) to your database and attach it to visitor's cart/order/session.

```
$cartboss->onCouponIntercepted(function(Coupon $coupon) {
    print $attribution->isValid(); // bool
    print $attribution->getType(); // PERCENTAGE|FIXED_AMOUNT|FREE_SHIPPING|CUSTOM
    print $attribution->getValue(); // float
    print $attribution->getCode(); // str

    // helper methods
    print $attribution->isFreeShipping(); // bool
    print $attribution->isPercentage(); // bool
    print $attribution->isFixedAmount(); // bool
    print $attribution->isCustom(); // bool
});
```

### 4. Sending AddToCart event

[](#4-sending-addtocart-event)

AddToCart event is usually sent, whenever new checkout information is available. For example; when visitor enters a phone number, sets first name, or updates delivery country...

**There are two very important aspects to keep in mind:**

- order\_id provided through `$order->setId("...")` is a glue between AddToCart and Purchase events. It tells CartBoss that order which has been previously "abandoned" is now "purchased".
- checkout\_url provided through `$order->setCheckoutUrl("...")` points to your script that should be able to restore previously abandoned session/order (Desktop) in a new browser (Phone). Keep in mind cookies are not shared between browsers and/or webviews (Facebook app, etc.).

Minimal AddToCart event example. You can find full example at [event\_atc.php](https://github.com/CartBoss/cartboss-php/blob/main/examples/event_atc.php).

```
// Create AddToCart event
$event = new AddToCartEvent();

// Create contact
$contact = new Contact();
$contact->setPhone("1234567");
$contact->setCountry("US");
$contact->setFirstName("Jake");
$contact->setAcceptsMarketing(true); // in case your site supports "consent checkout field"

// Add contact to event
$event->setContact($contact);

// Create order
$order = new Order();
$order->setId("1001"); // id that uniquely represents cart/order in your local database
$order->setValue(19.99); // float 2 decimals
$order->setCurrency('EUR'); // currency code

// Set publicly accessible url to the script that can restore visitor's order from provided order id
// https://www.your-site.com/cartboss-restore-cart.php?order_id=1001
// https://www.your-site.com/cartboss-restore-cart.php?order_hash=9n12998as7as798d791dn988jdsa (if you don't want to expose db order_id)
$order->setCheckoutUrl("https://site.com/cartboss/cart_restore.php?order_id=1001");

// Add order to event
$event->setOrder($order);

// Send event to CartBoss
try {
    $cartboss->sendOrderEvent($event);

} catch (EventValidationException $e) {
    var_dump($e->getMessage());

} catch (ApiException $e) {
    var_dump($e->getMessage());
}
```

### 5. Restoring abandoned cart

[](#5-restoring-abandoned-cart)

Each abandoned cart text messages includes shortened url (checkout\_url) back to your website. URL is provided through a method `setCheckoutUrl()` with AddToCart event. This handler must be publicly accessible and able to restore visitors old session within a new browser.

Implementation of this script is up to your business logic, but in abstract implementation, it should do the following:

1. parse url parameter for order\_id
2. fetch order from your local database
3. check if order exists and is still in "abandoned" state
4. store order\_id to visitors session
5. redirect to your checkout page (along with utm\_ params)
6. otherwise, redirect visitor to your home page

You can find example cart restore script at [cart\_restore.php](https://github.com/CartBoss/cartboss-php/blob/main/examples/cart_restore.php).

### 6. Sending Purchase event

[](#6-sending-purchase-event)

Purchase event is sent once the order has been placed on your store. It is highly suggested sending these events from your backend eg. 1min cronjob.

Minimal Purchase event example. You can find full example at [event\_purchase.php](https://github.com/CartBoss/cartboss-php/blob/main/examples/event_purchase.php).

```
// Create AddToCart event
$event = new PurchaseEvent();

// Attach attribution token, you have received through Attribution URL Interceptor when visitor visited your site
// through SMS link.
$event->setAttributionToken("...");

// Create contact
$contact = new Contact();
$contact->setPhone("1234567");
$contact->setCountry("US");
$contact->setFirstName("Jake");
$contact->setAcceptsMarketing(true); // in case your site supports "consent checkout field"

// Add contact to event
$event->setContact($contact);

// Create order
$order = new Order();
$order->setId("1001"); // id that uniquely represents cart/order in your local database
$order->setValue(19.99); // float 2 decimals
$order->setCurrency('EUR'); // currency code

// Add order to event
$event->setOrder($order);

// Send event to CartBoss
try {
    $cartboss->sendOrderEvent($event);

} catch (EventValidationException $e) {
    var_dump($e->getMessage());

} catch (ApiException $e) {
    var_dump($e->getMessage());
}
```

### FAQ

[](#faq)

Q: What happens when AddToCart event is sent to CartBoss?
A: A queue of abandoned cart text messages is created for provided phone number - usually one to three texts.

Q: When does CartBoss stop sending abandoned cart texts?
A: When a Purchase event with same $order->setId() as AddToCart event is received, or all texts from the queue have been sent out.

Q: What happens if I don't provide attribution token with Purchase event?
A: Such event will not count towards CartBoss statistics, as it's considered as organic conversion.

Q: What is checkout\_url I have to send with AddToCart event?
A: An URL that is sent to your visitor to restore session/cart in a new mobile browser.

Q: Should I send a Purchase event for every purchase made on our site - organic and CartBoss based?
A: Yes

Q: What should I don if sending an event fails?
A: You can simply ignore AddToCart errors, but should do your best to deliver all Purchase events.

### Helpers

[](#helpers)

We provide a few helper methods to ease your CartBoss SDK integration.

#### PHP

[](#php)

Please see [`CartBoss\Api\Utils`](https://github.com/CartBoss/cartboss-php/blob/main/src/Utils.php) for available helper functions.

#### JS

[](#js)

Please see [CartBossJS](https://github.com/CartBoss/cartboss-php/blob/main/examples/js/cartboss-helper.js) for more info. jQuery required.

###  Health Score

25

—

LowBetter than 37% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity11

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity52

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 97.9% of commits — single point of failure

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 ~19 days

Recently: every ~43 days

Total

11

Last Release

1511d ago

Major Versions

1.0.6 → 2.0.02021-10-24

PHP version history (2 changes)1.0.0PHP >=7.2

2.0.0PHP >=7.3

### Community

Maintainers

![](https://www.gravatar.com/avatar/98071494ac853b18abdd2aa894cd0a9c10d82c01f773b453cf1313914f9924ef?d=identicon)[cartboss](/maintainers/cartboss)

---

Top Contributors

[![dmalis](https://avatars.githubusercontent.com/u/274254?v=4)](https://github.com/dmalis "dmalis (47 commits)")[![CartBoss](https://avatars.githubusercontent.com/u/90379540?v=4)](https://github.com/CartBoss "CartBoss (1 commits)")

### Embed Badge

![Health badge](/badges/cartboss-cartboss-php/health.svg)

```
[![Health](https://phpackages.com/badges/cartboss-cartboss-php/health.svg)](https://phpackages.com/packages/cartboss-cartboss-php)
```

###  Alternatives

[imdhemy/google-play-billing

Google Play Billing

491.3M5](/packages/imdhemy-google-play-billing)[buckaroo/sdk

Buckaroo payment SDK

12189.1k9](/packages/buckaroo-sdk)[bitpay/sdk

Complete version of the PHP library for the new cryptographically secure BitPay API

42337.5k4](/packages/bitpay-sdk)[flutterwavedev/flutterwave-v3

A simple SDK for integrating to Flutterwave Payment

24174.1k6](/packages/flutterwavedev-flutterwave-v3)[contica/facturador-electronico-cr

Un facturador de código libre para integrar facturación electrónica en Costa Rica a un proyecto PHP

2128.8k](/packages/contica-facturador-electronico-cr)

PHPackages © 2026

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