REST Resource: orders

Recurso: Order

O recurso "Order" encapsula informações abrangentes sobre uma transação feita no Google Play. Ele inclui vários atributos que fornecem detalhes sobre o pedido, os produtos comprados e o histórico de eventos relacionados ao pedido.

As APIs Orders oferecem acesso em tempo real aos dados de pedidos no ecossistema do Google Play. É possível recuperar informações detalhadas e metadados de pedidos únicos e recorrentes, incluindo detalhes da transação, como cobranças, tributos e reembolsos, além de metadados, como fases de preços para assinaturas. Com as APIs Orders, é possível automatizar tarefas relacionadas ao gerenciamento de pedidos, reduzindo a necessidade de verificações manuais no Play Console.

Confira a seguir alguns casos de uso dessa API:

  • Recuperação de dados de pedidos em tempo real: "orders.get" detalhes e metadados de um pedido imediatamente após uma compra usando um ID de pedido.

  • Sincronização de atualizações de pedidos: sincronize periodicamente as atualizações de pedidos para manter um registro atualizado das informações.

Observação:

  • As chamadas da API Orders contam para sua cota da API Google Play Developer, que é de 200 mil por dia por padrão e pode ser insuficiente para sincronizar históricos de pedidos extensos.

  • É possível recuperar até 1.000 pedidos por chamada. Recomendamos usar tamanhos de página maiores para minimizar o uso da cota. Verifique sua cota no Console do Cloud e peça mais se necessário.

Representação 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)
  }
}
Campos
lineItems[]

object (LineItem)

Os itens de linha individuais que compõem este pedido.
orderId

string

O ID do pedido.
purchaseToken

string

O token enviado ao dispositivo do usuário no momento da compra da assinatura ou do item.
state

enum (State)

O estado do pedido.
createTime

string (Timestamp format)

A data e a hora em que o pedido foi criado.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
lastEventTime

string (Timestamp format)

A data e o horário do último evento ocorrido no pedido.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
buyerAddress

object (BuyerAddress)

Informações de endereço do cliente que serão usadas no cálculo dos tributos. Quando o Google é o comerciante responsável pelo processamento do pedido, somente o país é exibido.
total

object (Money)

O valor final pago pelo cliente, considerando descontos e tributos.
tax

object (Money)

O valor total dos tributos pagos como parte deste pedido.
orderDetails

object (OrderDetails)

Informações detalhadas sobre o pedido no momento da criação.
orderHistory

object (OrderHistory)

Detalhes sobre eventos que mudaram o pedido.
developerRevenueInBuyerCurrency

object (Money)

É a receita deste pedido na moeda do comprador, incluindo deduções de reembolsos parciais, tributos e taxas. O Google deduz as taxas padrão de transação e de terceiros de cada venda, incluindo o IVA em algumas regiões.
pointsDetails

object (PointsDetails)

Pontos do Play Points aplicados ao pedido, incluindo informações da oferta, taxa de desconto e valores dos pontos.

Estado

O estado do pedido.

Tipos enumerados
STATE_UNSPECIFIED Estado não especificado. Esse valor não é usado.
PENDING O pedido foi criado e está aguardando processamento.
PROCESSED O pedido foi processado.
CANCELED O pedido foi cancelado antes de ser processado.
PENDING_REFUND O reembolso solicitado está aguardando processamento.
PARTIALLY_REFUNDED Parte do valor do pedido foi reembolsada.
REFUNDED O valor total do pedido foi reembolsado.

BuyerAddress

Informações de endereço do cliente que serão usadas no cálculo dos tributos.

Representação JSON 
{
  "buyerState": string,
  "buyerCountry": string,
  "buyerPostcode": string
}
Campos
buyerState

string

Subdivisão administrativa de nível superior do país do comprador. Quando o Google é o comerciante responsável pelo processamento do pedido, essa informação não é incluída.
buyerCountry

string

Código do país de duas letras baseado no ISO-3166-1 Alpha-2 (códigos do país da ONU).
buyerPostcode

string

Código postal de um endereço. Quando o Google é o comerciante responsável pelo processamento do pedido, essa informação não é incluída.

OrderDetails

Informações detalhadas sobre o pedido no momento da criação.

Representação JSON 
{
  "taxInclusive": boolean
}
Campos
taxInclusive

boolean

Indica se o preço de tabela incluía tributos ou não.

LineItem

Detalhes de um item de linha.

Representação 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.
}
Campos
productTitle

string

É o nome do produto criado pelo desenvolvedor. Exibido na localidade do comprador. Exemplo: moedas, assinatura mensal etc.
productId

string

O ID ou SKU no app do produto comprado. Por exemplo, "monthly001" ou "com.some.thing.inapp1".
listingPrice

object (Money)

Preço de tabela do item na Play Store, que pode incluir tributos ou não. O valor não inclui descontos nem promoções.
total

object (Money)

O valor total pago pelo usuário por este item de linha, considerando descontos e tributos.
tax

object (Money)

Os tributos pagos por este item de linha.

Campo de união details.

details pode ser apenas de um dos tipos a seguir:
oneTimePurchaseDetails

object (OneTimePurchaseDetails)

Detalhes de uma compra única.
subscriptionDetails

object (SubscriptionDetails)

Detalhes da compra de uma assinatura.
paidAppDetails

object (PaidAppDetails)

Detalhes da compra de um app pago.

OneTimePurchaseDetails

Detalhes de uma compra única.

Representação JSON 
{
  "quantity": integer,
  "offerId": string,
  "purchaseOptionId": string,
  "preorderDetails": {
    object (PreorderDetails)
  },
  "rentalDetails": {
    object (RentalDetails)
  }
}
Campos
quantity

integer

O número de itens comprados (para compras de vários itens).
offerId

string

O ID da oferta de compra única.
purchaseOptionId

string

ID da opção de compra. Esse campo é definido para opções de compra e ofertas de variantes. Para opções de compra, esse ID identifica a opção de compra em si. Para ofertas de variantes, esse ID se refere à opção de compra associada e, junto com "offerId", identifica a oferta de variante.
preorderDetails

object (PreorderDetails)

Os detalhes de uma pré-venda. Definido somente se a compra for em pré-venda.
rentalDetails

object (RentalDetails)

Os detalhes de uma compra de aluguel. Definido somente se a compra for de um aluguel.

PreorderDetails

Esse tipo não tem campos.

Detalhes de uma compra em pré-venda.

RentalDetails

Esse tipo não tem campos.

Detalhes de uma compra de locação.

SubscriptionDetails

Detalhes da compra de uma assinatura.

Representação JSON 
{
  "basePlanId": string,
  "offerId": string,
  "offerPhase": enum (OfferPhase),
  "offerPhaseDetails": {
    object (OfferPhaseDetails)
  },
  "servicePeriodStartTime": string,
  "servicePeriodEndTime": string
}
Campos
basePlanId

string

O ID do plano básico da assinatura.
offerId

string

O ID da oferta de assinatura atual.
offerPhase

enum (OfferPhase)

A etapa de precificação referente ao período de faturamento coberto por esse pedido. Obsoleto. Use offerPhaseDetails.
offerPhaseDetails

object (OfferPhaseDetails)

Os detalhes da fase de precificação referente ao período de direito coberto por esse pedido.
servicePeriodStartTime

string (Timestamp format)

O início do período de faturamento coberto por esse pedido. Um resumo do horário de início do período de faturamento/serviço no momento em que o pedido foi processado. Deve ser usado apenas para contabilização.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
servicePeriodEndTime

string (Timestamp format)

O fim do período de faturamento coberto nesse pedido. Um resumo do horário de término do período de faturamento/serviço no momento em que o pedido foi processado. Deve ser usado apenas para contabilização. Para saber o horário de término atual do período de serviço da assinatura, use purchases.subscriptionsv2.get.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

OfferPhase

A etapa de precificação referente ao período de direito coberto por esse pedido.

Tipos enumerados
OFFER_PHASE_UNSPECIFIED Fase da oferta não especificada. Esse valor não é usado.
BASE O pedido cobre um período de preço base.
INTRODUCTORY O pedido cobre um período de preço inicial.
FREE_TRIAL O pedido cobre um período de teste sem custo financeiro.

OfferPhaseDetails

Detalhes de uma fase de preços para o período de direito coberto por este pedido.

Representação 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.
}
Campos
Campo de união phase_details. Os detalhes da fase de preços. phase_details pode ser apenas de um dos tipos a seguir:
freeTrialDetails

object (FreeTrialDetails)

O pedido cobre um período de teste sem custo financeiro.
introductoryPriceDetails

object (IntroductoryPriceDetails)

O pedido cobre um período de preço inicial.
baseDetails

object (BaseDetails)

O pedido cobre um período de preço base.
prorationPeriodDetails

object (ProrationPeriodDetails)

O pedido cobre um período de rateio.

FreeTrialDetails

Esse tipo não tem campos.

Detalhes de uma fase de preços de teste sem custo financeiro.

IntroductoryPriceDetails

Esse tipo não tem campos.

Detalhes de uma fase de preço inicial.

BaseDetails

Esse tipo não tem campos.

Detalhes de uma fase de preços de preço base.

ProrationPeriodDetails

Detalhes de um período de rateio.

Um período de rateio pode ser calculado durante uma mudança de plano para cobrir direitos de acesso atuais (para mais informações, consulte Permitir que os usuários façam upgrade, downgrade ou mudem a assinatura) ou um período proporcional para alinhar as datas de renovação de complementos com a assinatura básica (para mais informações, consulte Regras aplicáveis a itens na compra).

Representação JSON 
{
  "originalOfferPhase": enum (OfferPhase),
  "linkedOrderId": string
}
Campos
originalOfferPhase

enum (OfferPhase)

Representa a fase da oferta original do item de linha comprado se o período de rateio contiver alguma delas. Por exemplo, um período de rateio de uma mudança de plano CHARGE_FULL_PRICE pode mesclar a primeira fase da oferta de assinatura do novo produto comprado pelo usuário. Nesse caso, a fase da oferta original será definida aqui.
linkedOrderId

string

O ID do último pedido da compra da assinatura original antes da mudança de plano. Só será preenchido se esse período proporcional for de um upgrade/downgrade de uma assinatura anterior e tiver a fase restante da oferta do pedido vinculado da assinatura anterior.

PaidAppDetails

Esse tipo não tem campos.

Detalhes da compra de um app pago.

OrderHistory

Detalhes sobre eventos que mudaram o pedido.

Representação JSON 
{
  "partialRefundEvents": [
    {
      object (PartialRefundEvent)
    }
  ],
  "processedEvent": {
    object (ProcessedEvent)
  },
  "cancellationEvent": {
    object (CancellationEvent)
  },
  "refundEvent": {
    object (RefundEvent)
  }
}
Campos
partialRefundEvents[]

object (PartialRefundEvent)

Detalhes dos eventos de reembolso parcial deste pedido.
processedEvent

object (ProcessedEvent)

Detalhes de quando o pedido foi processado.
cancellationEvent

object (CancellationEvent)

Detalhes de quando o pedido foi cancelado.
refundEvent

object (RefundEvent)

Detalhes de quando o pedido foi totalmente reembolsado.

ProcessedEvent

Detalhes de quando o pedido foi processado.

Representação JSON 
{
  "eventTime": string
}
Campos
eventTime

string (Timestamp format)

A data e a hora do processamento do pedido.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

CancellationEvent

Detalhes de quando o pedido foi cancelado.

Representação JSON 
{
  "eventTime": string
}
Campos
eventTime

string (Timestamp format)

A data e o horário do cancelamento do pedido.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

RefundEvent

Detalhes de quando o pedido foi totalmente reembolsado.

Representação JSON 
{
  "eventTime": string,
  "refundDetails": {
    object (RefundDetails)
  },
  "refundReason": enum (RefundReason)
}
Campos
eventTime

string (Timestamp format)

A data e o horário do reembolso total do pedido.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
refundDetails

object (RefundDetails)

Detalhes do reembolso total.
refundReason

enum (RefundReason)

O motivo do reembolso do pedido.

RefundDetails

Detalhes de um reembolso parcial ou total.

Representação JSON 
{
  "total": {
    object (Money)
  },
  "tax": {
    object (Money)
  }
}
Campos
total

object (Money)

O valor total reembolsado, com tributos.
tax

object (Money)

O valor dos tributos reembolsados.

RefundReason

O motivo do reembolso do pedido.

Tipos enumerados
REFUND_REASON_UNSPECIFIED O motivo do reembolso do pedido não foi especificado. Esse valor não é usado.
OTHER O pedido foi reembolsado por um motivo que não foi listado aqui.
CHARGEBACK O pedido foi estornado.

PartialRefundEvent

Detalhes dos eventos de reembolso parcial deste pedido.

Representação JSON 
{
  "createTime": string,
  "processTime": string,
  "state": enum (State),
  "refundDetails": {
    object (RefundDetails)
  }
}
Campos
createTime

string (Timestamp format)

A data e o horário em que o reembolso parcial foi criado.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
processTime

string (Timestamp format)

A data e o horário em que o reembolso parcial foi processado.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
state

enum (State)

O estado do reembolso parcial.
refundDetails

object (RefundDetails)

Detalhes do reembolso parcial.

Estado

O estado do reembolso parcial.

Tipos enumerados
STATE_UNSPECIFIED Estado não especificado. Esse valor não é usado.
PENDING O reembolso parcial foi criado, mas ainda não foi processado.
PROCESSED_SUCCESSFULLY O reembolso parcial foi processado.

PointsDetails

Detalhes relacionados aos Pontos do Play Points aplicados a um pedido.

Representação JSON 
{
  "pointsOfferId": string,
  "pointsCouponValue": {
    object (Money)
  },
  "pointsDiscountRateMicros": string,
  "pointsSpent": string
}
Campos
pointsOfferId

string

ID exclusivo da oferta do Play Points em uso para este pedido.
pointsCouponValue

object (Money)

O valor monetário de um cupom do Play Points. Esse é o desconto oferecido pelo cupom, que pode não ser o valor total. Só é definido quando os cupons do Play Points são usados. Por exemplo, para um cupom de 100 pontos por US $2, esse valor é US $2.
pointsDiscountRateMicros

string (int64 format)

A taxa percentual em que a promoção do Play Points reduz o custo. Por exemplo, para um cupom de 100 pontos por US $2,esse valor é 500.000. Como o produto $2 tem uma estimativa de 200 pontos, mas os pontos reais necessários, 100, são 50% desse valor, e 50% em micros é 500.000. Entre 0 e 1.000.000.
pointsSpent

string (int64 format)

O número de Pontos do Play Points aplicados neste pedido. Por exemplo, para um cupom de 100 pontos por US $2, esse valor é 100. Para um cupom combinado com uma oferta básica, esse é o total de pontos gastos em ambos.

Métodos

batchget

 Recebe detalhes de uma lista de pedidos.

get

 Recebe os detalhes de um único pedido.

refund

 Reembolsa a assinatura ou ordem de compra no app de um usuário.

Códigos de erro

As operações desse recurso retornam os seguintes códigos de erro HTTP:

Código do erro Motivo Resolução
5xx Erro genérico no servidor do Google Play. Tente fazer a solicitação novamente.

Se o problema persistir, entre em contato com seu gerente de contas do Google Play ou envie uma solicitação de suporte. Verifique o Painel de status do Google Play para conferir se há interrupções conhecidas.
409 Erro de atualização de simultaneidade.

Houve uma tentativa de atualizar um objeto que já estava sendo atualizado. Por exemplo, uma compra está sendo confirmada chamando o método acknowledgePurchase() da Biblioteca Play Faturamento e o purchases.products.acknowledge da API Play Developer ao mesmo tempo.

 Tente fazer a solicitação novamente.