REST Resource: orders

Ressource: Bestellung

Die Ressource „Order“ 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 Zeit 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 offizielle Händler 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 gezahlten Steuern.
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, Rabattsatz und Punktwerten.

Bundesland

Der Status der Bestellung.

Enums
STATE_UNSPECIFIED Status nicht angegeben. 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

Die oberste administrative Unterteilung 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 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,
  "preorderDetails": {
    object (PreorderDetails)
  },
  "rentalDetails": {
    object (RentalDetails)
  }
}
Felder
quantity

integer

Die Anzahl der gekauften Artikel (bei Käufen von Artikeln mit mehreren Mengen).
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.
preorderDetails

object (PreorderDetails)

Details zu einer Vorbestellung. Wird nur festgelegt, wenn es sich um einen Vorbestellungskauf handelt.
rentalDetails

object (RentalDetails)

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

PreorderDetails

Dieser Typ hat keine Felder.

Details zu einem Vorbestellungskauf.

RentalDetails

Dieser Typ hat keine Felder.

Details zu einem Leihkauf.

SubscriptionDetails

Details zu einem Abokauf.

JSON-Darstellung 
{
  "basePlanId": string,
  "offerId": string,
  "offerPhase": enum (OfferPhase),
  "offerPhaseDetails": {
    object (OfferPhaseDetails)
  },
  "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. Verworfen. Verwenden Sie stattdessen „offerPhaseDetails“.
offerPhaseDetails

object (OfferPhaseDetails)

Die Details zur Preisphase für den Berechtigungszeitraum, 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 Abrechnungs-/Dienstzeitraums 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 eine Momentaufnahme des Endes 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.

OfferPhaseDetails

Details zu einer Preisstaffel für den Berechtigungszeitraum, der durch diese Bestellung finanziert wird.

JSON-Darstellung 
{

  // Union field phase_details can be only one of the following:
  "freeTrialDetails": {
    object (FreeTrialDetails)
  },
  "introductoryPriceDetails": {
    object (IntroductoryPriceDetails)
  },
  "baseDetails": {
    object (BaseDetails)
  },
  "prorationPeriodDetails": {
    object (ProrationPeriodDetails)
  }
  // End of list of possible types for union field phase_details.
}
Felder
Union-Feld phase_details. Details zur Preisphase. Für phase_details ist nur einer der folgenden Werte zulässig:
freeTrialDetails

object (FreeTrialDetails)

Mit der Bestellung wird ein kostenloser Testzeitraum finanziert.
introductoryPriceDetails

object (IntroductoryPriceDetails)

Die Bestellung finanziert einen Zeitraum mit Einführungspreis.
baseDetails

object (BaseDetails)

Mit der Bestellung wird ein Zeitraum mit einem Basispreis finanziert.
prorationPeriodDetails

object (ProrationPeriodDetails)

Die Bestellung deckt einen Abrechnungszeitraum ab.

FreeTrialDetails

Dieser Typ hat keine Felder.

Details zu einer Preisphase mit kostenlosem Testzeitraum.

IntroductoryPriceDetails

Dieser Typ hat keine Felder.

Details zu einer Preisphase mit Einführungspreis.

BaseDetails

Dieser Typ hat keine Felder.

Details zu einer Preisphase mit dem Basispreis.

ProrationPeriodDetails

Details zu einem Abrechnungszeitraum.

Ein anteiliger Zeitraum kann ein Zeitraum sein, der bei einer Planänderung berechnet wird, um bestehende Berechtigungen abzudecken (weitere Informationen finden Sie unter Nutzern ermöglichen, ihr Abo zu aktualisieren, herabzustufen oder zu ändern), oder ein anteiliger Zeitraum, um die Verlängerungsdaten von Add-ons mit dem Basis-Abo abzugleichen (weitere Informationen finden Sie unter Regeln für Artikel im Kauf).

JSON-Darstellung 
{
  "originalOfferPhase": enum (OfferPhase),
  "linkedOrderId": string
}
Felder
originalOfferPhase

enum (OfferPhase)

Stellt die ursprüngliche Angebotsphase dar, in der die Werbebuchung gekauft wurde, sofern der Abrechnungszeitraum eine solche Phase enthält. Beispiel: Bei einer anteiligen Abrechnungsperiode nach einer Planänderung vom Typ CHARGE_FULL_PRICE kann die erste Angebotsphase des Aboangebots des neuen Produkts, das der Nutzer gekauft hat, zusammengeführt werden. In diesem Fall wird die ursprüngliche Angebotsphase hier festgelegt.
linkedOrderId

string

Die letzte Bestell-ID des ursprünglichen Abo-Kaufs vor der Tarifänderung. Dieses Feld wird nur ausgefüllt, wenn dieser Abrechnungszeitraum aus einem Upgrade/Downgrade eines vorherigen Abos stammt und die verbleibende Angebotsphase aus der verknüpften Bestellung des vorherigen Abos enthält.

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.

Bundesland

Der Status der teilweisen Erstattung.

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

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 Coupon mit 100 Punkten für 2 $sind das z. B. 500.000. Da für $2 geschätzte 200 Punkte erforderlich sind, die tatsächlichen 100 Punkte aber nur 50 % davon ausmachen, entspricht das in Mikros 500.000. 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

 Ruft Bestelldetails für eine einzelne Bestellung ab.

refund

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

Fehlercodes

Die Vorgänge dieser Ressource geben die folgenden HTTP-Fehlercodes zurück:

Fehlercode Grund Auflösung
5xx Allgemeiner Fehler auf dem Google Play-Server. Wiederholen Sie Ihre Anfrage.

Wenn das Problem weiterhin besteht, wenden Sie sich an Ihren Google Play-Kundenbetreuer oder senden Sie eine Supportanfrage. Prüfen Sie im Play-Status-Dashboard, ob bekannte Ausfälle vorliegen.
409 Fehler beim Aktualisieren der Gleichzeitigkeit.

Es wurde versucht, ein Objekt zu aktualisieren, das gerade aktualisiert wird. Beispiel: Ein Kauf wird bestätigt, indem gleichzeitig die Methode acknowledgePurchase() der Play Billing Library und die Methode purchases.products.acknowledge der Play Developer API aufgerufen werden.

 Wiederholen Sie Ihre Anfrage.