REST Resource: orders

Ресурс: Заказ

Ресурс «Заказ» содержит исчерпывающую информацию о транзакции, совершенной в Google Play. Он включает в себя множество атрибутов, предоставляющих подробную информацию о самом заказе, приобретенных товарах и истории событий, связанных с заказом.

API заказов предоставляют доступ к данным ваших заказов в режиме реального времени в экосистеме Google Play. Вы можете получать подробную информацию и метаданные как для разовых, так и для повторяющихся заказов, включая детали транзакций, такие как списания, налоги и возвраты, а также метаданные, например, этапы ценообразования для подписок. API заказов позволяют автоматизировать задачи, связанные с управлением заказами, уменьшая необходимость в ручной проверке через консоль разработчика Play.

Ниже приведены некоторые варианты использования этого API:

  • Получение данных о заказе в режиме реального времени — orders.get: подробная информация о заказе и метаданные сразу после покупки с использованием идентификатора заказа.

  • Синхронизация обновлений заказов — Периодически синхронизируйте обновления заказов, чтобы поддерживать актуальную информацию о заказах.

Примечание:

  • Вызовы API заказов учитываются в вашей квоте API для разработчиков Play, которая по умолчанию составляет 200 000 в день, и этого может быть недостаточно для синхронизации обширной истории заказов.

  • За один запрос можно получить максимум 1000 заказов. Для минимизации использования квоты рекомендуется использовать страницы большего размера. Проверьте свою квоту в облачной консоли и при необходимости запросите дополнительную.

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)
  },
   "salesChannel": enum (SalesChannel)
}
Поля
lineItems[]

object ( LineItem )

Отдельные позиции, составляющие этот заказ.

orderId

string

Идентификатор заказа.

purchaseToken

string

Токен, предоставленный устройству пользователя при покупке подписки или товара.

state

enum ( State )

Состояние порядка.

createTime

string ( Timestamp format)

Время создания заказа.

Используется RFC 3339, согласно которому генерируемый вывод всегда будет Z-нормализован и будет содержать 0, 3, 6 или 9 дробных знаков. Допускаются также смещения, отличные от "Z". Примеры: "2014-10-02T15:01:23Z" , "2014-10-02T15:01:23.045123456Z" или "2014-10-02T15:01:23+05:30" .

lastEventTime

string ( Timestamp format)

Время последнего события, произошедшего в рамках данного заказа.

Используется RFC 3339, согласно которому генерируемый вывод всегда будет Z-нормализован и будет содержать 0, 3, 6 или 9 дробных знаков. Допускаются также смещения, отличные от "Z". Примеры: "2014-10-02T15:01:23Z" , "2014-10-02T15:01:23.045123456Z" или "2014-10-02T15:01:23+05:30" .

buyerAddress

object ( BuyerAddress )

Адресная информация клиента используется для расчета налогов. Если Google является официальным продавцом заказа, отображается только страна.

total

object ( Money )

Окончательная сумма, уплаченная клиентом, с учетом скидок и налогов.

tax

object ( Money )

Общая сумма налога, уплаченного в рамках данного распоряжения.

orderDetails

object ( OrderDetails )

Подробная информация о заказе на момент его создания.

orderHistory

object ( OrderHistory )

Подробности о событиях, изменивших порядок.

developerRevenueInBuyerCurrency

object ( Money )

Ваш доход от этого заказа в валюте покупателя, включая вычеты частичных возвратов, налогов и сборов. Google вычитает стандартные комиссионные сборы и сборы третьих сторон с каждой продажи, включая НДС в некоторых регионах.

pointsDetails

object ( PointsDetails )

Бонусные баллы начисляются на заказ, включая информацию о предложении, размере скидки и стоимости баллов.

salesChannel

enum ( SalesChannel )

Канал сбыта, через который был оформлен заказ.

Состояние

Состояние порядка.

Перечисления
STATE_UNSPECIFIED Штат не указан. Это значение не используется.
PENDING Заказ создан и ожидает обработки.
PROCESSED Заказ успешно обработан.
CANCELED Заказ был отменен до обработки.
PENDING_REFUND Запрос на возврат средств ожидает обработки.
PARTIALLY_REFUNDED Часть суммы заказа была возвращена.
REFUNDED Полная сумма заказа была возвращена.

Адрес покупателя

Адресная информация клиента для использования при расчете налогов.

JSON-представление 
{
  "buyerState": string,
  "buyerCountry": string,
  "buyerPostcode": string
}
Поля
buyerState

string

Административное деление верхнего уровня страны, в которой находится адрес покупателя. Если Google является официальным продавцом заказа, эта информация не включается.

buyerCountry

string

Двухбуквенный код страны, основанный на стандарте ISO-3166-1 Alpha-2 (коды стран ООН).

buyerPostcode

string

Почтовый индекс адреса. Если Google является официальным продавцом заказа, эта информация не включается.

Детали заказа

Подробная информация о заказе на момент его создания.

JSON-представление 
{
  "taxInclusive": boolean
}
Поля
taxInclusive

boolean

Указывает, включает ли указанная цена налоги или нет.

Позиция

Подробности по позиции.

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.
}
Поля
productTitle

string

Название продукта, указанное разработчиком. Отображается в языке покупателя. Пример: монеты, ежемесячная подписка и т. д.

productId

string

Идентификатор приобретенного продукта или артикул в приложении (например, 'monthly001' или 'com.some.thing.inapp1').

listingPrice

object ( Money )

Указанная цена товара в Play Store может включать или не включать налог. Не включает скидки и акции.

total

object ( Money )

Общая сумма, уплаченная пользователем за данную позицию, с учетом скидок и налогов.

tax

object ( Money )

Налог, уплаченный по данной статье расходов.

details о поле Союза.

details могут быть только одним из следующих вариантов:

oneTimePurchaseDetails

object ( OneTimePurchaseDetails )

Подробности разовой покупки.

subscriptionDetails

object ( SubscriptionDetails )

Подробности покупки подписки.

paidAppDetails

object ( PaidAppDetails )

Подробности о платной покупке приложения.

Информация о разовой покупке

Подробности разовой покупки.

JSON-представление 
{
  "quantity": integer,
  "offerId": string,
  "purchaseOptionId": string,
  "preorderDetails": {
    object (PreorderDetails)
  },
  "rentalDetails": {
    object (RentalDetails)
  }
}
Поля
quantity

integer

Количество приобретенных товаров (при покупке нескольких товаров).

offerId

string

Идентификатор предложения разовой покупки.

purchaseOptionId

string

Идентификатор варианта покупки. Это поле устанавливается как для вариантов покупки, так и для вариантов предложений. Для вариантов покупки этот идентификатор обозначает сам вариант покупки. Для вариантов предложений этот идентификатор относится к соответствующему варианту покупки и в сочетании с offerId обозначает вариант предложения.

preorderDetails

object ( PreorderDetails )

Подробности предварительного заказа. Эта информация отображается только в том случае, если это предварительный заказ.

rentalDetails

object ( RentalDetails )

Детали договора аренды с правом выкупа. Устанавливается только в том случае, если это договор аренды с правом выкупа.

Подробности предварительного заказа

Этот тип не содержит полей.

Подробности предварительного заказа.

Информация об аренде

Этот тип не содержит полей.

Подробности договора аренды с правом выкупа.

Подробности подписки

Подробности покупки подписки.

JSON-представление 
{
  "basePlanId": string,
  "offerId": string,
  "offerPhase": enum (OfferPhase),
  "offerPhaseDetails": {
    object (OfferPhaseDetails)
  },
  "servicePeriodStartTime": string,
  "servicePeriodEndTime": string
}
Поля
basePlanId

string

Идентификатор базового тарифного плана подписки.

offerId

string

Идентификатор предложения для текущего варианта подписки.

offerPhase

enum ( OfferPhase )

Этап ценообразования для расчетного периода, финансируемого данным заказом. Устарело. Используйте вместо него offerPhaseDetails.

offerPhaseDetails

object ( OfferPhaseDetails )

Подробная информация о ценообразовании на период действия права на получение финансирования в рамках данного заказа.

servicePeriodStartTime

string ( Timestamp format)

Начало расчетного периода, финансируемого данным заказом. Это моментальный снимок начала расчетного/сервисного периода на момент обработки заказа и должен использоваться только для бухгалтерского учета.

Используется RFC 3339, согласно которому генерируемый вывод всегда будет Z-нормализован и будет содержать 0, 3, 6 или 9 дробных знаков. Допускаются также смещения, отличные от "Z". Примеры: "2014-10-02T15:01:23Z" , "2014-10-02T15:01:23.045123456Z" или "2014-10-02T15:01:23+05:30" .

servicePeriodEndTime

string ( Timestamp format)

Конец расчетного периода, финансируемого этим заказом. Это моментальный снимок времени окончания расчетного/сервисного периода на момент обработки заказа и должен использоваться только для бухгалтерского учета. Чтобы получить текущее время окончания периода подписки, используйте purchases.subscriptionsv2.get.

Используется RFC 3339, согласно которому генерируемый вывод всегда будет Z-нормализован и будет содержать 0, 3, 6 или 9 дробных знаков. Допускаются также смещения, отличные от "Z". Примеры: "2014-10-02T15:01:23Z" , "2014-10-02T15:01:23.045123456Z" или "2014-10-02T15:01:23+05:30" .

Фаза предложения

Этап ценообразования на период действия права на получение льгот, финансируемый данным распоряжением.

Перечисления
OFFER_PHASE_UNSPECIFIED Этап предложения не указан. Это значение не используется.
BASE Данный указ финансирует период действия базовой цены.
INTRODUCTORY Данное распоряжение финансирует период действия льготных цен.
FREE_TRIAL Данное распоряжение предусматривает финансирование бесплатного пробного периода.

Подробности этапа предложения

Подробности этапа ценообразования на период действия права на получение услуг, финансируемый данным заказом.

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.
}
Поля
Поле объединения phase_details . Детали этапа ценообразования. phase_details может принимать только одно из следующих значений:
freeTrialDetails

object ( FreeTrialDetails )

Данное распоряжение предусматривает финансирование бесплатного пробного периода.

introductoryPriceDetails

object ( IntroductoryPriceDetails )

Данное распоряжение финансирует период действия льготных цен.

baseDetails

object ( BaseDetails )

Данный указ финансирует период действия базовой цены.

prorationPeriodDetails

object ( ProrationPeriodDetails )

Данное распоряжение предусматривает финансирование периода пропорционального распределения средств.

Подробности бесплатной пробной версии

Этот тип не содержит полей.

Подробности о ценообразовании в рамках бесплатного пробного периода.

Вводная ценаПодробности

Этот тип не содержит полей.

Подробности вводного этапа ценообразования.

Базовые детали

Этот тип не содержит полей.

Подробности этапа определения базовой цены.

Подробности периода пропорционального распределения

Подробности периода пропорционального распределения.

Период пропорционального начисления может представлять собой период, рассчитываемый при изменении тарифного плана для покрытия существующих прав (подробнее см. раздел «Разрешение пользователям повышать, понижать уровень или изменять свою подписку») , или период пропорционального начисления для согласования дат продления дополнительных услуг с базовыми (подробнее см. раздел «Правила, применимые к товарам в покупке »).

JSON-представление 
{
  "originalOfferPhase": enum (OfferPhase)
}
Поля
originalOfferPhase

enum ( OfferPhase )

Если период пропорционального распределения включает какой-либо из этих периодов, укажите исходный этап предложения, приобретенного по позиции заказа. Например, период пропорционального распределения, связанный с изменением плана CHARGE_FULL_PRICE, может включать первый этап предложения подписки нового продукта, приобретенного пользователем. В этом случае здесь будет указан исходный этап предложения.

PaidAppDetails

Этот тип не содержит полей.

Подробности о платной покупке приложения.

История заказов

Подробности о событиях, изменивших порядок.

JSON-представление 
{
  "partialRefundEvents": [
    {
      object (PartialRefundEvent)
    }
  ],
  "processedEvent": {
    object (ProcessedEvent)
  },
  "cancellationEvent": {
    object (CancellationEvent)
  },
  "refundEvent": {
    object (RefundEvent)
  }
}
Поля
partialRefundEvents[]

object ( PartialRefundEvent )

Подробная информация о частичном возврате средств по данному заказу.

processedEvent

object ( ProcessedEvent )

Подробная информация о времени обработки заказа.

cancellationEvent

object ( CancellationEvent )

Подробности об отмене заказа.

refundEvent

object ( RefundEvent )

Подробная информация о том, когда был произведен полный возврат средств по заказу.

Обработанное событие

Подробная информация о времени обработки заказа.

JSON-представление 
{
  "eventTime": string
}
Поля
eventTime

string ( Timestamp format)

Время обработки заказа.

Используется RFC 3339, согласно которому генерируемый вывод всегда будет Z-нормализован и будет содержать 0, 3, 6 или 9 дробных знаков. Допускаются также смещения, отличные от "Z". Примеры: "2014-10-02T15:01:23Z" , "2014-10-02T15:01:23.045123456Z" или "2014-10-02T15:01:23+05:30" .

Отмена события

Подробности об отмене заказа.

JSON-представление 
{
  "eventTime": string
}
Поля
eventTime

string ( Timestamp format)

Время отмены заказа.

Используется RFC 3339, согласно которому генерируемый вывод всегда будет Z-нормализован и будет содержать 0, 3, 6 или 9 дробных знаков. Допускаются также смещения, отличные от "Z". Примеры: "2014-10-02T15:01:23Z" , "2014-10-02T15:01:23.045123456Z" или "2014-10-02T15:01:23+05:30" .

Возвратное событие

Подробная информация о том, когда был произведен полный возврат средств по заказу.

JSON-представление 
{
  "eventTime": string,
  "refundDetails": {
    object (RefundDetails)
  },
  "refundReason": enum (RefundReason)
}
Поля
eventTime

string ( Timestamp format)

Время, когда заказ был полностью возмещен.

Используется RFC 3339, согласно которому генерируемый вывод всегда будет Z-нормализован и будет содержать 0, 3, 6 или 9 дробных знаков. Допускаются также смещения, отличные от "Z". Примеры: "2014-10-02T15:01:23Z" , "2014-10-02T15:01:23.045123456Z" или "2014-10-02T15:01:23+05:30" .

refundDetails

object ( RefundDetails )

Подробная информация о полном возврате средств.

refundReason

enum ( RefundReason )

Причина возврата средств за заказ.

Информация о возврате средств

Подробная информация о частичном или полном возврате средств.

JSON-представление 
{
  "total": {
    object (Money)
  },
  "tax": {
    object (Money)
  }
}
Поля
total

object ( Money )

Общая сумма возврата, включая налог.

tax

object ( Money )

Сумма возвращенного налога.

Причина возврата средств

Причина возврата средств за заказ.

Перечисления
REFUND_REASON_UNSPECIFIED Причина возврата средств не указана. Это значение не используется.
OTHER Возврат средств за заказ был произведен по причине, отличной от перечисленных здесь.
CHARGEBACK Заказ был аннулирован.

PartialRefundEvent

Подробная информация о частичном возврате средств по данному заказу.

JSON-представление 
{
  "createTime": string,
  "processTime": string,
  "state": enum (State),
  "refundDetails": {
    object (RefundDetails)
  }
}
Поля
createTime

string ( Timestamp format)

Время создания частичного возврата средств.

Используется RFC 3339, согласно которому генерируемый вывод всегда будет Z-нормализован и будет содержать 0, 3, 6 или 9 дробных знаков. Допускаются также смещения, отличные от "Z". Примеры: "2014-10-02T15:01:23Z" , "2014-10-02T15:01:23.045123456Z" или "2014-10-02T15:01:23+05:30" .

processTime

string ( Timestamp format)

Время обработки частичного возврата средств.

Используется RFC 3339, согласно которому генерируемый вывод всегда будет Z-нормализован и будет содержать 0, 3, 6 или 9 дробных знаков. Допускаются также смещения, отличные от "Z". Примеры: "2014-10-02T15:01:23Z" , "2014-10-02T15:01:23.045123456Z" или "2014-10-02T15:01:23+05:30" .

state

enum ( State )

Состояние частичного возврата средств.

refundDetails

object ( RefundDetails )

Подробная информация о частичном возврате средств.

Состояние

Состояние частичного возврата средств.

Перечисления
STATE_UNSPECIFIED Штат не указан. Это значение не используется.
PENDING Частичный возврат средств создан, но еще не обработан.
PROCESSED_SUCCESSFULLY Частичный возврат средств был успешно обработан.

Подробности по пунктам

Подробная информация о начисленных бонусных баллах за заказ.

JSON-представление 
{
  "pointsOfferId": string,
  "pointsCouponValue": {
    object (Money)
  },
  "pointsDiscountRateMicros": string,
  "pointsSpent": string
}
Поля
pointsOfferId

string

Уникальный идентификатор, присвоенный предложению по начислению игровых баллов, используемому для этого заказа.

pointsCouponValue

object ( Money )

Денежная стоимость купона Play Points. Это скидка, предоставляемая купоном, которая может не совпадать с общей суммой. Устанавливается только после использования купонов Play Points. Например, для купона на 100 баллов за 2 доллара это будет 2 доллара.

pointsDiscountRateMicros

string ( int64 format)

Процентная ставка, на которую акция Play Points снижает стоимость. Например, для купона на 100 баллов за 2 доллара это составляет 500 000. Поскольку 2 доллара примерно равны 200 баллам, а фактически необходимо 100 баллов, это составляет 50% от этой суммы, а 50% в микро-суммах — это 500 000. Диапазон значений: от 0 до 1 000 000.

pointsSpent

string ( int64 format)

Количество начисленных бонусных баллов в указанном порядке. Например, для купона на 100 баллов за 2 доллара это 100. Для купона, суммированного с базовым предложением, это общее количество баллов, потраченных по обоим предложениям.

Канал продаж

Канал сбыта, через который был оформлен заказ.

Перечисления
SALES_CHANNEL_UNSPECIFIED Канал продаж не указан. Это значение не используется.
IN_APP Стандартные заказы, инициированные через приложение.
PC_EMULATOR Заказы, оформленные через эмулятор ПК для совершения покупок внутри приложения.
NATIVE_PC Заказы, оформленные через нативное приложение для ПК, предназначены для внутриигровых покупок.
PLAY_STORE Заказы оформляются через магазин Google Play.
OUTSIDE_PLAY_STORE Заказы, оформленные вне магазина Google Play.

Методы

batchget

 Получите подробную информацию о заказе из списка заказов.

get

 Получить подробную информацию по одному заказу.

refund

 Осуществляет возврат средств пользователю за подписку или покупку внутри приложения.

коды ошибок

При работе с этим ресурсом возвращаются следующие коды ошибок HTTP:

Код ошибки Причина Разрешение
5xx Общая ошибка на сервере Google Play. Повторите запрос.

Если проблема не исчезнет, ​​обратитесь к своему менеджеру аккаунта Google Play или отправьте запрос в службу поддержки. Рекомендуем проверить панель состояния Play на наличие известных сбоев.

409 Ошибка обновления параллельного доступа.

Была предпринята попытка обновить объект, который и так обновляется. Например, подтверждение покупки осуществляется путем одновременного вызова метода acknowledgePurchase() библиотеки Play Billing и метода purchases.products.acknowledge API разработчиков Play.

 Повторите запрос.