PHPackages                             fulfillment/postage-api - 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. [API Development](/categories/api)
4. /
5. fulfillment/postage-api

ActiveLibrary[API Development](/categories/api)

fulfillment/postage-api
=======================

A wrapper for Fulfillment's Postage API

0.10.0(5y ago)010.3k2MITPHPCI failing

Since Aug 25Pushed 6mo ago5 watchersCompare

[ Source](https://github.com/Fulfillment-dot-com/postage-api-php)[ Packagist](https://packagist.org/packages/fulfillment/postage-api)[ Docs](https://github.com/Fufillment/postage-api-php)[ RSS](/packages/fulfillment-postage-api/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (5)Versions (31)Used By (0)

postage-api-php
===============

[](#postage-api-php)

A PHP library that wraps Fulfillment's Postage API for easy use

Features
--------

[](#features)

- Simple credential configuration
- Automatic authentication handling
- Fully featured PHP classes representing API requests and responses
- Flexible implementation options for API data
- Full range of methods mapping to the Postage API (in-progress)
- Model validation with descriptive, helpful messages
- Descriptive debug output
- Written and used by FDC employees

Example
-------

[](#example)

```
use Fulfillment\Postage\Postage;
use Fulfillment\Postage\Models\Request;

$postageWrapper = new PostageClient(__DIR__); //instantiate Postage with a configuration file or array of settings

$postageObj = new Postage($data); //use plain PHP classes to model a the JSON request that should be sent to the API
$postageObj->setShipper = 'YOUR_SHIPPER';

$postageResponse = $postageWrapper->postage->createPostage($postageObj); //make a request, get a response back as a model
```

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

[](#installation)

```
composer require fulfillment/postage-api

```

Configuration
-------------

[](#configuration)

Configuration needed is simple:

- **USERNAME** - Email address for your account
- **PASSWORD** - Password for your account
- **CLIENT\_ID** - Client Id for your merchant
- **CLIENT\_SECRET** - Client secret for your merchant
- **ACCESS\_TOKEN** - If already created, an access token for your merchant
- **API\_ENDPOINT** - The end point for the fulfillment api services you are using ()

Optional Configurations:

- **JSON\_ONLY** - Defaults to false. If set to true all responses will be returned as pure JSON as it is from the server.
- **VALIDATE\_REQUESTS** -- Defaults to true. Requests will only be validated if the passed data implements `Validatable` and the individual method has not request validation overriden.

There are two ways to configure OMS API

**Use dotenv**

Use a `.env` file compatible with fantastic [phpdotenv](https://github.com/vlucas/phpdotenv) library. Simply specify the absolute path to the folder containing your `.env` file as an argument in the OMS constructor.

```
$postageWrapper = new PostageClient('absolute/path/to/a/folder')
```

An example file called `.env.example` can be found in the root directory.

**Use an array**

Alternatively, create an array with key/values matching the above specified configuration and pass it as an argument in the PostageClient constructor.

```
$config = [
    'username' => '',
    'password' => '',
    'clientId' => '',
    'clientSecret' => '',
    'accessToken' => '',
    'endpoint' => '',
    'jsonOnly' => false,
    'validateRequests' => true
];

$postageWrapper = new PostageClient($config)
```

Usage
-----

[](#usage)

### Passing Your Data To A Request Method

[](#passing-your-data-to-a-request-method)

This package offers several options for data structures for use with the wrapper request methods:

#### Array

[](#array)

All wrapper methods accept a plain PHP array. If your data is already structured to produce a valid JSON body for a request you may simply pass it to a method.

#### Contracts

[](#contracts)

Contracts for `Request` models are available at

```
Fulfillment\Postage\Models\Request\Contracts

```

All wrapper methods will accept a corresponding model contract as an argument.

#### Abstract Models

[](#abstract-models)

These are `abstract class` models that implement the above mentioned contracts. If you wish to use an implemented contract but do not want to use the validation vendor or constructor used in the concrete models (you want to extend yourself) this what you want.

Located at

```
Fulfillment\Postage\Models\Request\Base

```

#### Concrete Models

[](#concrete-models)

These are **ready-to-use classes with built in validation**. Found at

```
Fulfillment\Postage\Models\Request\

```

### Model Types

[](#model-types)

There are two types of models:

**Request Models**

Found at `Fulfillment\Postage\Models\Request` these are the models that are used when making any request that requires data (such as a POST or PUT request). They differ slightly from the other type (`Response` model) because they do not require as much data as is returned from the api.

**Response Models**

Found at `Fulfillment\Postage\Models\Response` these are the models that response json is parsed in to. They inherit from `Request` models and so can be reused to make requests. At this time there is no option to use your own implemented `Response` models for response hydration, but this is a feature in progress.

### Validation

[](#validation)

By default if the object passed into a method implements `Validatable` then it is validated before a request is sent (in the case of a POST or PUT request). A descriptive error will be thrown if a model has any validation failures.

There are two ways to configure this:

- **Set Global Validation** - Set validation during client instantiation, see Configuration above for parameter names
- **Per method** - All POST/PUT requests have an optional `$requestValidation` parameter that will override the global settings.

Roadmap
-------

[](#roadmap)

There's still lots to do, check the issues section to see what is being worked on or make a request.

###  Health Score

39

—

LowBetter than 86% of packages

Maintenance47

Moderate activity, may be stable

Popularity20

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity64

Established project with proven stability

 Bus Factor1

Top contributor holds 94.3% 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 ~86 days

Recently: every ~16 days

Total

21

Last Release

1826d ago

### Community

Maintainers

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

![](https://www.gravatar.com/avatar/2263993374fa87b36ce7376802b73d5fd26d7a420ffc61bcf9049e7692526004?d=identicon)[Fulfillment.com](/maintainers/Fulfillment.com)

---

Top Contributors

[![FoxxMD](https://avatars.githubusercontent.com/u/4663766?v=4)](https://github.com/FoxxMD "FoxxMD (82 commits)")[![MikeGarde](https://avatars.githubusercontent.com/u/1537877?v=4)](https://github.com/MikeGarde "MikeGarde (5 commits)")

---

Tags

fulfillmentfulfillment.com

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/fulfillment-postage-api/health.svg)

```
[![Health](https://phpackages.com/badges/fulfillment-postage-api/health.svg)](https://phpackages.com/packages/fulfillment-postage-api)
```

###  Alternatives

[felixfbecker/advanced-json-rpc

A more advanced JSONRPC implementation

25578.7M6](/packages/felixfbecker-advanced-json-rpc)[cloudconvert/cloudconvert-php

PHP SDK for CloudConvert APIs

2223.4M7](/packages/cloudconvert-cloudconvert-php)[restcord/restcord

REST Library for the Discord API

177452.4k11](/packages/restcord-restcord)[keepa/php_api

API Framework for Keepa.com

55474.9k](/packages/keepa-php-api)[danog/advanced-json-rpc

A more advanced JSONRPC implementation

136.7M5](/packages/danog-advanced-json-rpc)[seatsio/seatsio-php

A PHP client for the seats.io API

17724.2k](/packages/seatsio-seatsio-php)

PHPackages © 2026

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