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.

GET https://example.picqer.com/api/v1/fulfilment/extras
HTTP/1.1 200 OK [ { "idfulfilment_extra": 14, "name": "Handwritten card", "reference": "EXT-CARD", "active": true }, { "idfulfilment_extra": 12, "name": "Sticker per product", "reference": "EXT-STICKER", "active": true } ]
This endpoint uses pagination.

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

GET https://example.picqer.com/api/v1/fulfilment/extras/{idfulfilment_extra}
HTTP/1.1 200 OK { "idfulfilment_extra": 14, "name": "Handwritten card", "reference": "EXT-CARD", "active": true }

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:
  • picklist
  • receipt
  • return
  • fulfilment_customer
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:
  • active
  • cancelled: the picklist was cancelled
  • removed: the registration was removed
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.

GET https://example.picqer.com/api/v1/fulfilment/extras/registrations
HTTP/1.1 200 OK [ { "idfulfilment_extra_registration": 8125, "extra": { "idfulfilment_extra": 12, "name": "Sticker per product", "reference": "EXT-STICKER", "active": true }, "idfulfilment_customer": 3, "subject_type": "fulfilment_customer", "subject": null, "amount": 200, "iduser": null, "status": "active", "created": "2026-11-12 15:02:44", "updated": "2026-11-12 15:02:44" }, { "idfulfilment_extra_registration": 8123, "extra": { "idfulfilment_extra": 14, "name": "Handwritten card", "reference": "EXT-CARD", "active": true }, "idfulfilment_customer": 3, "subject_type": "picklist", "subject": { "idpicklist": 1025698, "picklistid": "P2026-2041" }, "amount": 1, "iduser": 2671, "status": "cancelled", "created": "2026-11-12 09:41:52", "updated": "2026-11-13 08:55:47" } ]
This endpoint uses pagination.

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:

  1. Save the date and time at which this sync starts, before your first request.
  2. 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.
  3. 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.
  4. 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

GET https://example.picqer.com/api/v1/picklists/{idpicklist}/extras
HTTP/1.1 200 OK [ { "idfulfilment_extra_registration": 8124, "extra": { "idfulfilment_extra": 14, "name": "Handwritten card", "reference": "EXT-CARD", "active": true }, "idfulfilment_customer": 3, "subject_type": "picklist", "subject": { "idpicklist": 1025721, "picklistid": "P2026-2056" }, "amount": 1, "iduser": 2671, "status": "active", "created": "2026-11-12 10:23:07", "updated": "2026-11-12 10:23:07" } ]
This endpoint uses pagination.

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.

POST https://example.picqer.com/api/v1/picklists/{idpicklist}/extras
{ "idfulfilment_extra": 14, "amount": 2 }
HTTP/1.1 201 Created { "idfulfilment_extra_registration": 8126, "extra": { "idfulfilment_extra": 14, "name": "Handwritten card", "reference": "EXT-CARD", "active": true }, "idfulfilment_customer": 3, "subject_type": "picklist", "subject": { "idpicklist": 1025721, "picklistid": "P2026-2056" }, "amount": 2, "iduser": null, "status": "active", "created": "2026-11-13 09:12:31", "updated": "2026-11-13 09:12:31" }

Receipts

Extras can only be registered on v2 receipts.

Get all registrations of a receipt

GET https://example.picqer.com/api/v1/receipts/{idreceipt}/extras
This endpoint uses pagination.

Register an extra on a receipt

POST https://example.picqer.com/api/v1/receipts/{idreceipt}/extras
{ "idfulfilment_extra": 12, "amount": 40 }
HTTP/1.1 201 Created { "idfulfilment_extra_registration": 8127, "extra": { "idfulfilment_extra": 12, "name": "Sticker per product", "reference": "EXT-STICKER", "active": true }, "idfulfilment_customer": 3, "subject_type": "receipt", "subject": { "idreceipt": 5521, "receiptid": "RC2026-1071" }, "amount": 40, "iduser": null, "status": "active", "created": "2026-11-13 10:04:12", "updated": "2026-11-13 10:04:12" }

Returns

Get all registrations of a return

GET https://example.picqer.com/api/v1/returns/{idreturn}/extras
This endpoint uses pagination.

Register an extra on a return

POST https://example.picqer.com/api/v1/returns/{idreturn}/extras
{ "idfulfilment_extra": 14 }
HTTP/1.1 201 Created { "idfulfilment_extra_registration": 8128, "extra": { "idfulfilment_extra": 14, "name": "Handwritten card", "reference": "EXT-CARD", "active": true }, "idfulfilment_customer": 3, "subject_type": "return", "subject": { "idreturn": 2210, "returnid": "R2026-1002" }, "amount": 1, "iduser": null, "status": "active", "created": "2026-11-13 10:15:48", "updated": "2026-11-13 10:15:48" }

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

GET https://example.picqer.com/api/v1/fulfilment/customers/{idfulfilment_customer}/extras
This endpoint uses pagination.

Register general work for a fulfilment customer

POST https://example.picqer.com/api/v1/fulfilment/customers/{idfulfilment_customer}/extras
{ "idfulfilment_extra": 12, "amount": 200 }
HTTP/1.1 201 Created { "idfulfilment_extra_registration": 8125, "extra": { "idfulfilment_extra": 12, "name": "Sticker per product", "reference": "EXT-STICKER", "active": true }, "idfulfilment_customer": 3, "subject_type": "fulfilment_customer", "subject": null, "amount": 200, "iduser": null, "status": "active", "created": "2026-11-12 15:02:44", "updated": "2026-11-12 15:02:44" }

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.

PUT https://example.picqer.com/api/v1/fulfilment/extras/registrations/{idfulfilment_extra_registration}
{ "amount": 3, "previous_amount": 2 }
HTTP/1.1 200 OK { "idfulfilment_extra_registration": 8126, "extra": { "idfulfilment_extra": 14, "name": "Handwritten card", "reference": "EXT-CARD", "active": true }, "idfulfilment_customer": 3, "subject_type": "picklist", "subject": { "idpicklist": 1025721, "picklistid": "P2026-2056" }, "amount": 3, "iduser": null, "status": "active", "created": "2026-11-13 09:12:31", "updated": "2026-11-13 09:20:05" }

Delete a registration

The registration gets the status removed.

DELETE https://example.picqer.com/api/v1/fulfilment/extras/registrations/{idfulfilment_extra_registration}
HTTP/1.1 204 No Content