If you have any questions regarding the API we are happy to help you via our API support at api@c1st.com.

Please be specific and include the following information:

• A detailed description of the problem with a step-by-step description of what you do and what happens.
• Store details, specifically the StoreId.
• If possible, include a complete request and response.
• Screenshots, if possible.
• Other relevant or helpful information.

The API is forward-compatible. We take the freedom to add optional attributes to endpoints without notice. In this case, you should be aware that a PUT request replaces an entire object. i.e. not specifying a field on an object will null the field. To update a single field on e.g. a product you must first GET the product and then PUT the entire product with the new updated field. See example below.

We may introduce breaking changes to endpoints. In such case, you will be contacted via the email provided at the API token setup page with a transition period.

Send the header

Authorization: Bearer <token>

<token> can be found at https://app.deltateq.com/en -> Settings -> API -> API users.

We recommend creating a new user for each integration.

API requests are subject to potential throttling to limit excess load on our servers.

Throttling of requests is based on a simple bucket resource model (similar to the leaking bucket algorithm, except the bucket fills up instead of leaking). You are free to make API requests until the resource bucket is depleted, after which requests will return an HTTP 429 error.

The current bucket size is 80 and the filling (regen) rate is 8 requests per second. These limitations are subject change but are included within the HTTP response for throttled requests:

{
    "error": "API Resource limit reached.",
    "bucket_size:" "80",
    "bucket_regen": "8"
}

We urge you to use the API in a fair manner, and not introducing unnecessary load. Constantly retrieving all data or regularly updating the entire product catalog via bulk operations are examples of what we would consider unfair API usage. Instead, use hooks and only update changed products. Customers 1st monitors API usage to identity excessive API usage. We will try to get in contact on excessive use, but we may be forced to reduce limits until the matter has been resolved.

A list of settings configs can be found here

<?php
class Customers1stException extends Exception
{
    public $err;
    public function __construct($error)
    {
        $this->err = $error;
        parent::__construct($error['message']);
    }
}

class Customers1st
{
    private $token = null;

    function __construct($token)
    {
        $this->token = $token;
    }

    function call($method, $endpoint, $data = false)
    {
        $url = 'https://app.deltateq.com/api' . $endpoint;
        $curl = curl_init();
        switch ($method) {
            case "POST":
                curl_setopt($curl, CURLOPT_POST, 1);
                if ($data) {
                    curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
                }
                break;
            case "PUT":
                curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PUT');
                if ($data) {
                    curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
                }
                break;
            default:
                if ($data) {
                    $url = sprintf("%s?%s", $url, http_build_query($data));
                }
        }
        curl_setopt($curl, CURLOPT_HTTPHEADER, array(
            'Accept: application/json',
            'Content-Type: application/json',
            'Authorization: Bearer ' . $this->token,
        ));
        curl_setopt($curl, CURLOPT_URL, $url);
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
        $result = curl_exec($curl);
        $status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
        if ($status >= 300) {
            throw new ServicePOSException([
                'endpoint' => $url,
                'status' => $status,
                'error' => $this,
                'method' => 'post',
                'message' => 'Service API',
                'result' => $result
            ]);
        }
        curl_close($curl);
        return json_decode($result, true);
    }
}


try {
    $customers1st = new Customers1st('<token>');

    /* increase stock,
     * If you do not specify the cost price, we use the current average stock price */
    $transaction = [
        'productid' => '<id>',
        'addtostock' => 5,
        'costpriceofaddeditems' => 100,
    ];
    $customers1st->call('POST', '/stocktransactions', ['content' => $transaction]);

    /* decrease stock, costpriceofaddeditems must not be specified */
    $transaction = [
        'productid' => '<id>',
        'addtostock' => -2,
    ];
    $customers1st->call('POST', '/stocktransactions', ['content' => $transaction]);

    /* update a product */
    $product = $customers1st->call('GET', '/products/<id>')['content'];
    $product['title'] = 'New title';
    $product = $customers1st->call('PUT', '/products/<id>', ['content' => $product]);
} catch(Exception $e) {
    echo($e->err['result']);
}

Fetch updated ressources since given timestamp

A common operation you might want to do is fetch all the products from Customers 1st that where changed since the last time you "checked". The way to do this is to use the updated_after query parameter on the products search endpoint. So lets say for example today's date is the 20. of December and you want every product that was changed since the 19. of December. You would make a request like so:

curl \
  -H 'Content-Type: application/json' \
  https://app.deltateq.com/api/products?updated_after=2023-12-19 00:00:00

This would then return a list of products updated after that date. If the amount of products changed are greater than 50 you would still have to paginate through the list using the paginationStart query paramater like usual.

Stock changes

To achive the same for stocktransaction, the request is almost the same as the example above. Here you use the search stockstransactions endpoint with the query paramenter committed_after. So to get all stock transactions after the 19. of December 2023 you would make a request like so:

curl \
  -H 'Content-Type: application/json' \
  https://app.deltateq.com/api/stocktransactions?committed_after=2023-12-19 00:00:00

Pagination can be done via GET parameters paginationStart and paginationPageLength. The pagination is based on element count.
For example, if you want to access the third page of a pagination with 10 items per page use:

?pagiationStart=20&paginationPageLength=10

For all endpoints paginationPageLength is limited to 250. We are currently working on implementing this limit.

The Customers 1st API supports REST Hooks. This allows you to subscribe to events in our system and get notified via a callback url immediately.

To listen for events,

POST /api/hooks with JSON object

{
    "event": "<event>",
    "url": "<url>"
}

This call returns a unique id for that subscription that is needed to manage the subscription.

When the event triggers in our system, we will POST to the specified url with a relevant payload, for instance the product that was created in case of product.created.

Events can be:

inventorycount.created
inventorycount.updated
inventorycount.deleted
product.created
product.updated
product.deleted
supplier.updated
supplier.deleted
supplier.created
pospayment.created
posbalance.created
customer.created
customer.updated
customer.deleted
shoppinglistorder.created
shoppinglistorder.deleted
shoppinglistitem.created
shoppinglistitem.updated
shoppinglistitem.deleted
customertags.created
customertags.updated
customertags.deleted
customerarticle.created
customerarticle.updated
customerarticle.deleted
taskmaterial.created
taskmaterial.updated
taskmaterial.deleted
task.created
task.updated
task.deleted
taskcomment.created
taskcomment.updated
taskcomment.deleted
servicesubscription.created
servicesubscription.deleted
stocktransaction.committed
giftcard.created
giftcard.updated
giftcard.deleted
loyaltybalance.updated

To unsubscribe DELETE /api/hooks/{id} You can also unsubscribe by returning status code 410 (Gone) when your callback url is notified.

REST hooks can also be specified via the app under Settings -> API.

If the request returns 408 (Request Timeout), 429 (Too Many Requests) or 5xx (Server Error) the server will retry a maximum of 3 times, with an increasing interval of 30, 60, and finally 120 minutes, after which the hook will be considered failed.

When using the API to make changes to your store, for instance create products, these interactions will trigger events like product.created just like using the app would.

In some cases this behaviour is not desired since it can create infinite loops between services, for instance stock sync between Customers 1st and e-conomic.

To avoid this, interact with the API with the following header X-Suppress-Hooks: The content of the header doesn't matter and is ignored.

All resthooks from Customers 1st are signed using a store's signing secret. The signature is set in a header called X-C1st-Webhook-Signature. The secret can be changed under api settings or set using the api by changing the store config resthook_signing_secret

To validate a resthook, you need to calculate the HMAC of the request payload using the signing secret.

Here is an example in Laravel/PHP

    public function validateResthook(\Illuminate\Http\Request $request)
    {
        $signature = $request->header('X-C1st-Webhook-Signature');

        $secret = "resthook_super_secret_1337";

        $payload = $request->getContent();
        $calculated_hmac = base64_encode(hash_hmac('sha256', $payload, $secret, true));

        if ($signature != $calculated_hmac) {
            abort(401, 'Webhook failed signature check');
        }
    }