REST Resource: orders

Risorsa: Order

La risorsa Order contiene informazioni complete su una transazione effettuata su Google Play. Include una serie di attributi che forniscono dettagli sull'ordine stesso, sui prodotti acquistati e sulla cronologia degli eventi correlati all'ordine.

Le API Orders forniscono l'accesso in tempo reale ai dati degli ordini all'interno dell'ecosistema Google Play. Puoi recuperare informazioni dettagliate e metadati per gli ordini una tantum e ricorrenti, inclusi i dettagli delle transazioni come addebiti, tasse e rimborsi, nonché metadati come le fasi di prezzo degli abbonamenti. Le API Orders ti consentono di automatizzare le attività relative alla gestione degli ordini, riducendo la necessità di controlli manuali tramite Play Console.

Di seguito sono riportati alcuni casi d'uso di questa API:

  • Recupero dei dati degli ordini in tempo reale: recupera i dettagli e i metadati di un ordine immediatamente dopo un acquisto utilizzando un ID ordine.

  • Sincronizzazione degli aggiornamenti degli ordini: sincronizza periodicamente gli aggiornamenti degli ordini per mantenere un registro aggiornato delle informazioni sugli ordini.

Nota:

  • Le chiamate all'API Orders vengono conteggiate ai fini della quota dell'API Play Developer, che per impostazione predefinita è di 200.000 al giorno e potrebbe non essere sufficiente per sincronizzare cronologie degli ordini estese.

  • È possibile recuperare un massimo di 1000 ordini per chiamata. Per ridurre al minimo l'utilizzo della quota, è consigliabile utilizzare pagine di dimensioni maggiori. Controlla la quota in Cloud Console e richiedi un aumento, se necessario.

Rappresentazione 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)
  }
}
Campi
lineItems[]

object (LineItem)

I singoli elementi pubblicitari che compongono questo ordine.
orderId

string

L'ID ordine.
purchaseToken

string

Il token fornito al dispositivo dell'utente al momento dell'acquisto dell'abbonamento o dell'articolo.
state

enum (State)

Lo stato dell'ordine.
createTime

string (Timestamp format)

L'ora in cui è stato creato l'ordine.

Utilizza RFC 3339, in cui l'output generato è sempre normalizzato in base al fuso orario UTC e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
lastEventTime

string (Timestamp format)

L'ora dell'ultimo evento verificatosi nell'ordine.

Utilizza RFC 3339, in cui l'output generato è sempre normalizzato in base al fuso orario UTC e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
buyerAddress

object (BuyerAddress)

Informazioni sull'indirizzo del cliente, da utilizzare per il calcolo delle imposte. Quando Google è il commerciante registrato per l'ordine, viene visualizzato solo il paese.
total

object (Money)

L'importo finale pagato dal cliente, tenendo conto di sconti e tasse.
tax

object (Money)

L'imposta totale pagata nell'ambito di questo ordine.
orderDetails

object (OrderDetails)

Informazioni dettagliate sull'ordine al momento della creazione.
orderHistory

object (OrderHistory)

Dettagli sugli eventi che hanno modificato l'ordine.
developerRevenueInBuyerCurrency

object (Money)

Le tue entrate per questo ordine nella valuta dell'acquirente, incluse le detrazioni di rimborsi parziali, imposte e commissioni. Google detrae le commissioni di terze parti e sulle transazioni standard da ogni vendita, inclusa l'IVA in alcune regioni.
pointsDetails

object (PointsDetails)

Punti Play applicati all'ordine, incluse informazioni sull'offerta, tasso di sconto e valori dei punti.

Stato

Lo stato dell'ordine.

Enum
STATE_UNSPECIFIED Stato non specificato. Questo valore non viene utilizzato.
PENDING L'ordine è stato creato ed è in attesa di elaborazione.
PROCESSED L'ordine è stato elaborato correttamente.
CANCELED L'ordine è stato annullato prima dell'elaborazione.
PENDING_REFUND Il rimborso richiesto è in attesa di elaborazione.
PARTIALLY_REFUNDED L'importo dell'ordine è stato rimborsato in parte.
REFUNDED L'intero importo dell'ordine è stato rimborsato.

BuyerAddress

Informazioni sull'indirizzo del cliente, da utilizzare per il calcolo delle imposte.

Rappresentazione JSON 
{
  "buyerState": string,
  "buyerCountry": string,
  "buyerPostcode": string
}
Campi
buyerState

string

Suddivisione amministrativa di primo livello del paese dell'indirizzo dell'acquirente. Quando Google è il commerciante registrato per l'ordine, queste informazioni non sono incluse.
buyerCountry

string

Codice paese di due lettere basato su ISO-3166-1 Alpha-2 (codici paese delle Nazioni Unite).
buyerPostcode

string

Il codice postale di un indirizzo. Quando Google è il commerciante registrato per l'ordine, queste informazioni non sono incluse.

OrderDetails

Informazioni dettagliate sull'ordine al momento della creazione.

Rappresentazione JSON 
{
  "taxInclusive": boolean
}
Campi
taxInclusive

boolean

Indica se il prezzo indicato era comprensivo di tasse.

LineItem

Dettagli di un elemento pubblicitario.

Rappresentazione 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.
}
Campi
productTitle

string

Nome del prodotto specificato dallo sviluppatore. Visualizzato nella lingua dell'acquirente. Esempio: coins, monthly subscription, etc.
productId

string

L'ID prodotto acquistato o la SKU in-app (ad esempio "monthly001" o "com.some.thing.inapp1").
listingPrice

object (Money)

Prezzo di listino dell'articolo sul Play Store, che può includere o meno le tasse. Non sono inclusi sconti o promozioni.
total

object (Money)

L'importo totale pagato dall'utente per questa voce, tenendo conto di sconti e imposte.
tax

object (Money)

L'imposta pagata per questo elemento pubblicitario.

Campo unione details.

details può essere solo uno dei seguenti:
oneTimePurchaseDetails

object (OneTimePurchaseDetails)

Dettagli di un acquisto una tantum.
subscriptionDetails

object (SubscriptionDetails)

Dettagli di un acquisto di abbonamento.
paidAppDetails

object (PaidAppDetails)

Dettagli di un acquisto di app a pagamento.

OneTimePurchaseDetails

Dettagli di un acquisto una tantum.

Rappresentazione JSON 
{
  "quantity": integer,
  "offerId": string,
  "purchaseOptionId": string,
  "rentalDetails": {
    object (RentalDetails)
  }
}
Campi
quantity

integer

Il numero di articoli acquistati (per gli acquisti di articoli in più quantità).
offerId

string

L'ID offerta dell'offerta di acquisto una tantum.
purchaseOptionId

string

ID dell'opzione di acquisto. Questo campo è impostato sia per le opzioni di acquisto sia per le offerte di varianti. Per le opzioni di acquisto, questo ID identifica l'opzione di acquisto stessa. Per le offerte di varianti, questo ID si riferisce all'opzione di acquisto associata e, insieme a offerId, identifica l'offerta di variante.
rentalDetails

object (RentalDetails)

I dettagli di un acquisto di noleggio. Imposta solo se si tratta di un acquisto di noleggio.

RentalDetails

Questo tipo non contiene campi.

Dettagli di un acquisto di noleggio.

SubscriptionDetails

Dettagli di un acquisto di abbonamento.

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

string

L'ID piano base dell'abbonamento.
offerId

string

L'ID offerta dell'offerta di abbonamento attuale.
offerPhase

enum (OfferPhase)

La fase di determinazione del prezzo per il periodo di fatturazione finanziato da questo ordine.
servicePeriodStartTime

string (Timestamp format)

L'inizio del periodo di fatturazione finanziato da questo ordine. Si tratta di un'istantanea dell'ora di inizio del periodo di fatturazione/servizio al momento dell'elaborazione dell'ordine e deve essere utilizzata solo per la contabilità.

Utilizza RFC 3339, in cui l'output generato è sempre normalizzato in base al fuso orario UTC e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
servicePeriodEndTime

string (Timestamp format)

La fine del periodo di fatturazione finanziato da questo ordine. Si tratta di un'istantanea dell'ora di fine del periodo di fatturazione/servizio al momento dell'elaborazione dell'ordine e deve essere utilizzata solo per la contabilità. Per ottenere l'ora di fine corrente del periodo di servizio dell'abbonamento, utilizza purchases.subscriptionsv2.get.

Utilizza RFC 3339, in cui l'output generato è sempre normalizzato in base al fuso orario UTC e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

OfferPhase

La fase di determinazione dei prezzi per il periodo di idoneità finanziato da questo ordine.

Enum
OFFER_PHASE_UNSPECIFIED Fase dell'offerta non specificata. Questo valore non viene utilizzato.
BASE L'ordine finanzia un periodo di prezzo base.
INTRODUCTORY L'ordine finanzia un periodo di prezzo di lancio.
FREE_TRIAL L'ordine finanzia un periodo di prova senza costi.

PaidAppDetails

Questo tipo non contiene campi.

Dettagli di un acquisto di app a pagamento.

OrderHistory

Dettagli sugli eventi che hanno modificato l'ordine.

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

object (PartialRefundEvent)

Dettagli degli eventi di rimborso parziale per questo ordine.
processedEvent

object (ProcessedEvent)

Dettagli sull'elaborazione dell'ordine.
cancellationEvent

object (CancellationEvent)

Dettagli dell'annullamento dell'ordine.
refundEvent

object (RefundEvent)

Dettagli della data in cui l'ordine è stato rimborsato interamente.

ProcessedEvent

Dettagli sull'elaborazione dell'ordine.

Rappresentazione JSON 
{
  "eventTime": string
}
Campi
eventTime

string (Timestamp format)

L'ora in cui è stato elaborato l'ordine.

Utilizza RFC 3339, in cui l'output generato è sempre normalizzato in base al fuso orario UTC e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

CancellationEvent

Dettagli dell'annullamento dell'ordine.

Rappresentazione JSON 
{
  "eventTime": string
}
Campi
eventTime

string (Timestamp format)

La data e l'ora di annullamento dell'ordine.

Utilizza RFC 3339, in cui l'output generato è sempre normalizzato in base al fuso orario UTC e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

RefundEvent

Dettagli della data in cui l'ordine è stato rimborsato interamente.

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

string (Timestamp format)

La data e l'ora in cui l'ordine è stato rimborsato per intero.

Utilizza RFC 3339, in cui l'output generato è sempre normalizzato in base al fuso orario UTC e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
refundDetails

object (RefundDetails)

Dettagli del rimborso totale.
refundReason

enum (RefundReason)

Il motivo per cui l'ordine è stato rimborsato.

RefundDetails

Dettagli di un rimborso parziale o totale.

Rappresentazione JSON 
{
  "total": {
    object (Money)
  },
  "tax": {
    object (Money)
  }
}
Campi
total

object (Money)

L'importo totale rimborsato, tasse incluse.
tax

object (Money)

L'importo delle imposte rimborsate.

RefundReason

Il motivo per cui l'ordine è stato rimborsato.

Enum
REFUND_REASON_UNSPECIFIED orders.refund reason unspecified. Questo valore non viene utilizzato.
OTHER L'ordine è stato rimborsato per un motivo diverso da quelli elencati qui.
CHARGEBACK L'ordine è stato stornato.

PartialRefundEvent

Dettagli degli eventi di rimborso parziale per questo ordine.

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

string (Timestamp format)

L'ora in cui è stato creato il rimborso parziale.

Utilizza RFC 3339, in cui l'output generato è sempre normalizzato in base al fuso orario UTC e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
processTime

string (Timestamp format)

L'ora in cui è stato elaborato il rimborso parziale.

Utilizza RFC 3339, in cui l'output generato è sempre normalizzato in base al fuso orario UTC e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
state

enum (State)

Lo stato del rimborso parziale.
refundDetails

object (RefundDetails)

Dettagli del rimborso parziale.

Stato

Lo stato del rimborso parziale.

Enum
STATE_UNSPECIFIED Stato non specificato. Questo valore non viene utilizzato.
PENDING Il rimborso parziale è stato creato, ma non ancora elaborato.
PROCESSED_SUCCESSFULLY Il rimborso parziale è stato elaborato.

PointsDetails

Dettagli relativi ai punti Play Points applicati a un ordine.

Rappresentazione JSON 
{
  "pointsOfferId": string,
  "pointsCouponValue": {
    object (Money)
  },
  "pointsDiscountRateMicros": string,
  "pointsSpent": string
}
Campi
pointsOfferId

string

ID univoco dell'offerta Play Points in uso per questo ordine.
pointsCouponValue

object (Money)

Il valore monetario di un coupon Play Points. Questo è lo sconto fornito dal coupon, che potrebbe non essere l'importo totale. Impostato solo quando sono stati utilizzati i coupon Play Points. Ad esempio, per un coupon da 100 punti per 2 $, questo valore è 2 $.
pointsDiscountRateMicros

string (int64 format)

Il tasso percentuale in base al quale la promozione Play Points riduce il costo. Ad esempio, per un coupon da 100 punti per 2 $,questo valore è 500.000. Poiché 2 $hanno una stima di 200 punti, ma i punti effettivi richiesti, 100, sono il 50% di questo valore e il 50% in micro è 500.000. Tra 0 e 1.000.000.
pointsSpent

string (int64 format)

Il numero di punti Play applicati a questo ordine. Ad esempio, per un coupon da 100 punti per 2 $, questo valore è 100. Per il coupon combinato con l'offerta di base, si tratta dei punti totali spesi per entrambi.

Metodi

batchget

 Ottieni i dettagli dell'ordine per un elenco di ordini.

get

 Ottieni i dettagli di un singolo ordine.

refund

 Rimborsa l'ordine di abbonamento o acquisto in-app di un utente.