Download the PHP
package quoyer/quoyer-php without Composer
On this page you can find all versions of the php package
quoyer/quoyer-php. It is possible to download/install
these versions without Composer. Possible dependencies are resolved
automatically.
Vendor quoyer Package quoyer-php Short Description Official PHP SDK for the Quoyer loyalty API: customers, points, redemptions, webhooks, with Laravel integration. License
MIT Homepage https://github.com/ovency/quoyer-php
After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.
Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories.
In this case some credentials are needed to access such packages.
Please use the auth.json textarea to insert credentials, if a package is coming from a private repository.
You can look here for more information.
Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
To use Composer is sometimes complicated. Especially for beginners.
Composer needs much resources. Sometimes they are not available on a simple webspace.
If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
The official PHP client for the Quoyer loyalty API: enrol
customers, award and reverse points, redeem them as coupons, read balances and
history, and verify webhooks. Works in any PHP 8.2+ project, with a Laravel
service provider, facade and webhook middleware included.
SDK 1.0 covers API contract v1.9 in full. The complete API reference is at
quoyer.com/api/docs.
Contents
Requirements
Installation
Configuration
Laravel
Five things to know first
Usage
Errors
Retries, timeouts and rate limits
Pagination
Webhooks
Reading response headers
Calling endpoints newer than the SDK
Testing your integration
Versioning
More documentation
Requirements
PHP 8.2 or newer, with ext-json
Guzzle 7.15.2+ or 8.0.1+ (installed with the SDK; Laravel already ships it)
A Quoyer API key: the merchant creates one in the dashboard under
Integration → API keys. It is shown once.
Installation
Configuration
Option
Default
What it does
api_key
required
The merchant's key, quoy_live_… or quoy_sandbox_…. Keep it server-side: never in a browser, an app bundle or version control.
base_url
https://quoyer.com
The Quoyer install. /api/v1 is added for you. Must be https, except on localhost and *.test hosts.
store_url
none
Storefronts only. Sent as X-Quoyer-Store on every call, which registers the shop as a connected store on the merchant's plan. Leave it out for a back-office integration or a script: those are never counted. See Connected stores.
platform
none
name/version of your platform. Shown as the connected store's platform in the merchant's dashboard.
timeout
10
Seconds to wait for a whole response.
connect_timeout
3
Seconds to wait for a connection. A storefront should never hold a shopper's checkout for long.
max_retries
2
Retries after the first attempt. See Retries.
max_retry_wait
5
The longest Retry-After (seconds) the client sleeps through on a 429.
A second argument takes your own Guzzle client (proxies, custom TLS, test
mocks): new QuoyerClient($options, $guzzle).
Several merchants in one app? Derive a client per merchant; the copies
share one HTTP client:
Laravel
The service provider and the Quoyer facade are auto-discovered. Add your key
to .env:
Then inject the client, or use the facade:
Publish the config file to change more (php artisan vendor:publish --tag=quoyer-config).
Webhooks get a ready-made middleware: see docs/laravel.md.
Five things to know first
Identify customers by your own id. Send external_id + external_source
(your platform's name, e.g. myshop) on every upsert, and
customer_external_id + customer_external_source on credits and
redemptions. You never have to store Quoyer's cus_ id. In a physical
store, customer_card_number or customer_phone work too.
Upsert before you credit.customers->upsert() creates or updates;
call it before every credit so the customer exists.
Every write has a source_reference, and it makes the write safe to
repeat. Build one stable reference per business event
(myshop_order_5531) and send it every time. A repeat returns the original
result (wasNew() is false), so a retry after a timeout can never award or
spend twice.
Branch on error codes, not messages.$e->getErrorCode() is stable;
messages change. Account-state messages are safe to show a shopper;
getAdminReason() never is.
*Money in `_minor_unitsis always hundredths**, for every currency, zero-decimal ones included: ¥1,500 is150000. Amounts you *send* in metadata.amountare plain decimals (49.99`).
More in docs/concepts.md.
Usage
Every service is a property of the client (and a method, for the facade).
Parameters are arrays with the API's own field names, so everything in the
API reference works as documented. Enums
(Quoyer\Enums\RuleType::Purchase) and DateTimeInterface values are
accepted wherever a string is.
Account
Customers
Points
Signup, newsletter and review bonuses use RuleType::Signup,
NewsletterSignup and Review with their own source_reference
(myshop_signup_1042). Never credit birthday or referral: Quoyer does.
Redemptions
The limits per redemption are on the programme: $quoyer->program->retrieve()->minimum_redemption_points.
Everything else
Every method, with the endpoint it calls: docs/reference.md.
Reading objects
Responses are read-only objects. Read fields as properties or array keys; an
absent field reads as null. Nested objects are typed by their object field.
Fields added to the API after this SDK was released are kept and readable:
the SDK never drops what the API sends.
Errors
Every exception implements Quoyer\Exceptions\QuoyerException.
Exception
When
AuthenticationException
401: missing, invalid or revoked key. Stop and ask the merchant for a key.
AccountStateException
403: the account refuses this call (redemption paused, read-only, programme paused or closed, store limit). getMessage() is shopper-safe.
422: a field failed validation. getErrors() has every field.
InvalidRequestException
Any other refusal: insufficient_points, email_conflict, member_limit_reached, no_active_rule, feature_not_in_plan… (parent of the two above).
RateLimitException
429 beyond max_retry_wait. getRetryAfter() says how long.
ConfigurationException
Something is not set up: unconfigured_currency, or a Quoyer-side problem.
ConnectionException
Quoyer could not be reached. Repeat the call with the same source_reference.
UnexpectedResponseException
Not the API's answer (HTML, a redirect): usually a wrong base_url.
InvalidArgumentException
The SDK was called wrongly (no key, empty id, no source_reference). Nothing was sent.
ErrorCode has a constant for every code the API sends. The full list, with
what to do about each: docs/errors.md.
Retries, timeouts and rate limits
The client retries for you, and only when it is safe:
Connection errors and 502/503/504 are retried up to max_retries times
with exponential backoff and jitter (about 0.5 s, then 1 s), for every read
and every write the API makes idempotent: upserts, credits, reversals,
redemptions, updates. Creating an earning rule or a currency, deleting a
customer, and an upsert carrying a referral_code are never retried,
because a lost answer followed by a retry could do them twice.
429 Too Many Requests is retried for any call (the API refused it before
doing anything), but only when Retry-After is at most max_retry_wait
seconds. A longer wait throws RateLimitException at once: a storefront
should not hold a shopper for a minute.
Limits are per merchant, shared by all their keys, per minute: reads get the
plan's api_per_min, writes a fifth of it.
Pagination
Lists come oldest first, 20 per page by default (up to 100).
Webhooks
Quoyer can POST events to your URL: customer created/updated/deleted, points
credited or reversed, redemptions, tier changes, referral rewards, expiries.
Always verify the signature against the raw body:
Deduplicate on $event->id: it is the same on every retry. In Laravel, use the
quoyer.webhook middleware instead. Details: docs/webhooks.md.
Reading response headers
Every object keeps the response it came from:
Calling endpoints newer than the SDK
If the API gains an endpoint before the SDK does, call it directly. You get
the same authentication, headers and exceptions:
Pass retryable: true only for a write that is safe to repeat.
Testing your integration
Pass a Guzzle client with a mock handler to test without the network:
Sign test webhooks with Webhook::generateSignatureHeader($body, $secret).
For end-to-end tests, use a test merchant's key against staging.
Versioning
The SDK follows Semantic Versioning. Each release names
the API contract version it covers (QuoyerClient::API_CONTRACT).
A new field in the API needs no SDK release: unknown fields are kept.
A new endpoint or parameter arrives in a minor release.
A breaking change in the API, which Quoyer announces in advance, arrives in
a major release.
Requiresphp Version
^8.2 ext-json Version
* guzzlehttp/guzzle Version
^7.15.2 || ^8.0.1
Composer command for our command line client (download client)This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free.Standard composer command
The package quoyer/quoyer-php contains the following files
Loading the files please wait ...
Loading please wait ...
Before you can download the PHP files, the dependencies should be resolved. This can take some minutes. Please be patient.