Custom-sections (also referred to as custom_elements) are a way to add additional custom content on the receipt. This can be interesting if you want to add a custom message for a specific customer, or alternatively you would like to make the customer aware of for e.g. a summer-sale.
A custom-section can exist in various types:
- TEXT
For more information on TEXT custom-sections and how to use them, check out this article.
- IMAGE
For more information on IMAGE custom-sections and how to use them, check out this article. - QR_CODE
For more information on QR_CODE custom-sections and how to use them, check out this article. - BAR_CODE
For more information on BAR_CODE custom-sections and how to use them, check out this article.
The position of the custom-sections on the receipt is defined via the parameters orientation and position, position references a nearby receipt-section and orientation specifies the relative orientation to the receipt-section.
How to add custom-sections?
Custom-sections can be added for each receipt individually, which is useful for one-time messages. One time custom-sections are added directly in the API call (schema.ekabs_v0.custom_elements) when creating a receipt.
Custom-sections can also be configured as default for a specific time-frame, which comes in handy for generic messages. Default custom-sections can be configured either via the API, or via the UI of the merchant dashboard. We recommend to invite the merchants as collaborators to their organization in the dashboard, so they can configure the custom-sections themselves, and doesn't require intervention from the POS vendor.
How to add a custom-section via API?
- Choose the type of custom-section you want to add: TEXT, IMAGE, QR_CODE, or BAR_CODE
- Create an array of CustomElements objects, whereas the object contains the following data:
{
"alignment": "TEXT",
"content": CustomElementContent | CustomMediaContent,
"orientation": "BEFORE",
"position": "HEAD",
} - content can be either of type CustomElementContent or CustomMediaContent, which is composed of the following data fields:
CustomElementContent {
"data": "string",
"encoding": "CODE128",
"type": "BAR_CODE"
}
CustomMediaContent {
"alt_text": "string",
"label": "string",
"label_alignment": "ABOVE",
"media_id": "00000000-0000-0000-0000-000000000000",
"media_location": "string",
"type": "IMAGE"
} - For more details on how to create custom-sections of type IMAGE, see this article.
- Add the constructed object to the array in schema.ekabs_v0.custom_elements
- Create the receipt with the CreateReceipt endpoint
How to add a custom-section via the dashboard?
1. Select the Sections tab of the Receipt builder in the navigation bar on the left side of the screen.
2. Add a custom-section by clicking on the + icon on the right side of the screen.
3. A custom-section of the selected type will be added in its default location on the receipt.
4. Configure the custom-section in the editor on the right side of the screen. E.g. upload an image.
5. Save and apply the configured changes by clicking on the Apply button in the top-right corner of the screen. Hint: You need to apply the changes twice. Once to apply changes of the custom-section, and another time to set the configured custom-section as default for your receipts.