Fulfilment extras
For Picqer Fulfilment users, it's possible to register extras via the API. Extras are the extra work you do for your fulfilment customers, like adding a handwritten card or stickering products. You register an extra on a picklist, receipt or return, or as general work for a fulfilment customer.
These endpoints are not available for API keys of fulfilment customers.
Extras
Extras are managed in Picqer. Via the API you can retrieve them.
Attributes
| Name | Type | Required | Description |
|---|---|---|---|
| idfulfilment_extra | integer | generated | Unique Picqer reference |
| name | string | read-only | Name of the extra |
| reference | string | read-only | Your own reference of the extra, for example the article code in your invoicing software. Can be null |
| active | boolean | read-only | Only active extras can be registered |
Get all extras
With this call, you will only get the active extras, newest first. Provide the inactive parameter to get the inactive extras.
Filters
You can filter the extras with the following parameters. Add these filters as querystring parameters to the URL.
| Attribute | Description | Example |
|---|---|---|
| inactive | Get the inactive extras instead of the active extras | true |
| reference | Get extras with this reference | EXT-CARD |
| beforeid | Get extras with a smaller idfulfilment_extra than given | 12 |
The offset can be at most 10,000. Use beforeid to get older extras.
Get single extra
Registrations
Every time an extra is done, it is registered on a picklist, receipt or return: the subject of the registration. General work for a fulfilment customer has the fulfilment customer as subject.
You can get and add the registrations of a single picklist, receipt, return or fulfilment customer. These lists include cancelled and removed registrations. Use status=active to only get the registrations that count. Registering an extra via the API always creates a new registration, also if the extra is already registered on the same subject.
Attributes
| Name | Type | Required | Description |
|---|---|---|---|
| idfulfilment_extra_registration | integer | generated | Unique Picqer reference |
| extra | object | generated | The registered extra |
| idfulfilment_customer | integer | generated | Linked to the fulfilment customer of the subject |
| subject_type | string | generated | Type of the subject, one of:
|
| subject | object | generated | The subject of the registration, see Subjects |
| amount | integer | optional | How many times the extra is done, default 1 |
| iduser | integer | read-only | User who registered the extra, null if it was registered via the API |
| status | string | read-only | Status of the registration, one of:
|
| created | datetime | read-only | Date and time of the registration |
| updated | datetime | read-only | Date and time of the last change, also when the registration was cancelled or removed |
Subjects
The content of subject depends on the subject_type. The number of the picklist, receipt or return is stored on the registration, so it is still available if the receipt or return is deleted.
| subject_type | subject |
|---|---|
| picklist | idpicklist and picklistid |
| receipt | idreceipt and receiptid |
| return | idreturn and returnid |
| fulfilment_customer | null |
Cancelled and removed registrations
When a picklist is cancelled, its registrations get the status cancelled. When a registration is removed in Picqer or via the API, it gets the status removed. These registrations stay in the API, so you can see they no longer count. They cannot be changed or removed anymore.
Get all registrations
With this call, you will get the registrations of all fulfilment customers, newest first. Cancelled and removed registrations are included. Use status=active to only get the registrations that count.
Filters
You can filter the registrations with the following parameters. Add these filters as querystring parameters to the URL.
| Attribute | Description | Example |
|---|---|---|
| idfulfilment_customer | Get registrations for this fulfilment customer | 3 |
| idfulfilment_extra | Get registrations of this extra | 14 |
| status | Get registrations with this status: active, cancelled or removed | active |
| created_after | Get registrations created on or after this datetime | 2026-11-01 |
| created_before | Get registrations created before this datetime | 2026-12-01 |
| updated_after | Get registrations changed on or after this datetime | 2026-11-12 09:00:00 |
| beforeid | Get registrations with a smaller idfulfilment_extra_registration than given | 8124 |
The offset can be at most 10,000. Use beforeid to get older registrations.
To get the registrations of a fulfilment customer for November 2026, use idfulfilment_customer=3&status=active&created_after=2026-11-01&created_before=2026-12-01. The datetime of created_before itself is not included, so periods don't overlap.
Keeping your data in sync
Registrations can change after they are created: the amount can be changed, the registration can be removed, or the picklist can be cancelled. To keep your data in sync, request the registrations that changed since your previous sync:
- Save the date and time at which this sync starts, before your first request.
- Get the registrations with updated_after set to the start of your previous sync. Don't use a status filter, so you also get the cancelled and removed registrations. Get all pages of the result.
- Process every registration by its idfulfilment_extra_registration: add or update the registrations with status active, and remove the registrations with status cancelled or removed.
- When the sync is done, use the start you saved in step 1 for your next sync.
Use the start of the sync, not the end. A registration that changes while your sync is running is then included in the next sync.
Renaming an extra does not change its registrations, so get the extras for their current names.
Picklists
Get all registrations of a picklist
Register an extra on a picklist
Provide the idfulfilment_extra of an active extra and optionally an amount between 1 and 99,999. This works the same for receipts, returns and fulfilment customers.
Receipts
Extras can only be registered on v2 receipts.
Get all registrations of a receipt
Register an extra on a receipt
Returns
Get all registrations of a return
Register an extra on a return
Fulfilment customers
General work for a fulfilment customer is registered on the fulfilment customer itself. These calls only return this general work. To get all registrations of a fulfilment customer, use the idfulfilment_customer filter on Get all registrations.
Get all general registrations of a fulfilment customer
Register general work for a fulfilment customer
Update the amount of a registration
You can only change the amount, also after the picklist, receipt or return is completed. To remove a registration, delete it instead of setting the amount to 0.
Optionally provide the previous_amount. The amount will then only be changed if it still has this value.
Delete a registration
The registration gets the status removed.
