Skip to main content

Fulfillment Service API

Fulfillment Object

A Fulfillment Object models a process to deliver products to a customer during a self-checkout.

{
"state": "allocating",
"lineItems": [
{ "id": "7b725216-6887-11ea-b541-68f7286a148f", "sku": "sku-1", "amount": 2, "scannedCode": "..."},
{ "id": "a9389782-6887-11ea-8d3d-68f7286a148f", "sku": "sku-2", "amount": 1, "scannedCode": "..."}
]
"links": {
"fulfillment": { "href": "/a-project/checkout/fulfillments/6697512a-6887-11ea-965e-68f7286a148f" }
}
}
PropertytypeDescription
statestringState of the Fulfillment (see below)
lineItemsLineItem[]Array of Line Items (see below)
linksLinksLink object containing a link to the corresponding fulfillment in the snabble platform
errorError[]Array of Error Objects (see below)

Line Item

PropertytypeDescription
idstringIdentifier of the Line Item
skustringSKU of the product in snabble
amountnumberAmount to be delivered
scannedCodestringCode scanned by the customer

Error Object

PropertytypeDescription
refersTo`stringID of the related line item
typestringType of the error (ie. outOfStock, other have to be defined)
itemsAvailablenumberNumber of available items (in case of low stock)
messagestringAn optional error message

Fulfillment State

StateDescription
openA new fulfillment
allocatingService is currently reserving the products
allocatedProducts are reserved and ready to be delivered
processingDelivering the products
processedSuccessfully delivered the products
abortedClient abort
allocationFailedReservation failed
allocationTimedOutA successful reservation has timed out
failedDelivery failed

Create A New Fulfillment

Initially the snabble platform creates a new entity in the service. The state is allocating and the service should reserve the requested amounts or otherwise respond with an appropriate error.

Request

POST /service

{
"state": "allocating",
"lineItems": [
{ "id": "7b725216-6887-11ea-b541-68f7286a148f", "sku": "sku-1", "amount": 2, "scannedCode": "..."},
{ "id": "a9389782-6887-11ea-8d3d-68f7286a148f", "sku": "sku-2", "amount": 1, "scannedCode": "..."}
]
"links": {
"fulfillment": { "href": "/a-project/checkout/fulfillments/6697512a-6887-11ea-965e-68f7286a148f" }
}
}

Response

201 Created
Location: /service/id/132

{
"id": "6697512a-6887-11ea-965e-68f7286a148f",
"state": "allocated",
"shopID": "123",
"lineItems": [
{ "id": "7b725216-6887-11ea-b541-68f7286a148f", "sku": "sku-1", "amount": 2, "scannedCode": "..."},
{ "id": "a9389782-6887-11ea-8d3d-68f7286a148f", "sku": "sku-2", "amount": 1, "scannedCode": "..."}
]
}

Error Case

In case of an error the service should respond with HTTP Status Code 400 and optionally add an array of error objects to the response.

Error response

400 Bad Request

{
"id": "6697512a-6887-11ea-965e-68f7286a148f",
"state": "allocationFailed",
"shopID": "123",
"lineItems": [
{ "id": "7b725216-6887-11ea-b541-68f7286a148f", "sku": "sku-1", "amount": 2, "scannedCode": "..."},
{ "id": "a9389782-6887-11ea-8d3d-68f7286a148f", "sku": "sku-2", "amount": 1, "scannedCode": "..."}
],
"errors": [
{ "refersTo": "7b725216-6887-11ea-b541-68f7286a148f", "type": "outOfStock", "itemsAvailable": 1, "message": "..." }
]
}

Update A Fulfillment

After the payment is successfully processed by snabble, the platform updates the state of the entity with the state processing. The service triggers the delivery by the vending machine.

PUT /service

{
"state": "processing",
"lineItems": [
{ "id": "7b725216-6887-11ea-b541-68f7286a148f", "sku": "sku-1", "amount": 2, "scannedCode": "..."},
{ "id": "a9389782-6887-11ea-8d3d-68f7286a148f", "sku": "sku-2", "amount": 1, "scannedCode": "..."}
]
"links": {
"fulfillment": { "href": "/a-project/checkout/fulfillments/6697512a-6887-11ea-965e-68f7286a148f" }
}
}

Response

201 Created
Location: /service/id/132

{
"id": "6697512a-6887-11ea-965e-68f7286a148f",
"state": "processed",
"shopID": "123",
"lineItems": [
{ "id": "7b725216-6887-11ea-b541-68f7286a148f", "sku": "sku-1", "amount": 2, "scannedCode": "..."},
{ "id": "a9389782-6887-11ea-8d3d-68f7286a148f", "sku": "sku-2", "amount": 1, "scannedCode": "..."}
]
}

The service might also respond with a fulfillment in state processing. Then it has to update the fulfillment if it finished the delivery.

The service might also update the fulfillment with error states as described above.