REST Resource: orders

Ressource: Bestellung

Die Order-Ressource enthält umfassende Informationen zu einer Transaktion, die bei Google Play ausgeführt wurde. Es enthält eine Vielzahl von Attributen, die Details zur Bestellung selbst, zu den gekauften Produkten und zum Verlauf der Ereignisse im Zusammenhang mit der Bestellung liefern.

Die Orders APIs ermöglichen den Echtzeit-Zugriff auf Ihre Bestelldaten im Google Play-Ökosystem. Sie können detaillierte Informationen und Metadaten für einmalige und wiederkehrende Bestellungen abrufen, einschließlich Transaktionsdetails wie Gebühren, Steuern und Erstattungen sowie Metadaten wie Preisphasen für Abos. Mit den Orders APIs können Sie Aufgaben im Zusammenhang mit der Bestellverwaltung automatisieren. So sind weniger manuelle Prüfungen über die Play Console erforderlich.

Im Folgenden sind einige Anwendungsfälle für diese API aufgeführt:

  • Echtzeitabruf von Bestelldaten: Mit „orders.get“ können Sie Bestelldetails und Metadaten sofort nach einem Kauf über eine Bestell-ID abrufen.

  • Synchronisierung von Bestellaktualisierungen: Bestellaktualisierungen werden regelmäßig synchronisiert, um die Bestellinformationen auf dem neuesten Stand zu halten.

Hinweis:

  • Die Aufrufe der Orders API werden auf Ihr Play Developer API-Kontingent angerechnet, das standardmäßig 200.000 pro Tag beträgt und möglicherweise nicht ausreicht, um umfangreiche Bestellverläufe zu synchronisieren.

  • Pro Aufruf können maximal 1.000 Bestellungen abgerufen werden. Wir empfehlen, größere Seitengrößen zu verwenden, um die Kontingentnutzung zu minimieren. Prüfen Sie Ihr Kontingent in der Cloud Console und fordern Sie bei Bedarf mehr an.

JSON-Darstellung 
{   "lineItems": [     {       object (LineItem)     }   ],   "orderId": string,   "purchaseToken": string,   "state": enum (State),   "createTime": string,   "lastEventTime": string,   "buyerAddress": {     object (BuyerAddress)   },   "total": {     object (Money)   },   "tax": {     object (Money)   },   "orderDetails": {     object (OrderDetails)   },   "orderHistory": {     object (OrderHistory)   },   "developerRevenueInBuyerCurrency": {     object (Money)   },   "pointsDetails": {     object (PointsDetails)   } }
Felder
lineItems[]

object (LineItem)

Die einzelnen Positionen, aus denen sich diese Bestellung zusammensetzt.
orderId

string

Die Bestell‑ID.
purchaseToken

string

Das Token, das dem Gerät des Nutzers beim Kauf des Abos oder Artikels bereitgestellt wurde.
state

enum (State)

Der Status der Bestellung.
createTime

string (Timestamp format)

Der Zeitpunkt, zu dem die Bestellung erstellt wurde.

Verwendet RFC 3339, wobei die generierte Ausgabe immer Z-normalisiert ist und 0, 3, 6 oder 9 Nachkommastellen verwendet. Andere Offsets als „Z“ werden ebenfalls akzeptiert. Beispiele: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" oder "2014-10-02T15:01:23+05:30".
lastEventTime

string (Timestamp format)

Die Uhrzeit des letzten Ereignisses, das für die Bestellung aufgetreten ist.

Verwendet RFC 3339, wobei die generierte Ausgabe immer Z-normalisiert ist und 0, 3, 6 oder 9 Nachkommastellen verwendet. Andere Offsets als „Z“ werden ebenfalls akzeptiert. Beispiele: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" oder "2014-10-02T15:01:23+05:30".
buyerAddress

object (BuyerAddress)

Adressinformationen für den Kunden zur Verwendung bei der Steuerberechnung. Wenn Google der Merchant of Record für die Bestellung ist, wird nur das Land angezeigt.
total

object (Money)

Vom Kunden gezahlter Endbetrag unter Berücksichtigung von Rabatten und Steuern.
tax

object (Money)

Die im Rahmen dieser Bestellung gezahlte Gesamtsteuer.
orderDetails

object (OrderDetails)

Detaillierte Informationen zur Bestellung zum Zeitpunkt der Erstellung.
orderHistory

object (OrderHistory)

Details zu Ereignissen, die die Bestellung geändert haben.
developerRevenueInBuyerCurrency

object (Money)

Dein Umsatz für diese Bestellung in der Währung des Käufers, einschließlich Abzügen für Teilerstattungen, Steuern und Gebühren. Google zieht die standardmäßigen Transaktions- und Drittanbietergebühren von jedem Verkauf ab, einschließlich der MwSt. in einigen Ländern.
pointsDetails

object (PointsDetails)

Auf die Bestellung angewendete Play Points, einschließlich Angebotsinformationen, Rabatt und Punktwerten.

Status

Der Status der Bestellung.

Enums
STATE_UNSPECIFIED Status ist unbekannt. Dieser Wert wird nicht verwendet.
PENDING Die Bestellung wurde erstellt und wartet auf die Verarbeitung.
PROCESSED Die Bestellung wurde erfolgreich bearbeitet.
CANCELED Die Bestellung wurde vor der Bearbeitung storniert.
PENDING_REFUND Die beantragte Erstattung wird noch verarbeitet.
PARTIALLY_REFUNDED Ein Teil des Betrags der Bestellung wurde erstattet.
REFUNDED Der gesamte Betrag der Bestellung wurde erstattet.

BuyerAddress

Adressinformationen für den Kunden zur Verwendung bei der Steuerberechnung.

JSON-Darstellung 
{   "buyerState": string,   "buyerCountry": string,   "buyerPostcode": string }
Felder
buyerState

string

Verwaltungsgebiet auf höchster Ebene des Landes der Käuferadresse. Wenn Google der Merchant of Record für die Bestellung ist, sind diese Informationen nicht enthalten.
buyerCountry

string

Ländercode mit zwei Buchstaben basierend auf ISO 3166-1 Alpha-2 (UN-Ländercodes).
buyerPostcode

string

Postleitzahl einer Adresse. Wenn Google der Merchant of Record für die Bestellung ist, sind diese Informationen nicht enthalten.

OrderDetails

Detaillierte Informationen zur Bestellung zum Zeitpunkt der Erstellung.

JSON-Darstellung 
{   "taxInclusive": boolean }
Felder
taxInclusive

boolean

Gibt an, ob der angegebene Preis inklusive Steuern war oder nicht.

LineItem

Details zu einer Position.

JSON-Darstellung 
{   "productTitle": string,   "productId": string,   "listingPrice": {     object (Money)   },   "total": {     object (Money)   },   "tax": {     object (Money)   },    // Union field details can be only one of the following:   "oneTimePurchaseDetails": {     object (OneTimePurchaseDetails)   },   "subscriptionDetails": {     object (SubscriptionDetails)   },   "paidAppDetails": {     object (PaidAppDetails)   }   // End of list of possible types for union field details. }
Felder
productTitle

string

Der vom Entwickler angegebene Name des Produkts. Er wird in der Sprache des Käufers angezeigt. Beispiel: Münzen, Monatsabo usw.
productId

string

Die gekaufte Produkt-ID oder In-App-Artikelnummer (z. B. „monthly001“ oder „com.some.thing.inapp1“).
listingPrice

object (Money)

Der angegebene Preis des Artikels im Play Store. Dieser kann Steuern enthalten. Schließt alle Rabatte oder Angebote aus.
total

object (Money)

Der Gesamtbetrag, den der Nutzer für diese Position bezahlt hat, unter Berücksichtigung von Rabatten und Steuern.
tax

object (Money)

Die für diese Position gezahlte Steuer.

Union-Feld details.

Für details ist nur einer der folgenden Werte zulässig:
oneTimePurchaseDetails

object (OneTimePurchaseDetails)

Details zu einem einmaligen Kauf.
subscriptionDetails

object (SubscriptionDetails)

Details zu einem Abokauf.
paidAppDetails

object (PaidAppDetails)

Details zu einem Kauf einer kostenpflichtigen App.

OneTimePurchaseDetails

Details zu einem einmaligen Kauf.

JSON-Darstellung 
{   "quantity": integer,   "offerId": string,   "purchaseOptionId": string,   "rentalDetails": {     object (RentalDetails)   } }
Felder
quantity

integer

Die Anzahl der gekauften Artikel (bei Käufen von Artikeln in variabler Stückzahl).
offerId

string

Die Angebots-ID des Angebots für den Einmalkauf.
purchaseOptionId

string

ID der Kaufoption. Dieses Feld wird sowohl für Kaufoptionen als auch für Variantenangebote festgelegt. Bei Kaufoptionen wird mit dieser ID die Kaufoption selbst identifiziert. Bei Variantenangeboten bezieht sich diese ID auf die zugehörige Kaufoption. In Verbindung mit „offerId“ wird das Variantenangebot identifiziert.
rentalDetails

object (RentalDetails)

Details zu einem Leihkauf. Nur festlegen, wenn es sich um einen Mietkauf handelt.

RentalDetails

Dieser Typ hat keine Felder.

Details zu einem Leihkauf.

SubscriptionDetails

Details zu einem Abokauf.

JSON-Darstellung 
{   "basePlanId": string,   "offerId": string,   "offerPhase": enum (OfferPhase),   "servicePeriodStartTime": string,   "servicePeriodEndTime": string }
Felder
basePlanId

string

Die Basis-Abo-ID des Abos.
offerId

string

Die Angebots-ID für das aktuelle Aboangebot.
offerPhase

enum (OfferPhase)

Die Preisgestaltungsphase für den Abrechnungszeitraum, der durch diese Bestellung finanziert wird.
servicePeriodStartTime

string (Timestamp format)

Der Beginn des Abrechnungszeitraums, der durch diese Bestellung finanziert wird. Dies ist ein Snapshot des Beginns des Abrechnungs-/Servicezeitraums zum Zeitpunkt der Bearbeitung der Bestellung und sollte nur für die Buchhaltung verwendet werden.

Verwendet RFC 3339, wobei die generierte Ausgabe immer Z-normalisiert ist und 0, 3, 6 oder 9 Nachkommastellen verwendet. Andere Offsets als „Z“ werden ebenfalls akzeptiert. Beispiele: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" oder "2014-10-02T15:01:23+05:30".
servicePeriodEndTime

string (Timestamp format)

Das Ende des Abrechnungszeitraums, der durch diesen Auftrag finanziert wird. Dies ist ein Snapshot des Endzeitpunkts des Abrechnungs-/Servicezeitraums zum Zeitpunkt der Bearbeitung der Bestellung und sollte nur für die Buchhaltung verwendet werden. Verwenden Sie purchases.subscriptionsv2.get, um die aktuelle Endzeit des Abozeitraums abzurufen.

Verwendet RFC 3339, wobei die generierte Ausgabe immer Z-normalisiert ist und 0, 3, 6 oder 9 Nachkommastellen verwendet. Andere Offsets als „Z“ werden ebenfalls akzeptiert. Beispiele: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" oder "2014-10-02T15:01:23+05:30".

OfferPhase

Die Preisphase für den Berechtigungszeitraum, der durch diese Bestellung finanziert wird.

Enums
OFFER_PHASE_UNSPECIFIED Die Angebotsphase ist nicht angegeben. Dieser Wert wird nicht verwendet.
BASE Mit der Bestellung wird ein Zeitraum mit einem Basispreis finanziert.
INTRODUCTORY Die Bestellung finanziert einen Zeitraum mit Einführungspreis.
FREE_TRIAL Mit der Bestellung wird ein kostenloser Testzeitraum finanziert.

PaidAppDetails

Dieser Typ hat keine Felder.

Details zu einem Kauf einer kostenpflichtigen App.

OrderHistory

Details zu Ereignissen, die die Bestellung geändert haben.

JSON-Darstellung 
{   "partialRefundEvents": [     {       object (PartialRefundEvent)     }   ],   "processedEvent": {     object (ProcessedEvent)   },   "cancellationEvent": {     object (CancellationEvent)   },   "refundEvent": {     object (RefundEvent)   } }
Felder
partialRefundEvents[]

object (PartialRefundEvent)

Details zu den Ereignissen für die Teilerstattung für diese Bestellung.
processedEvent

object (ProcessedEvent)

Details dazu, wann die Bestellung bearbeitet wurde.
cancellationEvent

object (CancellationEvent)

Details dazu, wann die Bestellung storniert wurde.
refundEvent

object (RefundEvent)

Details dazu, wann die Bestellung vollständig erstattet wurde.

ProcessedEvent

Details dazu, wann die Bestellung bearbeitet wurde.

JSON-Darstellung 
{   "eventTime": string }
Felder
eventTime

string (Timestamp format)

Der Zeitpunkt, zu dem die Bestellung bearbeitet wurde.

Verwendet RFC 3339, wobei die generierte Ausgabe immer Z-normalisiert ist und 0, 3, 6 oder 9 Nachkommastellen verwendet. Andere Offsets als „Z“ werden ebenfalls akzeptiert. Beispiele: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" oder "2014-10-02T15:01:23+05:30".

CancellationEvent

Details dazu, wann die Bestellung storniert wurde.

JSON-Darstellung 
{   "eventTime": string }
Felder
eventTime

string (Timestamp format)

Der Zeitpunkt, zu dem die Bestellung storniert wurde.

Verwendet RFC 3339, wobei die generierte Ausgabe immer Z-normalisiert ist und 0, 3, 6 oder 9 Nachkommastellen verwendet. Andere Offsets als „Z“ werden ebenfalls akzeptiert. Beispiele: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" oder "2014-10-02T15:01:23+05:30".

RefundEvent

Details dazu, wann die Bestellung vollständig erstattet wurde.

JSON-Darstellung 
{   "eventTime": string,   "refundDetails": {     object (RefundDetails)   },   "refundReason": enum (RefundReason) }
Felder
eventTime

string (Timestamp format)

Der Zeitpunkt, zu dem die Bestellung vollständig erstattet wurde.

Verwendet RFC 3339, wobei die generierte Ausgabe immer Z-normalisiert ist und 0, 3, 6 oder 9 Nachkommastellen verwendet. Andere Offsets als „Z“ werden ebenfalls akzeptiert. Beispiele: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" oder "2014-10-02T15:01:23+05:30".
refundDetails

object (RefundDetails)

Details zur vollständigen Erstattung.
refundReason

enum (RefundReason)

Der Grund für die Erstattung der Bestellung.

RefundDetails

Details zu einer teilweisen oder vollständigen Erstattung.

JSON-Darstellung 
{   "total": {     object (Money)   },   "tax": {     object (Money)   } }
Felder
total

object (Money)

Der erstattete Gesamtbetrag, einschließlich Steuern.
tax

object (Money)

Die Höhe der erstatteten Steuern.

RefundReason

Der Grund für die Erstattung der Bestellung.

Enums
REFUND_REASON_UNSPECIFIED orders.refund reason unspecified. Dieser Wert wird nicht verwendet.
OTHER Die Bestellung wurde aus einem anderen als den hier aufgeführten Gründen erstattet.
CHARGEBACK Die Bestellung wurde storniert.

PartialRefundEvent

Details zu den Ereignissen für die Teilerstattung für diese Bestellung.

JSON-Darstellung 
{   "createTime": string,   "processTime": string,   "state": enum (State),   "refundDetails": {     object (RefundDetails)   } }
Felder
createTime

string (Timestamp format)

Der Zeitpunkt, zu dem die Teilerstattung erstellt wurde.

Verwendet RFC 3339, wobei die generierte Ausgabe immer Z-normalisiert ist und 0, 3, 6 oder 9 Nachkommastellen verwendet. Andere Offsets als „Z“ werden ebenfalls akzeptiert. Beispiele: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" oder "2014-10-02T15:01:23+05:30".
processTime

string (Timestamp format)

Der Zeitpunkt, zu dem die teilweise Erstattung verarbeitet wurde.

Verwendet RFC 3339, wobei die generierte Ausgabe immer Z-normalisiert ist und 0, 3, 6 oder 9 Nachkommastellen verwendet. Andere Offsets als „Z“ werden ebenfalls akzeptiert. Beispiele: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" oder "2014-10-02T15:01:23+05:30".
state

enum (State)

Der Status der teilweisen Erstattung.
refundDetails

object (RefundDetails)

Details zur teilweisen Erstattung.

Status

Der Status der teilweisen Erstattung.

Enums
STATE_UNSPECIFIED Status ist unbekannt. Dieser Wert wird nicht verwendet.
PENDING Die teilweise Erstattung wurde erstellt, aber noch nicht verarbeitet.
PROCESSED_SUCCESSFULLY Die teilweise Erstattung wurde erfolgreich verarbeitet.

PointsDetails

Details zu allen Play Points, die auf eine Bestellung angewendet wurden.

JSON-Darstellung 
{   "pointsOfferId": string,   "pointsCouponValue": {     object (Money)   },   "pointsDiscountRateMicros": string,   "pointsSpent": string }
Felder
pointsOfferId

string

Eindeutige ID des für diese Bestellung verwendeten Play Points-Angebots.
pointsCouponValue

object (Money)

Der Geldwert eines Play Points-Gutscheins. Das ist der Rabatt, der mit dem Gutschein gewährt wird. Er entspricht möglicherweise nicht dem Gesamtbetrag. Wird nur festgelegt, wenn Play Points-Gutscheine verwendet wurden. Bei einem Gutschein mit 100 Punkten für 2 $sind das 2 $.
pointsDiscountRateMicros

string (int64 format)

Der Prozentsatz, um den die Kosten durch die Play Points-Promotion gesenkt werden. Bei einem Gutschein mit 100 Punkten für 2 $sind das beispielsweise 500.000. Da für $2 ein Schätzwert von 200 Punkten vorliegt, die tatsächlich erforderlichen Punkte (100) jedoch 50% dieses Werts betragen, und 50% in Mikros 500.000 sind. Zwischen 0 und 1.000.000.
pointsSpent

string (int64 format)

Die Anzahl der in dieser Bestellung angewendeten Play-Punkte. Bei einem Coupon mit 100 Punkten für 2 € ist das beispielsweise 100. Bei einem Gutschein, der mit einem Basisangebot kombiniert wird, ist dies die Gesamtzahl der Punkte, die für beide ausgegeben wurden.

Methoden

batchget

 Ruft Bestelldetails für eine Liste von Bestellungen ab.

get

 Bestelldetails für eine einzelne Bestellung abrufen.

refund

 Erstattet die Bestellung eines Nutzers für ein Abo oder einen In-App-Kauf.