Update / easy.affiliate REST-API (Baskets)

📝 Einleitung

Um Warenkorb-Positionen von Orders automatisiert im easy.affiliate-System bearbeiten zu können, stellt die easy Marketing GmbH eine Webservice-API zur Verfügung. Diese ermöglicht es, einzelne Positionen bestehender Orders im Nachgang zu bearbeiten – z. B. bei Teilretouren, Teilstornos oder Preiskorrekturen.

Nach jeder Änderung werden Bestellwert, Provision und Status der Order automatisch aus ihren Positionen neu berechnet.

Jedem User stehen hierfür ein Authentifizierungs-Token und eine Login_id zur Verfügung, die über das Frontend abgerufen werden können.

• User-ID: Wo ist die User-ID hinterlegt? (Siehe Frontend-Profil)
• Access-Token: Wo ist der Access-Token hinterlegt? (Siehe API-Einstellungen)

Endpunkte

Zielgruppe	URL
Admin	https://SUBDOMAIN.de/ws/V6/admin/REST/Baskets

Beispiele

Beispiel mit cURL

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "X-Network-ID: -1" \
  -H "X-Auth-Token: ADMIN_APIUSER_TOKEN" \
  -H "X-Auth-ID: ADMIN_APIUSER_LOGIN_ID" \
  -d '[{ "id": 981234, "amount": 1 },{ "id": 981235, "status": 2 }]' \
  https://SUBDOMAIN.de/ws/V6/admin/REST/Baskets

Codebeispiel

Mit der folgenden Methode können eine oder mehrere Warenkorb-Positionen geupdatet werden. Ein Beispielaufruf sieht folgendermaßen aus:

Headers

Variable	Wert / Bedeutung
Content-Type	application/json
X-Network-ID	-1
X-Auth-Token	ADMIN_APIUSER_TOKEN
X-Auth-ID	ADMIN_APIUSER_LOGIN_ID

Body

[
    {
        "id": 981234,
        "amount": 1
    },
    {
        "basket_item_id": 981235,
        "status": 2
    },
    {
        "id": 981236,
        "price": 17.50,
        "additional": { "retoure_grund": "zu klein" }
    }
]

Für eine einzelne Position kann statt der Liste auch direkt ein Objekt gesendet werden, z. B. { "id": 981234, "amount": 1 }.

Variablenerläuterung

Headers

Variable	Bedeutung	Datentyp
Content-Type	Der Content-Type des Requests	String
X-NETWORKID	Hier wird die ID des Mandanten eingetragen. Wenn nur ein Mandant vorhanden ist oder mandantenübergreifend gearbeitet wird, muss der Wert “-1” eingetragen werden.	Integer
X-AUTH-TOKEN	Hier wird der API-Authentifizierungs-Token des Admin Nutzers hinterlegt.	String
X-AUTH-ID	Hier wird die ID des Admin Nutzers hinterlegt.	Integer

Body

Parameter	Beschreibung	Datentyp	Pflichtfeld
id	ID der Warenkorb-Position. Steht in der Antwort der Anlage (basket[].id) bzw. im Order-Export.	Integer	✅ Ja (oder basket_item_id)
basket_item_id	Alternative Schreibweise für id.	Integer	✅ Ja (oder id)
amount	Neue Menge der Position.	Integer	Nein
price	Neuer Preis einer Einheit, Punkt als Dezimaltrenner.	Float	Nein
status	Status der Position: 0 = offen, 1 = bestätigt, 2 = storniert, 3 = ausgezahlt.	Integer	Nein
commission	Provisionswert der Position in Kampagnenwährung. Wird er nicht übergeben, wird die Provision neu berechnet (Preis × Menge × Provisionssatz der Position).	Float	Nein
additional	Objekt { "key": "value", … }. Die übergebenen Keys werden in die bestehenden Zusatzfelder der Position eingefügt bzw. überschrieben; nicht übergebene Keys bleiben erhalten.	Object	Nein

*) Hinweis: Alle Werte außer additional müssen numerisch sein. Weitere Felder (z. B. productname, article_number, campaign_id) werden ignoriert und können über diesen Endpunkt nicht geändert werden.

🔄 Auswirkung auf die Order

Nach jeder Änderung wird die zugehörige Order aus allen ihren Positionen neu berechnet:

Wert der Order	Berechnung
turnover	Summe aus price × amount aller Positionen mit Status 0, 1 oder 3 (stornierte Positionen zählen nicht)
commission	Summe der Provisionen aller Positionen mit Status 0, 1 oder 3
status	Niedrigster Status aller Positionen (eine offene Position hält die Order offen; sind alle Positionen storniert, ist die Order storniert)

Die Neuberechnung erfolgt nur, solange die Order den Status offen, bestätigt oder storniert hat. Bereits ausgezahlte Orders (Status 3) werden nicht mehr verändert.

📤 Antwort

Die Antwort enthält die gespeicherten Positionen mit ihren aktuellen Werten (bei einer Liste als Array, bei einem einzelnen Objekt als Objekt).

Bei einer Liste werden Positionen, die nicht gefunden wurden oder ungültige Werte enthalten, übersprungen und fehlen in der Antwort – die übrigen Positionen werden trotzdem gespeichert. Bei einem einzelnen Objekt antwortet der Webservice in diesem Fall mit einem Fehler.

📘 Hinweise

• Teilretoure: Menge reduzieren (amount) oder die betroffene Position stornieren (status: 2) – Bestellwert und Provision der Order passen sich automatisch an.
• Komplettstorno: Alle Positionen auf status: 2 setzen, die Order wird dann ebenfalls storniert.
• Positions-IDs: Kommen aus der Antwort von Create / easy.affiliate REST-API (Baskets) oder per GET auf denselben Endpunkt.