Mapping Consignly fulfilments to ERP order lines
If your ERP requires line numbers when recording a fulfilment, use middleware to match quantities fulfilled in Consignly to the appropriate ERP order lines.
Why Consignly does not use order line numbers
Consignly focuses on warehouse operations: telling the warehouse which goods to pick and pack, and in what quantities. ERP line numbers describe how an order is organised in the ERP, but do not necessarily change the work the warehouse needs to perform.
For example, an ERP order might request 30 units of Product A on line 10 and another 50 units on line 20. Where those goods have the same warehouse handling requirements, the warehouse needs to pick 80 units of Product A. Those 80 units might be picked as a single full pallet, with no operational distinction between the 30 units and the 50 units.
Consignly therefore leaves ERP line allocation to the integration, allowing the warehouse to focus on efficient picking and packing. Middleware translates the fulfilled product quantities back into the line allocations required by the ERP, using the stakeholder's agreed rules.
How it works
ERP sales orders and purchase orders often contain numbered product lines. The same product can appear on several lines, each with its own quantity, required date, or priority.
We recommend that your integration retrieves the order lines from the ERP and allocates the quantities fulfilled in Consignly across those lines.
The middleware brings together:
- From the ERP: the order's product lines, line references, and quantities still available to fulfil.
- From Consignly: the products fulfilled and their quantities.
- From the stakeholder: the rule that determines which matching lines to fulfil first.
This approach lets the integration support the ERP's line requirements and the stakeholder's preferred allocation order.
Suggested process
1. Retrieve the ERP order lines
Use the order reference maintained by your integration to find the corresponding order in the ERP.
Retrieve the current lines, including each line's reference, product code, unit of measure, and remaining quantity. Include any other information needed to decide the allocation order, such as required date or priority.
Only include lines that are eligible for fulfilment.
2. Retrieve the fulfilled quantities from Consignly
At the agreed fulfilment milestone, retrieve the products and quantities fulfilled in Consignly.
For picked quantities, use GET /v1/consignments/{consignmentId}. See Fetching picked quantities through the API below for the request and response example.
Prepare a total for each product and unit of measure. These should be the quantities to report to the ERP in this update, excluding any quantities already reported.
Check that product identifiers match between the systems and that quantities use compatible units.
3. Allocate quantities to the ERP lines
For each fulfilled product, find the matching ERP lines and place them in the order agreed with the stakeholder. For example:
- Lowest line number first.
- Earliest required date first.
- Highest business priority first.
Work through the matching lines in that order. Allocate as much as possible to each line without exceeding its remaining quantity, then move to the next line until the fulfilled quantity has been allocated.
Where a product appears on several lines, this is a business allocation rule: the product quantity reported by Consignly does not identify a particular ERP line.
4. Update the ERP
Send the resulting line references and allocated quantities to the ERP using its required fulfilment format.
If a product cannot be matched, or its fulfilled quantity exceeds the available quantity on the matching lines, flag the order for review before submitting the update.
Record the ERP's response so that the integration can confirm the outcome and avoid reporting the same fulfilment twice.
Worked example
An ERP order contains two lines for the same product:
| Line number | Product | Quantity available to fulfil |
|---|---|---|
| 10 | PRODUCT-A | 5 |
| 20 | PRODUCT-A | 8 |
Consignly reports 9 units fulfilled. The stakeholder's rule is to fulfil the lowest line number first.
The middleware allocates 5 units to line 10, then the remaining 4 units to line 20:
| Line number | Product | Quantity allocated |
|---|---|---|
| 10 | PRODUCT-A | 5 |
| 20 | PRODUCT-A | 4 |
The ERP receives two line allocations totalling 9 units. Line 10 is fully fulfilled, and line 20 has 4 units remaining.
Fetching picked quantities through the API
Once you have an access token and the consignment ID, a single request retrieves the consignment details, including its picked product quantities.
Authenticate
See Authentication for steps to obtain an access token with the consignment.read permission.
Find the consignment ID, if needed
If your integration already stores the Consignly consignment ID, skip this lookup. Otherwise, use GET /v1/consignments to find the consignment. For example, look up an exact consignment number:
curl --get "https://api.consignlyhq.com/v1/consignments" \
--data-urlencode "ConsignmentNumbers=CON-2024-001234" \
-H "Authorization: Bearer ACCESS_TOKEN"
Read the matching entry's id from the response's consignments array and confirm that it belongs to the expected client and order. The list endpoint also supports an ExternalId filter if your integration populated that field. Use the returned UUID for the detail request, rather than the displayed consignment number.
Retrieve the picked quantities
Call GET /v1/consignments/{consignmentId}:
curl "https://api.consignlyhq.com/v1/consignments/550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Bearer ACCESS_TOKEN"
The following illustrative response excerpt matches the worked example above. Unrelated fields have been omitted:
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"consignmentNumber": "CON-2024-001234",
"type": 2,
"status": 3,
"products": [
{
"partnerProduct": {
"code": "PRODUCT-A",
"productUnitTypeName": "Each"
},
"quantity": 13,
"pickedQuantity": 9,
"dispatchedQuantity": 0
}
]
}
Here, type: 2 means an outward consignment and status: 3 means ReadyToDispatch. The response shows 13 units requested, 9 picked, and none dispatched. For an integration that reports fulfilment when picking is complete, 9 is the quantity to allocate; the requested quantity of 13 is not the picked quantity. If your integration reports fulfilment at dispatch, use dispatchedQuantity at that milestone instead.
For each entry in products, read:
| Field | Use |
|---|---|
partnerProduct.code |
Match the product to the ERP order lines. |
partnerProduct.productUnitTypeName |
Identify the product's unit of measure and map it to the ERP's unit. |
pickedQuantity |
Obtain the picked quantity for this consignment product entry. |
Sum pickedQuantity across entries for the same product and compatible unit of measure, retaining any attributes needed by your matching rule. This example uses the product-level quantities; do not add item-level quantities to those totals. If the unit is absent, resolve it through your product mapping before allocating.
Assuming none of these 9 units has already been reported, the middleware prepares the following input for the allocation algorithm:
[
{
"productCode": "PRODUCT-A",
"unitOfMeasure": "Each",
"quantity": 9
}
]
With the worked example's allocation rule, this produces 5 units for ERP line 10 and 4 units for ERP line 20.
Illustrative pseudocode
The following example uses lowest line number first. Replace that sorting rule with the stakeholder's preferred order.
The GET request below uses the Consignly endpoint described above. The other functions represent middleware operations to implement for your integration. The inputs are assumed to have valid quantities, matching product identifiers, and compatible units of measure.
# Retrieve the current ERP lines and the quantities to report from Consignly.
erpLines = getEligibleErpOrderLines(orderReference)
consignment = GET /v1/consignments/{consignmentId}
# Use products[].partnerProduct.code, partnerProduct.productUnitTypeName,
# and pickedQuantity to build totals for each product and compatible unit.
pickedProducts = groupPickedQuantities(consignment.products)
fulfilledProducts = excludePreviouslyReportedQuantities(pickedProducts)
# Each fulfilled product has one total per product code and unit of measure.
allocations = []
exceptions = []
for each product in fulfilledProducts:
quantityLeft = product.quantity
matchingLines = erpLines where:
line.productCode == product.productCode
and line.unitOfMeasure == product.unitOfMeasure
and line.remainingQuantity > 0
# Change this rule to suit the stakeholder's requirements.
matchingLines = sortByLineNumberAscending(matchingLines)
for each line in matchingLines:
if quantityLeft == 0:
break
quantityToAllocate = min(
quantityLeft,
line.remainingQuantity
)
allocations.append({
lineReference: line.lineReference,
productCode: product.productCode,
quantity: quantityToAllocate,
unitOfMeasure: product.unitOfMeasure
})
quantityLeft = quantityLeft - quantityToAllocate
line.remainingQuantity = line.remainingQuantity - quantityToAllocate
if quantityLeft > 0:
exceptions.append({
productCode: product.productCode,
unitOfMeasure: product.unitOfMeasure,
unallocatedQuantity: quantityLeft
})
if exceptions is not empty:
flagOrderForReview(orderReference, exceptions)
else if allocations is not empty:
response = submitFulfilmentToErp(orderReference, allocations)
recordOutcome(orderReference, allocations, response)
Implementation notes
- Use remaining quantities. Allocate against what can still be fulfilled on each ERP line, rather than its original ordered quantity.
- Preserve line references. Send the exact identifiers required by the ERP, including any leading zeros or non-numeric characters. Treat sorting separately from the identifier itself.
- Match comparable quantities. Convert units where necessary before allocating. If lines differ by other relevant attributes, include those attributes in the matching rule.
- Handle retries. Ensure the same fulfilment cannot be recorded twice. If an ERP response is missing or unclear, confirm the outcome before sending it again.