Idempotency

    Our API supports idempotency for safely retrying requests without accidentally performing the same operation twice. When creating or updating an object (order, template), use an idempotency key. If a connection error then occurs, you can safely retry the request without risking creating a second object (order, template) or performing the update twice.

    With our idempotency function you can easily prevent an order from being sent twice to the same address or the same person (within 24 hours).

    Deduplication of your file is also no longer necessary if you use idempotency keys.

    Concrete usage examples:

    • Use the customer ID to generate an idempotency key. If our system receives two orders with the same idempotency key within 24 hours, only 1 order will be executed (the first).

    • Use zip code and house number to generate an idempotency key. If our system receives two orders with the same key, only the first order will be executed.

    How it works:

    To execute an idempotent request, give an additional Idempotency-Key: <key> header to the request.

    The idempotency at Print.one works by storing the resulting status code and header of the first request for a given idempotent key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result, including 500 errors.

    An idempotency key is a unique value generated by the client that the server uses to recognise subsequent new attempts of the same request. How you create unique keys is up to you, but we recommend using V4 UUIDs, or another random string with sufficient entropy to avoid collisions. idempotency keys can be up to 255 characters long.

    Keys are automatically deleted from the system after they are 24 hours old. The idempotency layer compares incoming parameters with those of the original request and returns an error if they are not the same. This means that it is not possible to repeat a request with a different body using the same key.

    All POST and PATCH requests accept idempotency keys. Sending idempotent keys in DELETE and GET requests has no effect and should be avoided, as these requests are by definition idempotent.