Skip to main content

Changelog

2025-05-05​

Products V5 (Sandbox Only)​

  • The former productSafety container has been moved from the top level to the new compliance container and restructured to accommodate multiple addresses.
  • For each address information, it is mandatory to provide the corresponding role(s) of the respective economic operator. In the case of a set-product, the corresponding component can now also be assigned to an address.

2025-01-08​

Receipts V3​

Added​

  • Add new price modifications type REFUND_CREDIT_CARD_DISPUTE
  • Add new partial refund type REFUND_CREDIT_CARD_DISPUTE

2024-10-11​

Receipts V3​

Added​

  • Add new value CREDIT_CARD to field paymentMethod of Payment

2024-10-07​

Products V3​

  • The product safety information now includes the additional properties regionCode and url. Specifying the email and/or url is mandatory when providing product safety information.

Products V4​

2024-09-27​

Receipts V3​

Added​

  • Add new field insurancePeriodto ServicePartialRefundPosition

2024-09-26​

Orders V4​

  • New value CREDIT_CARD had been added.- Old value CREDIT_CARD_ONLINE has been deprecated.

2024-09-24​

Receipts V3​

Added​

  • Add new value INSURANCE to field serviceType of ServicePosition
  • Add new object schema ServicePartialRefundPosition
  • Add field servicePartialRefundPositions as array of ServicePartialRefundPosition to LineItems

2024-09-23​

Shipments V1​

  • Changed description for multiparcel-shipments

2024-09-20​

Receipts V3​

Added​

  • Add new value SERVICE_FULL_REFUND_CANCELLED_BY_SDU, SERVICE_FULL_REFUND_PRODUCT_RETURNED to refundType of Receipt
  • Add new value REFUND_PARTIAL_AMOUNT_AFTER_SERVICE_CANCELLATION to partialRefundType of Receipt
  • Add new value REFUND_PARTIAL_AMOUNT_AFTER_SERVICE_CANCELLATION to priceModificationType of PriceModification

2024-09-17​

Orders V4​

  • New field dealId: the unique id of the deal related to the position item. - New field dealName: the name of the deal related to the position item.

2024-08-06​

Orders V4​

  • The new cancellation reason is CANCELLED_ON_MARKETPLACE_WISH.

2024-08-05​

Availability V1​

  • Replaces Quantities v2 Replaces Quantities v2

2024-08-01​

Products V4​

  • The top-level delivery container becomes optional and will be removed in v4 in 2025. There is no need to transmit deliveryTypes and deliveryTimes, when you setup shipping-profiles. The shipping-profiles become mandatory, so take the chance and set them up as quickly as possible.Due to legal requirements the productSafety container will becomes mandatory. Please start entering the safety information as soon as possible.There is no need anymore to provide start- and end-periods for your sale-prices. These attributes become optional. To setup a reduction on otto.de it will be enough, to set the standardPrice and the salePrice.The sale periods can still be used. In this case, both the start and end dates must still be set and must be valid.New SKUs will be sanitized. It is not allowed to use leading or trailing spaces and the SKUs should be UTF8-compliant.It will still be possible to update existing SKUs that were created with API v3 or older.

2024-07-23​

Shipments V1​

  • added new carriers: RABEN_LOGISTIK, ZUFALL, GEIS, DSV, EPH_DIREKT, SCHMIDT_GEVELSBERG, GUETTLER, REIMER, HEUEL

2024-07-16​

Receipts V3​

Added​

  • Add field paymentBreak to Payment

2024-05-28​

Products V3​

  • Possibility to add information for product safety - productSafety is a new top level container for providing manufacturer / importer information. Will be obligatory from V4.

2024-05-21​

Receipts V3​

Added​

  • Add field linkedPositionItemId to Details

2024-05-06​

Orders V4​

  • The new cancellation reason is MARKETPLACE_FRAUD.

2024-04-22​

Receipts V3​

Added​

  • Add new value REFUND_ESCALATION to priceModificationType of PriceModification
  • Add new value REFUND_ESCALATION to partialRefundType of Receipt

2024-04-08​

Orders V4​

  • If the return of a position item has been accepted by the marketplace, this flag is set to true.

2024-03-18​

Returns V3​

  • We are introducing API v3 in which return rejection reason should be one of the enum values; rather than a free text earlier. From v3, return acceptance can also have a reason as an optional enum value.API version v2 will be supported till 30th September, 2024.After this date, the returns interface will reject requests via v2 and only v3 will be supported. Please do the necessary changes to migrate to v3 version. We are introducing API v3 in which return rejection reason should be one of the enum values; rather than a free text earlier. From v3, return acceptance can also have a reason as an optional enum value.API version v2 will be supported till 30th September, 2024.After this date, the returns interface will reject requests via v2 and only v3 will be supported. Please do the necessary changes to migrate to v3 version.

2024-02-07​

Orders V4​

  • In case of illegal product, open orders will be cancelled with the fulfillment status set to CANCELLED_BY_MARKETPLACE and a cancellation reason of ILLEGAL_PRODUCT.

2024-01-18​

Orders V4​

  • New optional field shopUrl has been added to the product on the position item level. It contains the url of the product inside the webshop.

2023-11-13​

Receipts V3​

Added​

  • Add new value REFUND_PAYPAL_DISPUTE to field priceModificationType of PriceModification

2023-11-09​

Orders V4​

  • When the partner cancels an order after having received a fraud suspicion for that order, the cancellation reason will be set to PAYMENT_FRAUD while the fulfillment status remains CANCELLED_BY_PARTNER.- When the contract between the partner and OTTO Market has been terminated, open orders will be cancelled with the fulfillment status set to CANCELLED_BY_MARKETPLACE and a cancellation reason of PARTNER_TERMINATED.

Receipts V3​

Added​

  • Add new object schema Shipment
  • Add new object schema AddressInformation
  • Add field shipment of object type Shipment to Receipt
  • Add field shipFromAddress of object type AddressInformation to Shipment

2023-09-07​

Receipts V3​

Added​

  • Add new query parameter next to endpoint GET /v3/receipts

Deprecated​

  • Set query parameter page of GET /v3/receipts to deprecated. Please switch to new parameter next

2023-08-09​

Receipts V3​

Added​

  • Add new value PAYPAL to field paymentMethod of Payment

2023-07-06​

ReturnShipments V1​

  • changed ReturnShipmentState order

ReturnShipments V1​

  • Add new ReturnShipmentState ANNOUNCED

2023-06-19​

Receipts V3​

Added​

  • Add field priceModifications as array of PriceModification to ServicePosition
  • Add object schema ServicePartialRefundPosition
  • Add field servicePartialRefundPositions as array of ServicePartialRefundPosition to LineItems
  • Add object schema DeliveryFeePartialRefundPosition
  • Add field deliveryFeePartialRefundPositions as array of DeliveryFeePartialRefundPosition toLineItems
  • Add object schema PartialRefundDetails
  • Add field partialRefundDetails of PartialRefundDetails to ItemPartialRefundPosition
  • Add field partialRefundType to Receipt for PARTIAL_REFUND receipts
  • Add field reason to Details for PARTIAL_REFUND receipts
  • Add field type to Details of PriceModification

Changed​

  • Change description of field priceModificationType of PriceModification
  • Change field description of Details

2023-05-31​

Receipts V3​

Added​

  • Add field totalsReductions to Receipt
  • Add field priceToPayPerPositionItems to ItemPosition for PURCHASE receipts

2023-04-26​

Receipts V3​

Added​

  • Add field refundType to Receipt for REFUND receipts

2023-04-14​

ReturnShipments V1​

  • Fixed the name of 'creationDate' to 'createdAt' to match the actual implementation, added some documentation

2023-03-27​

ReturnShipments V1​

  • Go live of API Definition

2023-03-22​

Shipments V1​

  • Added endpoint for multiparcel-shipments.

2023-02-10​

ReturnShipments V1​

  • Change name of id consistently to returnShipmentId

ReturnShipments V1​

  • Fixed property names of ReturnPositionItems

2023-02-07​

ReturnShipments V1​

  • return-shipments endpoint returns list of full return-shipments, removed ReturnShipmentsWithMinimumDetails

2023-01-11​

Receipts V3​

We are proudly introducing our Receipts API v3 with a lot of changes compared to v2, that we will roughly describe here.
v2 will be supported until 11th of July 2023.. After this date, the receipts interface will reject requests via v2.

Added​

  • Add new query parmeter receiptTypes, from and to to /receipts endpoint
  • New field isRealReceipt of Receipt indicates whether its a real invoice or technical invoice
  • New field houseNumber of Customer contains house number of the customer
  • New field houseNumber of DeliveryAddress contains house number of the delivery address
  • New field totals as array of Price contains total amount per tax type and tax rate
  • New field totalsGrossAmount contains summation of total receipt amount including all tax type

Changed​

  • Query parameter sales_order_id of /receipts endpoint has been renamed to salesOrderId
  • Field typeof Receipt has been renamed to receiptType
  • Field originalReceiptNumber has been renamed to linkedReceiptNumber
  • Field originalCreationDate has been renamed to linkedCreationDate
  • Field name of Partner has been renamed to partnerName
  • Field legalRepresentatives of Partner has been renamed to representedBy
  • Field registerNumber of Partner has been renamed to commercialRegisterNumber
  • Field street of Customer will not contain house number for newly created receipts
  • Field articleNumber will contain promotion as suffix
  • Array field lineItems was only used for item positions previously, now there is a sub structure that cares about all bill objects
  • Field dimensions of lineItem has been renamed to variationAttributes of ItemPosition
  • Field amountDue will contain the actual amount due from customer
  • Array field shippingCosts has been renamed to deliveryCosts
  • Field vatRate has been renamed to taxRate
  • Field vat has been renamed to tax

Removed​

  • Field url and field priceToPay has been removed
  • Query parameter type has been removed from /receipts endpoint

2022-12-12​

ReturnShipments V1​

  • first version of the API Definition

2022-10-04​

Orders V4​

  • All partner orders will now show up instantly in the status ANNOUNCED (regardless of the payment method). Once the time period has exceeded in which the customer can still cancel an order, the respective position items will transition to PROCESSABLE status. If the customer has actually cancelled a position item or an entire order, the respective position items will change their status to CANCELLED_BY_MARKETPLACE with a cancellation reason of CANCELLED_ON_CUSTOMER_WISH.

2022-09-22​

Products V3​

  • the attribute offeringStartDate is deleted - UPC and ISBN are deleted

2022-09-12​

Shipments V1​

  • Deleted field returnAddressCarrierId from the Documentation, field no longer needed in the request.

2022-07-12​

Shipments V1​

  • added new field returnAddressCarrierId, unique id for the return address and the return carrier combination. Backend logic not deployed in live yet.

2022-06-24​

Shipments V1​

  • added authorization to the endpoints and use new roles separated for read and write

2022-05-11​

Orders V4​

  • New field dimensions has been added to the product on the position item level. It describes the different dimensions of a product from the marketplace.

2022-05-01​

Shipments V1​

  • add new ShipmentStates array to Shipments - add add new ShipmentStates array to ShipmentWithMinimumDetails objects

2022-01-19​

Price Reductions V1​

  • price reduction APIs

2021-11-04​

Orders V4​

  • New field cancellationReason has been added on position item level, which describes the reason for a cancellation of an item.

2021-11-01​

Orders V4​

  • New optional field weeePickup has been added on position item level. This field indicates whether customer requested a disposal service as per "Waste from Electrical and Electronic Equipment" (WEEE) regulation.

2021-10-19​

Orders V4​

  • On all endpoints the error response 403 will be given if access role is missing; will include a body conforming to the common error message style.

2021-10-18​

Orders V4​

  • New optional object payment has been added on partner order level. It includes the paymentMethod field, which describes the chosen payment method.

2021-08-30​

Orders V4​

  • The objects deliveryAddress and invoiceAddress of an order (optional since v4) are not provided for orders after 8 weeks after all position items have reached either status SENT or any of the CANCELLED states, i.e. no position item is in BLOCKED or PROCESSABLE status. Both the fields email and phoneNumber are no longer provided after 4 weeks.

2021-08-25​

Orders V4​

  • New optional field processableDate has been added on partner position item level, which describes when a position item has reached PROCESSABLE status.

2021-05-21​

Orders V4​

  • New optional field expectedDeliveryDate has been added on partner position item level, which describes when the customer expects the delivery.

2021-04-30​

Orders V4​

  • Within the query for orders the parameters 'searchTerm' and 'searchTermField' are no longer available.

2020-07-02​

Shipments V1​

  • rework of the validation of the request body for better user experience as version 1.1.0 - better error messages in title and detail properties of ErrorDescription - a new optional property jsonPath in ErrorDescription to imply where the error happened - multiple ErrorDescription in BadRequest, BadRequestAddPositionItemByTrackingNumber and BadRequestAddPositionItemByShipmentId possible

2020-03-31​

Shipments V1​

  • add length restriction to shipFromAddress.city and shipFromAddress.zipCode

2020-02-12​

Shipments V1​

  • add some examples for CreateShipmentRequest for carrier "OTHER_FORWARDER"

2020-01-14​

Shipments V1​

  • type of shipmentId changed from integer to string

ON THIS PAGE