REST Resource: orders

Zasób: Order

Zasób Order (Zamówienie) zawiera szczegółowe informacje o transakcji dokonanej w Google Play. Zawiera on różne atrybuty, które dostarczają szczegółowych informacji o samym zamówieniu, zakupionych produktach i historii zdarzeń związanych z zamówieniem.

Interfejsy API zamówień zapewniają dostęp w czasie rzeczywistym do danych o zamówieniach w ekosystemie Google Play. Możesz pobierać szczegółowe informacje i metadane zarówno w przypadku zamówień jednorazowych, jak i cyklicznych, w tym szczegóły transakcji, takie jak obciążenia, podatki i zwroty, a także metadane, np. etapy cenowe subskrypcji. Interfejsy Orders API umożliwiają automatyzację zadań związanych z zarządzaniem zamówieniami, co zmniejsza potrzebę ręcznego sprawdzania w Konsoli Play.

Oto niektóre przypadki użycia tego interfejsu API:

  • Pobieranie danych zamówienia w czasie rzeczywistym – szczegóły i metadane zamówienia są dostępne natychmiast po zakupie za pomocą identyfikatora zamówienia.

  • Synchronizacja aktualizacji zamówień – okresowa synchronizacja aktualizacji zamówień w celu utrzymania aktualnych informacji o zamówieniach.

Uwaga:

  • Wywołania interfejsu Orders API są wliczane do limitu Play Developer API, który domyślnie wynosi 200 tys. dziennie i może być niewystarczający do synchronizacji rozbudowanej historii zamówień.

  • Każde wywołanie może pobrać maksymalnie 1000 zamówień. Aby zminimalizować wykorzystanie limitu, zalecamy używanie większych rozmiarów stron. Sprawdź limit w Cloud Console i w razie potrzeby poproś o jego zwiększenie.

Zapis JSON 
{
  "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)
  }
}
Pola
lineItems[]

object (LineItem)

Poszczególne elementy zamówienia składające się na to zamówienie.
orderId

string

Identyfikator zamówienia.
purchaseToken

string

Token przekazany na urządzenie użytkownika w momencie zakupu subskrypcji lub produktu.
state

enum (State)

Stan zamówienia.
createTime

string (Timestamp format)

Data i godzina utworzenia zamówienia.

Korzysta ze standardu RFC 3339, w którym wygenerowane dane wyjściowe są zawsze znormalizowane do formatu Z i zawierają 0, 3, 6 lub 9 cyfr po przecinku. Akceptowane są też przesunięcia inne niż „Z”. Przykłady: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" lub "2014-10-02T15:01:23+05:30".
lastEventTime

string (Timestamp format)

Czas ostatniego zdarzenia, które wystąpiło w przypadku zamówienia.

Korzysta ze standardu RFC 3339, w którym wygenerowane dane wyjściowe są zawsze znormalizowane do formatu Z i zawierają 0, 3, 6 lub 9 cyfr po przecinku. Akceptowane są też przesunięcia inne niż „Z”. Przykłady: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" lub "2014-10-02T15:01:23+05:30".
buyerAddress

object (BuyerAddress)

Informacje o adresie klienta do obliczania podatku. Gdy Google jest sprzedawcą w przypadku zamówienia, wyświetlany jest tylko kraj.
total

object (Money)

Ostateczna kwota zapłacona przez klienta z uwzględnieniem rabatów i podatków.
tax

object (Money)

Łączna kwota podatku zapłaconego w ramach tego zamówienia.
orderDetails

object (OrderDetails)

Szczegółowe informacje o zamówieniu w momencie jego utworzenia.
orderHistory

object (OrderHistory)

Szczegóły zdarzeń, które zmodyfikowały zamówienie.
developerRevenueInBuyerCurrency

object (Money)

Przychody uzyskane z tego zamówienia w walucie kupującego, z uwzględnieniem odliczeń za częściowe zwroty środków, podatki i opłaty. Google odejmuje od każdej sprzedaży standardowe opłaty transakcyjne i opłaty dla firm zewnętrznych, w tym VAT w niektórych regionach.
pointsDetails

object (PointsDetails)

Punkty Play zastosowane do zamówienia, w tym informacje o ofercie, wysokość rabatu i wartość punktów.

Stan

Stan zamówienia.

Wartości w polu enum
STATE_UNSPECIFIED Stan nieokreślony. Ta wartość nie jest używana.
PENDING Zamówienie zostało utworzone i oczekuje na przetworzenie.
PROCESSED Zamówienie zostało przetworzone.
CANCELED Zamówienie zostało anulowane przed przetworzeniem.
PENDING_REFUND Prośba o zwrot środków jest w trakcie realizacji.
PARTIALLY_REFUNDED Część kwoty zamówienia została zwrócona.
REFUNDED Zwróciliśmy pełną kwotę zamówienia.

BuyerAddress

Informacje o adresie klienta do obliczania podatku.

Zapis JSON 
{
  "buyerState": string,
  "buyerCountry": string,
  "buyerPostcode": string
}
Pola
buyerState

string

Najwyższy poziom podziału administracyjnego kraju adresu kupującego. Gdy Google jest sprzedawcą w przypadku zamówienia, te informacje nie są uwzględniane.
buyerCountry

string

Dwuliterowy kod kraju zgodny z normą ISO-3166-1 alfa-2 (kody krajów ONZ).
buyerPostcode

string

Kod pocztowy adresu. Gdy Google jest sprzedawcą w przypadku zamówienia, te informacje nie są uwzględniane.

OrderDetails

Szczegółowe informacje o zamówieniu w momencie jego utworzenia.

Zapis JSON 
{
  "taxInclusive": boolean
}
Pola
taxInclusive

boolean

Wskazuje, czy podana cena zawierała podatek.

LineItem

Szczegóły elementu zamówienia.

Zapis JSON 
{
  "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.
}
Pola
productTitle

string

Nazwa produktu określona przez dewelopera. Wyświetlana w języku kupującego. Przykład: monety, subskrypcja miesięczna itp.
productId

string

Identyfikator zakupionego produktu lub kod SKU w aplikacji (np. „monthly001” lub „com.some.thing.inapp1”).
listingPrice

object (Money)

Cena produktu w Sklepie Play. Może zawierać podatek lub nie. Nie uwzględnia rabatów ani promocji.
total

object (Money)

Łączna kwota zapłacona przez użytkownika za ten element zamówienia z uwzględnieniem rabatów i podatku.
tax

object (Money)

Podatek zapłacony za ten element zamówienia.

Pole zbiorcze details.

Pole details może mieć tylko jedną z tych wartości:
oneTimePurchaseDetails

object (OneTimePurchaseDetails)

Szczegóły jednorazowego zakupu.
subscriptionDetails

object (SubscriptionDetails)

Szczegóły zakupu subskrypcji.
paidAppDetails

object (PaidAppDetails)

Szczegóły zakupu płatnej aplikacji.

OneTimePurchaseDetails

Szczegóły jednorazowego zakupu.

Zapis JSON 
{
  "quantity": integer,
  "offerId": string,
  "purchaseOptionId": string,
  "preorderDetails": {
    object (PreorderDetails)
  "rentalDetails": {
    object (RentalDetails)
  }
}
Pola
quantity

integer

Liczba kupionych produktów (w przypadku zakupu większej liczby produktów).
offerId

string

Identyfikator oferty zakupu jednorazowego.
purchaseOptionId

string

Identyfikator opcji zakupu. To pole jest ustawione zarówno dla opcji zakupu, jak i ofert wariantów. W przypadku opcji zakupu ten identyfikator określa samą opcję zakupu. W przypadku ofert wariantowych ten identyfikator odnosi się do powiązanej opcji zakupu i w połączeniu z offerId identyfikuje ofertę wariantową.
preorderDetails

object (PreorderDetails)

Szczegóły zamówienia w przedsprzedaży. Ustaw tylko wtedy, gdy jest to zakup w przedsprzedaży.
rentalDetails

object (RentalDetails)

Szczegóły zakupu wypożyczenia. Ustawiana tylko w przypadku zakupu wypożyczenia.

PreorderDetails

Ten typ nie ma pól.

Szczegóły zakupu w przedsprzedaży.

RentalDetails

Ten typ nie ma pól.

Szczegóły zakupu wypożyczenia.

SubscriptionDetails

Szczegóły zakupu subskrypcji.

Zapis JSON 
{
  "basePlanId": string,
  "offerId": string,
  "offerPhase": enum (OfferPhase),
  "servicePeriodStartTime": string,
  "servicePeriodEndTime": string
}
Pola
basePlanId

string

Identyfikator abonamentu podstawowego.
offerId

string

Identyfikator oferty bieżącej subskrypcji.
offerPhase

enum (OfferPhase)

Etap cenowy okresu rozliczeniowego finansowanego przez to zamówienie.
servicePeriodStartTime

string (Timestamp format)

Początek okresu rozliczeniowego finansowanego przez to zamówienie. Jest to moment rozpoczęcia okresu rozliczeniowego lub okresu świadczenia usług w chwili przetwarzania zamówienia. Należy go używać tylko do celów księgowych.

Korzysta ze standardu RFC 3339, w którym wygenerowane dane wyjściowe są zawsze znormalizowane do formatu Z i zawierają 0, 3, 6 lub 9 cyfr po przecinku. Akceptowane są też przesunięcia inne niż „Z”. Przykłady: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" lub "2014-10-02T15:01:23+05:30".
servicePeriodEndTime

string (Timestamp format)

Koniec okresu rozliczeniowego finansowanego przez to zamówienie. Jest to zrzut czasu zakończenia okresu rozliczeniowego lub okresu świadczenia usługi w momencie przetwarzania zamówienia. Należy go używać tylko do celów księgowych. Aby uzyskać aktualny czas zakończenia okresu subskrypcji, użyj metody purchases.subscriptionsv2.get.

Korzysta ze standardu RFC 3339, w którym wygenerowane dane wyjściowe są zawsze znormalizowane do formatu Z i zawierają 0, 3, 6 lub 9 cyfr po przecinku. Akceptowane są też przesunięcia inne niż „Z”. Przykłady: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" lub "2014-10-02T15:01:23+05:30".

OfferPhase

Etap cenowy okresu uprawnień finansowanego przez to zamówienie.

Wartości w polu enum
OFFER_PHASE_UNSPECIFIED Nieokreślona faza oferty. Ta wartość nie jest używana.
BASE Zamówienie finansuje okres ceny podstawowej.
INTRODUCTORY Zamówienie finansuje okres ceny dla nowych subskrybentów.
FREE_TRIAL Zamówienie finansuje bezpłatny okres próbny.

PaidAppDetails

Ten typ nie ma pól.

Szczegóły zakupu płatnej aplikacji.

OrderHistory

Szczegóły zdarzeń, które zmodyfikowały zamówienie.

Zapis JSON 
{
  "partialRefundEvents": [
    {
      object (PartialRefundEvent)
    }
  ],
  "processedEvent": {
    object (ProcessedEvent)
  },
  "cancellationEvent": {
    object (CancellationEvent)
  },
  "refundEvent": {
    object (RefundEvent)
  }
}
Pola
partialRefundEvents[]

object (PartialRefundEvent)

Szczegóły zdarzeń związanych z częściowym zwrotem środków za to zamówienie.
processedEvent

object (ProcessedEvent)

Szczegóły dotyczące czasu realizacji zamówienia.
cancellationEvent

object (CancellationEvent)

Szczegóły anulowania zamówienia.
refundEvent

object (RefundEvent)

Szczegóły dotyczące pełnego zwrotu środków za zamówienie.

ProcessedEvent

Szczegóły dotyczące czasu realizacji zamówienia.

Zapis JSON 
{
  "eventTime": string
}
Pola
eventTime

string (Timestamp format)

Czas przetworzenia zamówienia.

Korzysta ze standardu RFC 3339, w którym wygenerowane dane wyjściowe są zawsze znormalizowane do formatu Z i zawierają 0, 3, 6 lub 9 cyfr po przecinku. Akceptowane są też przesunięcia inne niż „Z”. Przykłady: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" lub "2014-10-02T15:01:23+05:30".

CancellationEvent

Szczegóły anulowania zamówienia.

Zapis JSON 
{
  "eventTime": string
}
Pola
eventTime

string (Timestamp format)

Data i godzina anulowania zamówienia.

Korzysta ze standardu RFC 3339, w którym wygenerowane dane wyjściowe są zawsze znormalizowane do formatu Z i zawierają 0, 3, 6 lub 9 cyfr po przecinku. Akceptowane są też przesunięcia inne niż „Z”. Przykłady: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" lub "2014-10-02T15:01:23+05:30".

RefundEvent

Szczegóły dotyczące pełnego zwrotu środków za zamówienie.

Zapis JSON 
{
  "eventTime": string,
  "refundDetails": {
    object (RefundDetails)
  },
  "refundReason": enum (RefundReason)
}
Pola
eventTime

string (Timestamp format)

Data i godzina pełnego zwrotu środków za zamówienie.

Korzysta ze standardu RFC 3339, w którym wygenerowane dane wyjściowe są zawsze znormalizowane do formatu Z i zawierają 0, 3, 6 lub 9 cyfr po przecinku. Akceptowane są też przesunięcia inne niż „Z”. Przykłady: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" lub "2014-10-02T15:01:23+05:30".
refundDetails

object (RefundDetails)

Szczegóły pełnego zwrotu środków.
refundReason

enum (RefundReason)

Powód zwrotu środków za zamówienie.

RefundDetails

Szczegóły dotyczące częściowego lub pełnego zwrotu środków.

Zapis JSON 
{
  "total": {
    object (Money)
  },
  "tax": {
    object (Money)
  }
}
Pola
total

object (Money)

łączna kwota zwrotu środków, w tym podatek;
tax

object (Money)

Kwota zwróconego podatku.

RefundReason

Powód zwrotu środków za zamówienie.

Wartości w polu enum
REFUND_REASON_UNSPECIFIED orders.refund reason unspecified. Ta wartość nie jest używana.
OTHER Zwrot środków został przyznany z innego powodu niż wymienione tutaj.
CHARGEBACK Zamówienie zostało obciążone zwrotnie.

PartialRefundEvent

Szczegóły zdarzeń związanych z częściowym zwrotem środków za to zamówienie.

Zapis JSON 
{
  "createTime": string,
  "processTime": string,
  "state": enum (State),
  "refundDetails": {
    object (RefundDetails)
  }
}
Pola
createTime

string (Timestamp format)

Czas utworzenia częściowego zwrotu środków.

Korzysta ze standardu RFC 3339, w którym wygenerowane dane wyjściowe są zawsze znormalizowane do formatu Z i zawierają 0, 3, 6 lub 9 cyfr po przecinku. Akceptowane są też przesunięcia inne niż „Z”. Przykłady: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" lub "2014-10-02T15:01:23+05:30".
processTime

string (Timestamp format)

Czas przetworzenia częściowego zwrotu środków.

Korzysta ze standardu RFC 3339, w którym wygenerowane dane wyjściowe są zawsze znormalizowane do formatu Z i zawierają 0, 3, 6 lub 9 cyfr po przecinku. Akceptowane są też przesunięcia inne niż „Z”. Przykłady: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" lub "2014-10-02T15:01:23+05:30".
state

enum (State)

Stan częściowego zwrotu środków.
refundDetails

object (RefundDetails)

Szczegóły częściowego zwrotu środków.

Stan

Stan częściowego zwrotu środków.

Wartości w polu enum
STATE_UNSPECIFIED Stan nieokreślony. Ta wartość nie jest używana.
PENDING Częściowy zwrot środków został utworzony, ale nie został jeszcze przetworzony.
PROCESSED_SUCCESSFULLY Częściowy zwrot środków został zrealizowany.

PointsDetails

Szczegóły dotyczące punktów Play zastosowanych w zamówieniu.

Zapis JSON 
{
  "pointsOfferId": string,
  "pointsCouponValue": {
    object (Money)
  },
  "pointsDiscountRateMicros": string,
  "pointsSpent": string
}
Pola
pointsOfferId

string

Unikalny identyfikator oferty punktów Play użytej w tym zamówieniu.
pointsCouponValue

object (Money)

Wartość pieniężna kuponu Play Points. Jest to rabat zapewniany przez kupon, który może nie być kwotą całkowitą. Ustawiana tylko wtedy, gdy użyto kuponów w Play Points. Np. w przypadku kuponu na 100 punktów za 2 zł jest to 2 zł.
pointsDiscountRateMicros

string (int64 format)

Wartość procentowa, o którą promocja w Play Points obniża koszt. Np. w przypadku kuponu na 100 punktów za 2 zł jest to 500 tys. Szacunkowa liczba punktów za 2 PLN wynosi 200, ale rzeczywista liczba punktów, czyli 100, to 50% tej wartości, a 50% w mikro to 500 000. Od 0 do 1 000 000.
pointsSpent

string (int64 format)

Liczba punktów Play zastosowanych w tym zamówieniu. Np. w przypadku kuponu na 100 punktów za 2 zł jest to 100. W przypadku kuponu połączonego z ofertą podstawową jest to łączna liczba punktów wydanych na obie oferty.

Metody

batchget

 Wyświetlanie szczegółów zamówienia dla listy zamówień.

get

 Wyświetlanie szczegółów pojedynczego zamówienia.

refund

 Zwraca środki za subskrypcję lub zamówienie zakupu w aplikacji.

Kody błędów

Operacje na tym zasobie zwracają te kody błędów HTTP:

Kod błędu Przyczyna Rozdzielczość
5xx Ogólny błąd serwera Google Play. Ponów żądanie.

Jeśli problem nie ustąpi, skontaktuj się z menedżerem konta Google Play lub prześlij prośbę o pomoc. Sprawdź Panel stanu Google Play, aby dowiedzieć się, czy występują znane awarie.
409 Błąd aktualizacji współbieżnej.

Podjęto próbę zaktualizowania obiektu, który jest aktualizowany. Na przykład zakup jest potwierdzany przez jednoczesne wywołanie metody acknowledgePurchase() Biblioteki płatności w Play i metody purchases.products.acknowledge interfejsu Play Developer API.

 Ponów żądanie.