Bill Endpoints

This page covers the routes that send receipts to anybill and how a receipt is linked to a consumer. The structure of the receipt payload itself is described in the Bill Data Model, and worked examples for discounts, returns and custom sections in Bill Examples.

Endpoints

The receipt controller offers two routes:

• GET /v3/bill/url: Get QR code in advance for a receipt.
  • GET Staging Swagger | Production Swagger
• POST /v3/bill: Send receipt to anybill.
  • POST Staging Swagger | Production Swagger
• DELETE /v3/bill/{billId}: Cancel a receipt based on the billId.
  • DELETE Staging Swagger | Production Swagger
• POST /v3/bill/{billId}/printed: Adds a printed timestamp to the receipt.
  • POST Staging Swagger | Production Swagger

Detailed Endpoint Description

Staging Environment: SwaggerUI
Production Environment: SwaggerUI

Request

The store ID must be sent in the body of the request. The BuyerInformation are optional and not necessary.

POST /v3/bill

{
  "storeId": "3QT1su7Wtl",
  ... // see Swagger
}

Response

The response returns a json object with an url from which the QR code can be generated.

{
   "type": "url",
   "url": "url to receipt",
   "billId": "Id of the receipt"
}

The POST /v3/bill-route can be used to add following types of receipts.

• Anonymous Receipts:
  • This is the case if the POS not provide a user identifier as a value in userIdentification.externalId - e.g. via QR code scan of a loyalty card of the consumer.
    Example:

    { "url": "https://getmy.anybill.de/{billId}" }

• User Receipts:
  • This is the case if the POS provides a value in userIdentification.externalId, e.g. the loyalty/crm identifier scanned at the POS. Here, anybill can use this information to e.g. assign the receipt automatically to the consumer's app account, use it for analytics, insights and actions in Purchase Intelligence or many other use cases.

If the user identification object or all its property are null, the receipt will be treated as anonymous.

Response objects

The /v3/bill endpoint returns different response objects.

1. When no userIdentification.externalId has been provided in the request:

// UrlBillResponseDto
{
   "type": "url",
   "url": "url to receipt",
   "billId": "Id of the receipt"
}

---

2. When a value in userIdentification.externalId has been provided in the request and the receipt was matched with an external user (e.g. receipt was assigned to a user account to make it visible in the merchant's app) - without requiring a QR code.:

// ExternalIdResponseDto
{
   "type": "externalId",
   "isAssigned": true,
   "billId": "Id of the receipt"
}

---

💡 isAssigned will always be true if type is externalId. If userIdentification.externalId has been defined, and no match could be made, the response is of type url.

User identification

If a receipt with a link to a known consumer should be added, the property userIdentification.externalId must be set with the identifier value.

• The externalId of the consumer is an identifier from a marchant's system like CRM (customer number), Loyalty. The maximum length is 256 characters.

Transparent user creation via externalId

Historically, anybill required merchants to first create an anybill user via the Partner Platform API, in order to link an externalId-Identifier to it later.

After popular demand, this requirement has been removed:
If the provided userIdentification.externalId is not yet known to anybill, anybill internally creates an anonymous anybill user automatically and the receipt is assigned to it.
No pre-registration or creation of an internal anybill user is required anymore.
On subsequent receipts with the same userIdentification.externalId value, the existing user is reused.
The same userIdentification.externalId can later be passed to the Partner Platform API token endpoint to obtain an SDK token for that user.

WARNING

The "Transparent user creation via externalId" - flow has to be manually enabled per merchant on the anybill side. If it is relevant for your integration, please contact dev@anybill.de or your anybill contact person.

Deprecated useridentification fields

The previously available userIdentification.userId (anybill user id) and userIdentification.loyaltyCardBarcode fields are deprecated and will be removed in a future revision. Use userIdentification.externalId for all new integrations.

Self-generated Receipt Id

The Vendor API optionally offers the possibility that the POS system generates a Receipt ID (UUID) independently, prior to sending the receipt data.

WARNING

The "Self-generated Receipt Id" - feature has to be manually enabled per merchant on the anybill side. If it is relevant for your integration, please contact dev@anybill.de or your anybill contact person.

If a self-generated Receipt Id already exists

If the self-generated receipt UUID already exists in the anybill system, a HTTP 400 error is returned with the following error message:

{
    "errors": [
        {
            "message": "Bill with Id 5e952ea6-167d-4001-95d9-a759204c2943 already exists",
            "code": "billId-alreadyExists",
            "extensions": {}
        }
    ],
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more business logic errors occurred.",
    "status": 400,
    "detail": null,
    "instance": "/v3/bill",
    "extensions": {
        "traceId": "00-62c5389aa64965de30dcf0c4313e60c1-cc61c9200d008c1b-00"
    }
}

Cancelling a receipt

A receipt is cancelled with DELETE /v3/bill/{billId}. The billId is part of the request path.

TIP

The response returns status code 204 if the receipt could be cancelled, or 404 if the receipt could not be found.

Required Fields

These fields are validated against the OpenAPI schema; the business rules described in the Bill Data Model apply on top of them. Fields listed as required once the surrounding object is sent belong to an optional part of the payload — omitting that part entirely is fine, including it makes the listed fields mandatory.

Generated from the production OpenAPI specification (API version 3.0) on 3 September 2026.

POST /v3/bill/url

Request body: RegisterBillIdDto

Always required

Field	Type	Description
storeId	string, non-empty	Id of the Store that issues the bill in the future

POST /v3/bill

Request body: AddBillDto

Always required

Field	Type	Description
storeId	string, 1–36 chars	The id of the store of the vendor in which the transaction was done.
bill	BillDto	The definition of a bill based on the version '1.0.0' of the DFKA.
bill.head	HeadDto	Head data of the bill.
bill.head.date	string (date-time)	Date of invoice.
bill.data	DataDto	Bill data.
bill.data.currency	string, exactly 3 chars	This field defines the currency to be used for all document data if no other currency is explicitly specified. Must be a valid ISO 4217 currency code…
bill.data.fullAmountInclVat	number (double)	The total gross amount of the receipt. A precision of 2 decimal places is used.
bill.security	SecurityDto	Data to secure the receipt via TSE.

Required once the surrounding optional object is sent

Object	Position in the request body	Required fields
BillDiscountDto	bill.data.extension:anybill.discounts[]	id, type
DefaultLineDto	bill.data.lines[]	text, item, extension:anybill
TextLineDto	bill.data.lines[]	text, extension:anybill
DiscountLineDto	bill.data.lines[]	text, extension:anybill
KeyValueLineDto	bill.data.lines[]	type
AnybillDefaultLineExtensionDto	bill.data.lines[].extension:anybill	sequenceNumber
AnybillTextLineExtensionDto	bill.data.lines[].extension:anybill	sequenceNumber
AnybillDiscountLineExtensionDto	bill.data.lines[].extension:anybill	sequenceNumber
AnybillCustomLineExtensionDto	bill.data.lines[].extension:anybill	sequenceNumber
ItemDto	bill.data.lines[].item	number, quantity, pricePerUnit
LineVatAmountDto	bill.data.lines[].vatAmounts[]	percentage, inclVat, exclVat, vat
PaymentTypeInformationDto	bill.data.paymentTypes[]	name, amount, extension:anybill
AnybillPaymentTypeInformationExtensionDto	bill.data.paymentTypes[].extension:anybill	type
DataVatAmountDto	bill.data.vatAmounts[]	percentage, inclVat, exclVat, vat
SellerDto	bill.head.seller	name
SellerAddressDto	bill.head.seller.address	street, postalCode, city
BasicAdditionalReceiptDto	bill.misc.additionalReceipts[]	type, contentType
VendorAdditionalReceiptDto	bill.misc.additionalReceipts[]	type, contentType
AfterSalesCouponDto	bill.misc.extension:anybill.afterSalesCoupons[]	title, codeType, code
FranceSpecificAttributesDto	bill.misc.extension:anybill.countrySpecificAttributes	type
LoyaltyCouponingInformationDto	bill.misc.extension:anybill.couponingInformation	type
CustomSectionDto	bill.misc.extension:anybill.customSections[]	position, section, data
TseDto	bill.security.fiscalization	type
SwedenFiscalizationDto	bill.security.fiscalization	type
RksvDto	bill.security.fiscalization	type
SecurityInformationDto	bill.security.fiscalization	type
BoiTvaDto	bill.security.fiscalization	type
TBaiDto	bill.security.fiscalization	type
PortugalFiscalizationDto	bill.security.fiscalization	type
AdditionalRksvDataDto	bill.security.fiscalization.additionalData	displayName, value
AdditionalBoiTvaDataTextDto	bill.security.fiscalization.additionalData[]	type
AdditionalBoiTvaDataKeyValueDto	bill.security.fiscalization.additionalData[]	type
SecurityInformationDataDto	bill.security.fiscalization.data[]	displayed, displayName, value
AdditionalTseDataDto	bill.security.fiscalization.extension:anybill.additionalTseData	displayName, value

DELETE /v3/bill/

Name	Location	Type	Description
billId	path parameter	string (uuid)	The bills id to be deleted.

POST /v3/bill/{billId}/printed

Name	Location	Type	Description
billId	path parameter	string (uuid)	The bill id where the timestamp to add.