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)

Czas 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ść punktowa.

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 czeka 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. Jeśli Google jest sprzedawcą w przypadku zamówienia, te informacje nie są uwzględniane.
buyerCountry

string

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

string

Kod pocztowy adresu. Jeśli 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 w przypadku 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. Ustawiane 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),
  "offerPhaseDetails": {
    object (OfferPhaseDetails)
  },
  "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. Rola wycofana. Zamiast tego użyj offerPhaseDetails.
offerPhaseDetails

object (OfferPhaseDetails)

Szczegóły etapu cenowego w okresie uprawnień finansowanym 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 ekranu z godziną zakończenia okresu rozliczeniowego lub okresu świadczenia usługi w momencie przetwarzania zamówienia. Należy go używać wyłącznie 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.

OfferPhaseDetails

Szczegóły etapu cenowego w okresie uprawnień finansowanym przez to zamówienie.

Zapis JSON 
{

  // 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.
}
Pola
Pole zbiorcze phase_details. Szczegóły fazy cenowej. phase_details może mieć tylko jedną z tych wartości:
freeTrialDetails

object (FreeTrialDetails)

Zamówienie finansuje bezpłatny okres próbny.
introductoryPriceDetails

object (IntroductoryPriceDetails)

Zamówienie finansuje okres ceny dla nowych subskrybentów.
baseDetails

object (BaseDetails)

Zamówienie finansuje okres ceny podstawowej.
prorationPeriodDetails

object (ProrationPeriodDetails)

Zamówienie finansuje okres proporcjonalny.

FreeTrialDetails

Ten typ nie ma pól.

Szczegóły etapu cenowego bezpłatnego okresu próbnego.

IntroductoryPriceDetails

Ten typ nie ma pól.

Szczegóły etapu cenowego ceny dla nowych użytkowników.

BaseDetails

Ten typ nie ma pól.

Szczegóły fazy cenowej ceny podstawowej.

ProrationPeriodDetails

Szczegóły okresu proporcjonalnego.

Okres proporcjonalny może być okresem obliczanym podczas zmiany planu w celu pokrycia istniejących uprawnień (więcej informacji znajdziesz w artykule Umożliwianie użytkownikom przejścia na wyższą lub niższą wersję subskrypcji albo zmiany subskrypcji) lub okresem proporcjonalnym, który ma na celu dostosowanie dat odnowienia dodatków do dat odnowienia subskrypcji podstawowej (więcej informacji znajdziesz w artykule Zasady dotyczące elementów zakupu).

Zapis JSON 
{
  "originalOfferPhase": enum (OfferPhase),
  "linkedOrderId": string
}
Pola
originalOfferPhase

enum (OfferPhase)

Reprezentuje pierwotną fazę oferty z zakupionego elementu zamówienia, jeśli okres proporcjonalny obejmuje którąkolwiek z nich. Na przykład okres proporcjonalny wynikający ze zmiany planu CHARGE_FULL_PRICE może zostać połączony z pierwszą fazą oferty subskrypcji nowego produktu kupionego przez użytkownika. W takim przypadku zostanie tu ustawiona pierwotna faza oferty.
linkedOrderId

string

Ostatni identyfikator zamówienia pierwotnej subskrypcji przed zmianą abonamentu. To pole jest wypełniane tylko wtedy, gdy okres proporcjonalny wynika z przejścia na wyższą lub niższą wersję poprzedniej subskrypcji i obejmuje pozostałą fazę oferty z połączonego zamówienia poprzedniej subskrypcji.

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 w przypadku tego zamówienia.

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ą. Ustawiane tylko wtedy, gdy wykorzystano kupony 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 000. 2 PLN to szacunkowo 200 punktów, ale rzeczywista liczba punktów, czyli 100, to 50% tej wartości, a 50% w mikrojednostkach 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ówień z 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 tego zasobu 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.