Skip to main content

Checkout Management API

This documentation describes the snabble API endpoints related to the management and simple access of checkouts. These endpoints are available on the api subdomain. See General API access for general information about api access.

Info operation

Process operations

Data Model

Content Types

Content-Type : application/json

The payload is a JSON document of the specified type.

Data Model

Cart

ParameterTypeDescription
clientIDstringThe ID of the client/device
appUserIDstringThe ID of the appUser
sessionstringCurrent session ID
shopIDstringID of the shop
itemsCartItem[]Array of cart items
customerobjectContains further information to the customer, e.g.loyaltyCard number

A cart item contains following information:

ParameterTypeDefaultDescription
idstringnullID of the item
skustringSKU of the product
amountintNumber of products
weightintnullWeight of product in case of a weighable (a not packaged) product
weightUnitstringnullUnit of the weight
unitsintnullNumber of units in a package in case of bundle or piece product
priceintnullPrice of the product in case of an encoded price
scannedCodestringScanned code

Example:

{
"session": "d06474fa-1584-11e8-b642-0ed5f89f718b",
"clientID": "772fdd23-0161-4e3e-85d0-af2a52fbe3f7",
"appUserID": "d7b5a85a-4186-466e-99ee-414fe93951f3",
"shopID": "shop-01",
"items": [
{"sku": "1", "amount": 2, "scannedCode": "0000000000001" },
{"sku": "2", "amount": 1, "weight": 102, "weightUnit": "g", "scannedCode": "0000000000002"},
{"sku": "3", "amount": 42, "scannedCode": "0000000000003"},
{"sku": "4", "amount": 1, "units": 6, "scannedCode": "000000000004"},
{"sku": "5", "amount": 1, "price": 129, "scannedCode": "0000000000005"},
],
"customer": {
"loyaltyCard": "..."
}
}

Checkout Info

A signed document with mandatory price calculation and available payment methods.

Signed Checkout Info

ParameterTypeDefaultDescription
checkoutInfoCheckoutInfoActual Checkout Info
signaturestringSignature of the checkoutInfo object

Checkout Info

ParameterTypeDefaultDescription
sessionstringIdentifier of the session
clientIDstringThe ID of the client/device
appUserIDstringThe ID of the appUser
shopIDstringIdentifier of the shop
shopShopInformationShop details
customerCustomerCustomer details
createdAtdateCreation date of the checkout info (RFC3339 Datetime formated)
availableMethodsstring[]List of payment methods available for this checkout
lineItemsLineItem[]List of the line items
pricePricePrice of the checkout
currencystringCurrency of the project

Shop Information

The Shop Information captures the details of the essential for the checkout.

ParameterTypeDefaultDescription
externalIdstringAn identifier provided by external sources
namestringThe name of the shop
emailstringEmail address
phonestringPhone number
streetstringStreet and number
zipstringPostal code
citystringCity
statestringState
countrystringCountry

Line Item

A line item normaly represents a certain amount of a product. But it can also used for additional items that are indivisble from the bought product like a deposit. Further, it can be used to represent promotions like a general discount. The line items are hence typed to distinguish these cases. Also it can refer to another one through the refersTo property.

ParameterTypeDefaultDescription
idstringIdentifier of the line item
typestringdefaultType of the line item (default, deposit, promotion)
refersTostringnullLine item that is related to this one (ie. if the line item represents a deposit the id of the line item wich requires it)
skustringSKU of the product
amountintNumber of products / packages
weightint0Weight purchased
weightUnitstringUnit of the weight
referenceUnitstringReference unit for weighable item, Details: Product API: weighable products
unitsint0Number of units in a package in case of bundle or piece product
priceintPrice of the product for single unit, piece, weightUnit, etc
priceOriginstringOrigin of the price (master price from the products list, client the price was provided by the client)
totalPriceintTotal price of the line item
namestringName of the product
taxRatestringTax rate as string encoded decimal
scannedCodestringScanned code
saleRestrictionstringRestriction for product e.g. min age

Example:

{
"links": {
"checkoutProcess": {
"href": "/demo/checkout/process"
}
},
"checkoutInfo" : {
"price" : {
"tax" : {
"19" : 7673
},
"taxNet" : {
"19" : 40382
},
"taxPre" : {
"19" : 48055
},
"netPrice" : 40382,
"price" : 48055
},
"availableMethods" : [
"cash",
"girocard",
"sepa",
"visa",
"mastercard"
],
"clientID": "772fdd23-0161-4e3e-85d0-af2a52fbe3f7",
"appUserID": "d7b5a85a-4186-466e-99ee-414fe93951f3",
"shopID" : "shop-01",
"shop": {
"externalID": "shop-1234",
"street": "Shop Street 3",
"zip": "12345",
"state": "Shop State",
"country": "Some Country",
"city": "Some City",
"phone": "+4912342356",
"email": "shop@someshop.de",
"name": "Some Shop"
},
"lineItems" : [
{
"id": "e25bc1ee-5233-11e9-9e12-68f7286a148f",
"type": "default",
"totalPrice" : 798,
"amount" : 2,
"name" : "Kugelschreiber tarent rot",
"price" : 399,
"taxRate" : "19",
"sku" : "1",
"scannedCode": "0000000000001",
"saleRestriction": "min_age_18"
},
{
"id": "ecac5c4e-5233-11e9-b17e-68f7286a148f",
"type": "default",
"price" : 1099,
"name" : "tarent logo-Cap grau",
"totalPrice" : 1099,
"amount" : 1,
"taxRate" : "19",
"sku" : "2",
"scannedCode": "0000000000002",
"saleRestriction": ""
},
{
"id": "f660bac8-5233-11e9-a689-68f7286a148f",
"type": "default",
"amount" : 42,
"totalPrice" : 46158,
"name" : "tarent logo-Cap rot",
"price" : 1099,
"sku" : "3",
"taxRate" : "19",
"scannedCode": "0000000000003"
}
],
"currency": "EUR",
"project" : "demo",
"session" : "d06474fa-1584-11e8-b642-0ed5f89f718b",
"clientID": "app-id-12345",
"createdAt": "2018-06-19T09:59:29.245Z",
"customer": {
"loyaltyCard": "..."
}
},
"signature" : "Dynit3mnsBnM8eA9.."
}

Create Checkout Process Request

Example:

{
"signedCheckoutInfo" : { .. signedCheckoutInfo .. },
"paymentMethod": "sepa",
"paymentInformation": { .. some information depending on payment system .. }
}

Checkout Process

Process attributes:

ParameterTypeDefaultDescription
supervisorApprovalbool/nilnilApproval by the checkout supervisor (nil=pending, true=granted, false=rejected)
paymentApprovalbool/nilnilApproval by the payment process (nil=pending, true=granted, false=rejected)
abortedboolfalseFlag, if the process was aborted by the user
checkoutInfoCheckoutInfoThe full Checkout Info object (that was provided in the creation of the process)
pricingpricingThe Pricing information of the checkout
paymentMethodstringA valid payment method
paymentStatestringpendingThe Status of the associated payment process
paymentInformationobjectnilPayment dependent additional information, i.e. a code to present to the user
paymentResultobjectnilInformation from payment system, i.e. transaction id, state
modifiedboolfalseFlag, if the process was modified by the checkout supervisor
createdAtdateCreation date of the process (RFC3339 Datetime formated )
finalizedAtdateThe time the process was finalized, i.e. the time it was paid
processedOfflineboolfalseFlag, if the customer was offline while creating the process
clientIDstringThe ID of the client/device
appUserIDstringThe ID of the appUser

Example:

{
"links": {
"self": {"href": "/demo/checkout/process/f42a5718-1621-11e8-b642-0ed5f89f718b"},
"approval": {"href": "/demo/checkout/process/f42a5718-1621-11e8-b642-0ed5f89f718b/approval"},
"payment": {"href": "/demo/checkout/payment"}
},
"supervisorApproval" : null,
"paymentApproval" : null,
"aborted" : false,
"checkoutInfo" : { .. checkoutInfo .. },
"paymentMethod" : "cash",
"pricing": { .. pricing .. },
"modified" : false,
"processedOffline": false,
"clientID": "772fdd23-0161-4e3e-85d0-af2a52fbe3f7",
"appUserID": "d7b5a85a-4186-466e-99ee-414fe93951f3"
}

Payment State

Represents the state of the payment process associated with the Checkout Process.

Possible values are:

  • pending (initial state): The payment is pending
  • processing: A payment system is currently processing the process
  • transferred (terminal state): The process was transferred to a payment system. But the outcome of the processing will not be communicated to the process.
  • successful (terminal state)
  • failed (terminal state)

Payment Result

The structure of the payment result depends on the payment method and the provider used. In general three cases have to be considered: Online Payment Credit Card, Online SEPA Direct Debit and Payment Terminal. In this cases the system assures that at least the described fields are present.

Payment Result: Payment Credit Card

The payment was processed online using a Credit Card, ie. Visa, Mastercard.

ParameterTypeDescription
transactionTimestringTransation time as unix timestamp in time zone UTC
panstringAnnonymized Primary Account
processorApprovalCodestringApproval code of the transaction
processorReferenceNumberstringReference number of the transaction

Payment Result: SEPA Direct Debit

The payment was processed online using a Direct Debit transaction

ParameterTypeDescription
transactionTimestringTransation time as unix timestamp in time zone UTC
mandateReferencestringSEPA Mandate reference
processorApprovalCodestringApproval code of the transaction
processorReferenceNumberstringReference number of the transaction

Payment Result: Payment Terminal

The payment was processed using a payment terminal with the ZVT-Protocol.

ParameterTypeDescription
timestringTransation time as encoded as RFC3339
aidstringAuthorization Code
panstringPrimary Account Number
paymentTypestringZVT-Payment Type

Checkout Process List

Example:

{
"processes" : [
{
"links": {
"self": {"href": "/demo/checkout/process/f42a5718-1621-11e8-b642-0ed5f89f718b"},
"approval": {"href": "/demo/checkout/process/f42a5718-1621-11e8-b642-0ed5f89f718b/approval"},
"payment": {"href": "/demo/checkout/payment"}
},
"supervisorApproval" : null,
"paymentApproval" : null,
"aborted" : false,
"checkoutInfo" : { .. checkoutInfo .. },
"paymentMethod" : "cash",
"paymentState": "pending",
"pricing": { .. pricing .. },
"modified" : false
},
{
"links": {
"self": {"href": "/demo/checkout/process/f42a5718-1621-11e8-b642-xxd5f89f718b"},
"approval": {"href": "/demo/checkout/process/f42a5718-1621-11e8-b642-xxd5f89f718b/approval"},
"payment": {"href": "/demo/checkout/payment"}
},
"supervisorApproval" : null,
"paymentApproval" : null,
"aborted" : false,
"checkoutInfo" : { .. checkoutInfo .. },
"paymentMethod" : "cash",
"paymentState": "pending",
"pricing": { .. pricing .. },
"modified" : false
}
]
}

Pricing

Price information.

ParameterTypeDescription
taxObjectMap of tax rates (as string encoded decimals) to the portion of the price that was taxed with this rate
taxNetObjectMap of tax rates (as string encoded decimals) to the portion of the net price that was taxed with this rate
taxPreObjectMap of tax rates (as string encoded decimals) sums all pre tax prices of products with this rate up
lineItemsLineItem[]Line items of the order. For details see Checkout API: Line Item
{
"price" : {
"tax" : {
"19" : 7673
},
"taxNet" : {
"19" : 40382
},
"taxPre" : {
"19" : 48055
},
"netPrice" : 40382,
"price" : 48055
},
"lineItems" : [
{
"totalPrice" : 798,
"amount" : 2,
"name" : "Kugelschreiber tarent rot",
"price" : 399,
"taxRate" : 19,
"sku" : "1",
"scannedCode": "0000000000001"
},
{
"price" : 1099,
"name" : "tarent logo-Cap grau",
"totalPrice" : 1099,
"amount" : 1,
"taxRate" : 19,
"sku" : "2",
"scannedCode": "0000000000002"
}
]
}

Checkout Approval

Possible Types:

  • supervisor

Example:

{"type": "supervisor"}

Abort Request

Example:

{"aborted": true}

Update Pricing Request

Updates the pricing of the checkout process.

Example:

{
"pricing" : {
"lineItems" : [
{
"sku" : "1",
"amount" : 1,
"taxRate" : 19,
"price" : 399,
"totalPrice" : 399,
"name" : "Kugelschreiber tarent rot"
}
],
"price" : {
"price" : 399
}
}
}

Set Payment State Request

Valid values are:

  • pending
  • processing
  • successful
  • failed

Example:

{
"paymentState" : "successful"
}

Create Checkout Info

POST /{project}/checkout/info

Creates a Checkout Info document with mandatory price calculation and available payment methods. This document can be used to show the real price to the user and it can be used to start a Checkout Process as input of Create Checkout Process.

Required permissions : productsRead

Request

Content-Type : application/json

Data : Cart.

Success Response 200 OK

Content-Type : application/json

Data : Checkout Info.

Possible structured errors

More information on structured errors in General API

TypeDescription
shop_not_foundshop for provided shopID does not exists
bad_shop_idThe provided shopID is either not present or invalid
no_available_methodNo payment method is available
invalid_cart_itemOne or multiple cart items are invalid. The api returns an array of lineItemErrors in details

LineItemError

A LineItemError gives further information on line item which caused an error.

PropertyTypeDescription
skustringSKU of the affected product
typestringline item error types
messagestringerror message

Possible line item error types:

TypeDescription
sale_stopproduct is affected by a sale stop
product_not_foundproduct with the given SKU does not exist

Example:

{
"type": "invalid_cart_item",
"details": [
{
"sku": "some-sku",
"type": "sale_stop",
"message": "product is excluded from sale"
},
{
"sku": "some-other-sku",
"type": "product_not_found",
"message": "product not found"
}
]
}

Create Checkout Process

POST /{project}/checkout/process

Initiate a Checkout Process.

Required permissions : productsRead and a Checkout Info

Request

Content-Type : application/json

Data : Create Checkout Process Request.

Success Response 201 Created

Location : Get Checkout Process

Content-Type : application/json

Data : Checkout Process


Get Checkout Process

GET /{project}/checkout/process/{id}

Get the state of a Checkout Process.

Required permissions : checkoutRead for the checkout process

Success Response 200 OK

Content-Type : application/json

Data : Checkout Process


List Checkout Processes

GET /{project}/checkout/process?shop=shopID

List all available Checkout Processes for a shop.

Parameter : shop (string) - the shop id

Required permissions : supervisor

Success Response 200 OK

Content-Type : application/json

Data : Checkout Process List


Modify Checkout Process

PATCH /{project}/checkout/process/{id}

Modify a Checkout Process.

Aborting the Checkout Process

Required permissions : productsRead and the id of a Checkout Process

Abort Request

Mark a checkout process as aborted.

Content-Type : application/json

Data : Abort Request.

Success Response 200 OK

Content-Type : application/json

Data : Checkout Process

Set Payment State of the Checkout Process

Required permissions : setPaymentState and the id of a Checkout Process

Set Payment State Request

Mark a checkout process as successful, failed or in process.

Content-Type : application/json

Data : Set Payment State Request.

Success Response 200 OK

Content-Type : application/json

Data : Checkout Process

Update the Pricing of the Checkout Process

Required permissions : updatePricingCheckoutProcess and the id of a Checkout Process

Update Pricing Request

Update the pricing of the CheckoutProcess.

The provided pricing might be incomplete. This means whole line items or parts of them (like taxRate) might be missing. Also the netPrice and the tax properties are optional. This leads to the generation of incomplete orders. In this case downstream processes like the generation of receipts might not be possible or can't generate the correct results.

Content-Type : application/json

Data : Update Pricing Request.

Success Response 200 OK

Content-Type : application/json

Data : Checkout Process


Create Checkout Process Approval

POST /{project}/checkout/process/{id}/approval

Create an approval for a Checkout Process.

Request

Content-Type : application/json

Data : Create Checkout Approval Request.

Success Response 201 Created

Content-Type : application/json

Data : Checkout Approval.