Skip to main content

Receipts

The Receipts V3 API allows you to get all customer receipts generated in customer billing processes by OTTO Market in your name. As long as you have regular access to OTTO Market you can get all receipts up to 4 years old. We cannot guarantee this forever, so it would be good, if you plan to get receipts regularly.

Receipt types​

You will currently find customer receipts of the following receipt types:

  • PURCHASE
    A purchase receipt (also known as an invoice) records the prices charged to the customer at the time of sale, taking into account any instant discounts. The receipt contains information per order, partner and shipment. It is generated when items are shipped to the customer, so there may be more than one receipt per order. Shipping costs are charged only once per partner and per order, and are billed with first purchase receipt of this partner order. Surcharges imposed by payment provider on the customer for using special payment conditions are not included in the OTTO Market receipts.
  • REFUND
    We distinguish between different types of reimbursement documents. A refund receipt documents a credit note issued to a customer for a refund. This document is currently created when returns are accepted. In very rare cases, refund receipts may also be created during the cancellation process to reimburse shipping costs for full returns. Previous partial refunds will be taken into account.
  • PARTIAL_REFUND
    We distinguish different types of reimbursement documents. A partial refund receipt documents a credit note issued to a customer without return. As a partner, you might offer a customer a partial refund if there is a legitimate complaint to avoid a return.

Representation of receipts​

Customer receipts are provided in various formats. You decide which formats best support your processes. The following formats are available:

  • PDF document
    Customer receipts in PDF format are graphically enhanced and contain some details in addition to the raw invoice data some details you can only find on PDF documents, like:
    • Company logo of OTTO (as operator of OTTO Market)
    • Company details of financial service partners
    • Contact details of OTTO (as relation center operator for customer inquiries and complaints) Dates on receipts in PDF format are always printed in format DD.MM.YYYY in German time zone(CET/CEST)
  • JSON format
    Customer receipts in JSON format are presented in a structured easily readable technical format. It's particular suitable for you, if you want to use the data in your own technical applications.
    In addition to billing information, the JSON format provides you with further information that can help you control or simplify your processes.

    Rough class diagram of representation in JSON format
    ⚠ This class diagram only shows the main objects of general structure.
    Receipts Response Class Diagram

Fetching Receipts​

A single receipt can be fetched individually by receiptNumber or as a list by using different filter criteria. When products are shipped, PURCHASE receipts(invoices) are generated. Before this happens, you will not find any customer receipts on OTTO Market. When products are returned or refunded, REFUND receipts are generated. You have the possibility to grant price reduction to avoid refunds e.g. when there are customer complaints. If a subsequent discount is triggered a PARTIAL_REFUND is generated.

Common Use Cases​

Receipts in JSON format are not visible for customers. To fetch a PDF document you need the receiptNumber first. There are different ways you can get it.

Fetch all purchase receipts for a special order​

When products are shipped, purchase receipts(invoices) are created. This could take even in happy path some minutes because on OTTO Market we try to consolidate invoices from different shipments for the customers. As long as no purchase receipt is created, you will not find any customer receipts on OTTO Market. This is how you can get receipts of any receiptType by salesOrderId.

Here an example for receipt type PURCHASE

GET v3/receipts?receiptTypes=PURCHASE&salesOrderId=82f3e02f-2f56-448d-8f3b-d42f5a475119

If there is a next link follow it until there are no new receipts. To start at a certain date use from

GET v3/receipts?receiptTypes=PURCHASE&salesOrderId=82f3e02f-2f56-448d-8f3b-d42f5a475119&from=2022-08-01
Fetch all partial refund receipts for a special order​

Partial refund receipts are generated in after sale, eg. to avoid returns by granting a subsequent price reduction when customers have complaints. If there are any receipts of this type, the request from above will look like this.

GET /v3/receipts?receiptTypes=PARTIAL_REFUND&salesOrderId=82f3e02f-2f56-448d-8f3b-d42f5a475119
Fetch all refund receipt for a special order​

Refund receipt get generated, when e.g. products are refunded. If there are any receipts of this type, the request from above will look like this.

GET /v3/receipts?receiptTypes=REFUND&salesOrderId=82f3e02f-2f56-448d-8f3b-d42f5a4751191
Fetch receipts of different types together​

For sure, you can also fetch receipts of more than one receipt type at the same time by extending the array of receiptTypes. This is how it could look like

GET v3/receipts?receiptTypes=PURCHASE,REFUND&salesOrderId=82f3e02f-2f56-448d-8f3b-d42f5a475119&from=2022-08-01
Fetch all receipts generated in a month​

Maybe you want to archive all receipts generated in your name by OTTO Market monthly, fetch it this way:

GET /v3/receipts?receiptTypes=PURCHASE,PARTIAL_REFUND,REFUND&from=2022-08-01&to=2022-08-31

If there is a next link follow it until there are no new receipts. If you like to get also PDF documents, get the receipt numbers first as described above and use it to get the PDF documents in a second step.

Fetch JSON representation by a single receipt​

This is how you can get JSON representation by receiptNumber= R-DE-123456789-2020-1507

GET /v3/receipts/R-DE-123456789-2020-1507
Fetch PDF document by a single receipt​

PDF documents are visible for customers in aftersales area. To fetch a PDF document you need the receiptNumber first. You can get it with one of the requests described above. This is how you can get PDF document by receiptNumber= R-DE-123456789-2020-1507

GET /v3/receipts/R-DE-123456789-2020-1507.pdf

Performance Hints​

There can be a lot of combinations of parameters for the API which will result in varying response times. For best performance results try to use from & to and try to limit the duration between these dates. Avoid using page which is deprecated. Use next instead. For quicker results or with fewer data expected, a smaller limit could be used. The default limit is 128.

Pagination​

Paging will occur if the number of returned receipts exceeds the current limit (request parameter limit).

Example​
{
      "resources": [
        { 
          ...
        }
        ...
      ],
      "links": [
        {
          "href": "/v3/receipts?nextcursor=eyJmZiI6MTY4ODU0Mzk5MDUxMCwicGlmIjoiMTAwNjI1MCIsIm0iOiJCVUNLRVQiLCJvY3QiOiJPUkRFUl9MSUZFQ1lDTEVfREFURSIsIm9kIjoiQVNDIiwic3RmIjoic2FsZXNPcmRlcklkIiwibHNvaSI6ImUxM2IwYTMyLWU1ZTMtNDEwYi05YWQ2LTliZWRlY2MwNzVjNiIsInNvaWNyIjpmYWxzZX0",
          "rel": "next"
        }
      ]
}

Using /v3/receipts?next=eyJmZiI6MTY4ODU0Mzk5MDUxMCwicGlmIjoiMTAwNjI1MCIsIm0iOiJCVUNLRVQiLCJvY3QiOiJPUkRFUl9MSUZFQ1lDTEVfREFURSIsIm9kIjoiQVNDIiwic3RmIjoic2FsZXNPcmRlcklkIiwibHNvaSI6ImUxM2IwYTMyLWU1ZTMtNDEwYi05YWQ2LTliZWRlY2MwNzVjNiIsInNvaWNyIjpmYWxzZX0 here would receive the next slice of records; a missing next link indicates no further records.

Glossary​

  • Receipt - Collection of all details of a receipt. A receipt can have different receiptTypes
  • Customer - Customer information
  • Address - Address entered by customer during the order process. Recipient can be a person or a pickup point.
  • Partner - Partner details when generating the receipt
  • LineItems - Object, that contains all kinds of possible line items of a receipt, like:
    • ItemPosition - Representation of an item
      Never used in context of receipts of receiptType PARTIAL_REFUND
    • DeliveryCost - Representation of delivery cost like delivery fee or freight surcharge
      Never used in context of receipts of receiptType PARTIAL_REFUND
    • ServicePosition - Representation of a service
      Never used in context of receipts of receiptType PARTIAL_REFUND
    • ItemPartialRefundPosition - Reduction of an item price granted by a receipt of receiptType PARTIAL_REFUND
    • ServicePartialRefundPosition - Reduction on a service price granted by a receipt of receiptType PARTIAL_REFUND
    • DeliveryFeePartialRefundPosition - Reduction on delivery costs granted by a receipt of receiptType PARTIAL_REFUND
  • PriceModification - PriceModification objects represent price increases and decreases of individual line item objects. Currently we only know decreases.
    On the pdf documents increases and decreases do not necessarily have to be shown on the same line. If there is a discrepancy, it is visible by different line numbers of this object and the parent line item object.
    Different PriceModification objects of same type are possible.
  • Payment - Payment details
  • TotalsReduction - Reduction on receipt level
  • Shipment - Additional information of shipment
  • receiptNumber - The receipt number is unique per partner and is build up as follows <Reference>-<VAT Id>-<Year>-<Sequence number> with:
    • <Reference>: The reference is used to differentiate different sequence number ranges from each other. The following sequence number ranges can exist: R = Purchase receipts E = refund receipts
    • <VAT ID>: VAT Id = Value Added Tax identification number. We separate the country abbreviation from the rest of the number with a hyphen, i.e. as follows: DE-123456789
    • <Year>: The year is determined on the basis of UTC time. The information is displayed in the format YYYY.
    • <Sequence number>: Sequence number ranges are assigned once a year. They start at 1 and have no fixed length

ON THIS PAGE