REST Resource: orders

แหล่งข้อมูล: คำสั่งซื้อ

ทรัพยากรคำสั่งซื้อจะสรุปข้อมูลที่ครอบคลุมเกี่ยวกับธุรกรรมที่ดำเนินการใน Google Play ซึ่งประกอบด้วยแอตทริบิวต์ต่างๆ ที่ให้รายละเอียดเกี่ยวกับคำสั่งซื้อ ผลิตภัณฑ์ที่ซื้อ และประวัติเหตุการณ์ที่เกี่ยวข้องกับคำสั่งซื้อ

API คำสั่งซื้อช่วยให้คุณเข้าถึงข้อมูลคำสั่งซื้อได้แบบเรียลไทม์ภายในระบบนิเวศของ Google Play คุณสามารถดึงข้อมูลและข้อมูลเมตาโดยละเอียดสำหรับคำสั่งซื้อแบบครั้งเดียวและแบบตามรอบ ซึ่งรวมถึงรายละเอียดธุรกรรม เช่น การเรียกเก็บเงิน ภาษี และการคืนเงิน รวมถึงข้อมูลเมตา เช่น เฟสการกำหนดราคาสำหรับการสมัครใช้บริการ API คำสั่งซื้อช่วยให้คุณสร้างระบบอัตโนมัติสำหรับงานที่เกี่ยวข้องกับการจัดการคำสั่งซื้อได้ ซึ่งจะช่วยลดความจำเป็นในการตรวจสอบด้วยตนเองผ่าน Play Developer Console

กรณีการใช้งาน API นี้บางส่วนมีดังนี้

  • การดึงข้อมูลคำสั่งซื้อแบบเรียลไทม์ - orders.get รายละเอียดคำสั่งซื้อและข้อมูลเมตาทันทีหลังจากการซื้อโดยใช้รหัสคำสั่งซื้อ

  • การซิงค์ข้อมูลอัปเดตคำสั่งซื้อ - ซิงค์ข้อมูลอัปเดตคำสั่งซื้อเป็นระยะๆ เพื่อบันทึกข้อมูลคำสั่งซื้อให้เป็นปัจจุบัน

หมายเหตุ:

  • การเรียก Orders API จะนับรวมในโควต้า Play Developer API ซึ่งมีค่าเริ่มต้นอยู่ที่ 200,000 รายการต่อวัน และอาจไม่เพียงพอที่จะซิงค์ประวัติการสั่งซื้อจำนวนมาก

  • เรียกข้อมูลคำสั่งซื้อได้สูงสุด 1,000 รายการต่อการเรียก เราขอแนะนำให้ใช้ขนาดหน้าเว็บที่ใหญ่ขึ้นเพื่อลดการใช้โควต้า ตรวจสอบโควต้าใน Cloud Console และขอเพิ่มหากจำเป็น

การแสดง 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)
  }
}
ช่อง
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 หักเงินค่าธรรมเนียมการทำธุรกรรมมาตรฐานและค่าธรรมเนียมของบุคคลที่สามจากการขายแต่ละรายการ ซึ่งรวมถึง VAT ในบางภูมิภาค
pointsDetails

object (PointsDetails)

แต้ม Play ที่ใช้กับคำสั่งซื้อ รวมถึงข้อมูลข้อเสนอ อัตราส่วนลด และมูลค่าแต้ม

รัฐ

สถานะของคำสั่งซื้อ

Enum
STATE_UNSPECIFIED ไม่ได้ระบุสถานะ ระบบจะไม่ใช้ค่านี้
PENDING สร้างคำสั่งซื้อแล้วและกำลังรอการประมวลผล
PROCESSED ระบบดำเนินการตามคำสั่งซื้อเรียบร้อยแล้ว
CANCELED ระบบได้ยกเลิกคำสั่งซื้อก่อนที่จะดำเนินการ
PENDING_REFUND คำขอเงินคืนกำลังรอดำเนินการ
PARTIALLY_REFUNDED คืนเงินคำสั่งซื้อบางส่วนแล้ว
REFUNDED คืนเงินคำสั่งซื้อเต็มจำนวนแล้ว

BuyerAddress

ข้อมูลที่อยู่ของลูกค้าเพื่อใช้ในการคำนวณภาษี

การแสดง JSON 
{
  "buyerState": string,
  "buyerCountry": string,
  "buyerPostcode": string
}
ช่อง
buyerState

string

เขตบริหารย่อยระดับบนสุดของประเทศที่อยู่ของผู้ซื้อ เมื่อ Google เป็นผู้ขายที่จดทะเบียนสำหรับคำสั่งซื้อ ระบบจะไม่รวมข้อมูลนี้
buyerCountry

string

รหัสประเทศ 2 ตัวอักษรตาม ISO-3166-1 Alpha-2 (รหัสประเทศของสหประชาชาติ)
buyerPostcode

string

รหัสไปรษณีย์ของที่อยู่ เมื่อ Google เป็นผู้ขายที่จดทะเบียนสำหรับคำสั่งซื้อ ระบบจะไม่รวมข้อมูลนี้

OrderDetails

ข้อมูลโดยละเอียดเกี่ยวกับคำสั่งซื้อ ณ เวลาที่สร้าง

การแสดง JSON 
{
  "taxInclusive": boolean
}
ช่อง
taxInclusive

boolean

ระบุว่าราคาที่แสดงรวมภาษีหรือไม่

LineItem

รายละเอียดของรายการโฆษณา

การแสดง 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

รหัสผลิตภัณฑ์ที่ซื้อหรือ SKU ในแอป (เช่น "monthly001" หรือ "com.some.thing.inapp1")
listingPrice

object (Money)

ราคาที่ระบุของแต่ละรายการใน Play Store โดยอาจรวมหรือไม่รวมภาษีก็ได้ ไม่รวมส่วนลดหรือโปรโมชันใดๆ
total

object (Money)

จำนวนเงินทั้งหมดที่ผู้ใช้ชำระสำหรับรายการโฆษณานี้ โดยคำนึงถึงส่วนลดและภาษี
tax

object (Money)

ภาษีที่ชำระสำหรับรายการโฆษณานี้

ฟิลด์ Union details

details ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
oneTimePurchaseDetails

object (OneTimePurchaseDetails)

รายละเอียดของการซื้อครั้งเดียว
subscriptionDetails

object (SubscriptionDetails)

รายละเอียดการซื้อการสมัครใช้บริการ
paidAppDetails

object (PaidAppDetails)

รายละเอียดการซื้อแอปที่ต้องซื้อ

OneTimePurchaseDetails

รายละเอียดของการซื้อครั้งเดียว

การแสดง JSON 
{
  "quantity": integer,
  "offerId": string,
  "purchaseOptionId": string,
  "rentalDetails": {
    object (RentalDetails)
  }
}
ช่อง
quantity

integer

จํานวนสินค้าที่ซื้อ (สําหรับการซื้อสินค้าหลายรายการ)
offerId

string

รหัสข้อเสนอของข้อเสนอการซื้อแบบครั้งเดียว
purchaseOptionId

string

รหัสของตัวเลือกการซื้อ ช่องนี้จะตั้งค่าสำหรับทั้งตัวเลือกการซื้อและข้อเสนอผลิตภัณฑ์ย่อย สำหรับตัวเลือกการซื้อ รหัสนี้จะระบุตัวเลือกการซื้อเอง สำหรับข้อเสนอแบบมีตัวแปร รหัสนี้จะอ้างอิงถึงตัวเลือกการซื้อที่เชื่อมโยง และจะระบุข้อเสนอแบบมีตัวแปรร่วมกับ offerId
rentalDetails

object (RentalDetails)

รายละเอียดการซื้อแบบเช่า ตั้งค่าเฉพาะในกรณีที่เป็นการซื้อแบบเช่า

RentalDetails

ประเภทนี้ไม่มีฟิลด์

รายละเอียดการซื้อแบบเช่า

SubscriptionDetails

รายละเอียดการซื้อการสมัครใช้บริการ

การแสดง JSON 
{
  "basePlanId": string,
  "offerId": string,
  "offerPhase": enum (OfferPhase),
  "servicePeriodStartTime": string,
  "servicePeriodEndTime": string
}
ช่อง
basePlanId

string

รหัสแพ็กเกจเริ่มต้นของการสมัครใช้บริการ
offerId

string

รหัสข้อเสนอสำหรับข้อเสนอการสมัครใช้บริการปัจจุบัน
offerPhase

enum (OfferPhase)

ระยะการกำหนดราคาสำหรับรอบการเรียกเก็บเงินที่ได้รับเงินสนับสนุนจากคำสั่งซื้อนี้
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"

OfferPhase

ระยะการกำหนดราคาสำหรับระยะเวลาการให้สิทธิ์ที่ได้รับเงินทุนจากคำสั่งซื้อนี้

Enum
OFFER_PHASE_UNSPECIFIED ไม่ได้ระบุระยะของข้อเสนอ ระบบจะไม่ใช้ค่านี้
BASE คำสั่งซื้อจะให้เงินทุนสำหรับระยะเวลาราคาฐาน
INTRODUCTORY คำสั่งซื้อจะให้เงินทุนสำหรับระยะเวลาการกำหนดราคาช่วงแนะนำ
FREE_TRIAL โดยคำสั่งซื้อนี้จะใช้ชำระค่าบริการในช่วงทดลองใช้ฟรี

PaidAppDetails

ประเภทนี้ไม่มีฟิลด์

รายละเอียดการซื้อแอปที่ต้องซื้อ

OrderHistory

รายละเอียดเกี่ยวกับเหตุการณ์ที่แก้ไขคำสั่งซื้อ

การแสดง 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)

รายละเอียดของเวลาที่คืนเงินคำสั่งซื้อเต็มจำนวน

ProcessedEvent

รายละเอียดเวลาที่ประมวลผลคำสั่งซื้อ

การแสดง 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"

CancellationEvent

รายละเอียดเวลาที่ยกเลิกคำสั่งซื้อ

การแสดง 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"

RefundEvent

รายละเอียดของเวลาที่คืนเงินคำสั่งซื้อเต็มจำนวน

การแสดง 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)

เหตุผลที่คำสั่งซื้อได้รับเงินคืน

RefundDetails

รายละเอียดสำหรับการคืนเงินบางส่วนหรือเต็มจำนวน

การแสดง JSON 
{
  "total": {
    object (Money)
  },
  "tax": {
    object (Money)
  }
}
ช่อง
total

object (Money)

จำนวนเงินทั้งหมดที่คืน รวมถึงภาษี
tax

object (Money)

จำนวนเงินภาษีที่คืน

RefundReason

เหตุผลที่คำสั่งซื้อได้รับเงินคืน

Enum
REFUND_REASON_UNSPECIFIED orders.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)

รายละเอียดการคืนเงินบางส่วน

รัฐ

สถานะของการคืนเงินบางส่วน

Enum
STATE_UNSPECIFIED ไม่ได้ระบุสถานะ ระบบจะไม่ใช้ค่านี้
PENDING ระบบได้สร้างการคืนเงินบางส่วนแล้ว แต่ยังไม่ได้ดำเนินการ
PROCESSED_SUCCESSFULLY ดำเนินการคืนเงินบางส่วนเรียบร้อยแล้ว

PointsDetails

รายละเอียดที่เกี่ยวข้องกับแต้ม Play ที่ใช้กับคำสั่งซื้อ

การแสดง JSON 
{
  "pointsOfferId": string,
  "pointsCouponValue": {
    object (Money)
  },
  "pointsDiscountRateMicros": string,
  "pointsSpent": string
}
ช่อง
pointsOfferId

string

รหัสที่ไม่ซ้ำกันของข้อเสนอแต้ม Play ที่ใช้สำหรับคำสั่งซื้อนี้
pointsCouponValue

object (Money)

มูลค่าเงินตราของคูปอง Play Points นี่คือส่วนลดที่คูปองมอบให้ ซึ่งอาจไม่ใช่จำนวนเงินทั้งหมด ตั้งค่าเมื่อมีการใช้คูปองแต้ม Play เท่านั้น เช่น สำหรับคูปอง 100 คะแนนต่อ $2 ค่านี้คือ $2
pointsDiscountRateMicros

string (int64 format)

อัตราเปอร์เซ็นต์ที่โปรโมชัน Play Points ลดต้นทุน เช่น สำหรับคูปอง 100 คะแนนต่อ $2 ค่านี้คือ 500,000 เนื่องจาก $2 มีการประมาณค่าเป็น 200 แต้ม แต่แต้มจริงที่ต้องใช้คือ 100 ซึ่งคิดเป็น 50% ของ 200 และ 50% ในหน่วยไมโครคือ 500,000 ระหว่าง 0 ถึง 1,000,000
pointsSpent

string (int64 format)

จำนวน Play Points ที่ใช้ในคำสั่งซื้อนี้ เช่น สำหรับคูปอง 100 คะแนนมูลค่า $2 ค่านี้คือ 100 สำหรับคูปองที่ซ้อนกับข้อเสนอพื้นฐาน นี่คือคะแนนทั้งหมดที่ใช้ในทั้ง 2 รายการ

เมธอด

batchget

 ดูรายละเอียดคำสั่งซื้อสำหรับรายการคำสั่งซื้อ

get

 ดูรายละเอียดคำสั่งซื้อสำหรับคำสั่งซื้อรายการเดียว

refund

 คืนเงินสำหรับการสมัครใช้บริการหรือคำสั่งซื้อในแอปของผู้ใช้