---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/en/notes/subscription/invoice/query/index.md
description: >-
  The Invoice Details API queries an invoice by invoice ID, returning the
  amount, customer, merchant snapshot, payment information and download link; in
  subscription scenarios it additionally returns the billed period.
---
# Invoice Details

```apidef
endpoint: POST /v4/invoices/query
name: Invoice Details
summary: Query invoice details by invoiceId
tags: Invoice
```

The Invoice Details API queries an invoice by invoice ID, returning the amount, customer, merchant snapshot, payment information and download link; in subscription scenarios it additionally returns the billed period.

## Request Parameters

| Parameter | Type | Required | Description |
|--------|------|------|------|
| clientId | string | M | Merchant ID. |
| accId | string | M | Store ID. |
| signType | string | M | Signature type, MD5; for details, see the Signature Specification: /en/notes/guide/sign/ section of this document. |
| sign | string | M | Signature value, following the V4 signature specification. All parameters participate in the signature. |
| version | string | M | API version, fixed at 4.0 . |
| bizContent | string | M | Business parameters as a JSON string. All request parameters except the common ones must be passed within this parameter. |
| └─ requestId | string | M | Unique request ID, globally unique. |
| └─ invoiceId | string | M | Invoice ID. |

### Request Example

```json
{
  "clientId": "20250101123456",
  "accId": "ACC001",
  "signType": "MD5",
  "sign": "SIGN_VALUE",
  "version": "4.0",
  "bizContent": "{\"requestId\":\"req_20260507_0011\",\"invoiceId\":\"INV-260507100000000001\"}"
}
```

## Response Parameters

| Parameter | Type | Description |
|--------|------|------|
| clientId | string | Merchant ID. |
| accId | string | Store ID. |
| signType | string | Signature type. |
| sign | string | Signature value, verified using the V4 signature specification. |
| code | string | Response code: 000000 on success; on failure, the business error code is passed through ( 102000 invalid parameter / 500003 resource not found / 910001 business validation failed / 910005 operation not allowed in current status / 910008 in-flight task exists / 500000 system error, etc.). |
| description | string | Response description. |
| bizContent | string | Business response as a JSON string. |
| └─ requestId | string | Unique request ID, echoed from the request. |
| └─ invoiceId | string | Invoice ID. |
| └─ invoiceNumber | string | Invoice number, assigned after finalization. |
| └─ version | integer | Invoice version number, incremented on every re-render. |
| └─ status | string | Invoice status: DRAFT : draft, not finalized after creation; can be updated or voided.; FINALIZED : finalized, invoice number assigned, downloadable.; VOID : voided.; Observed in sandbox: the invoice status follows the payment pipeline and may also be PAYMENT_PENDING (charge in progress) / PAID / PARTIALLY_REFUNDED (refunds attach to the first invoice) / FULLY_REFUNDED . |
| └─ createdAt | string | Creation time as a 10-digit second-level timestamp string. |
| └─ finalizedAt | string | Finalization time as a 10-digit second-level timestamp string. |
| └─ paidAt | string | Payment completion time as a 10-digit second-level timestamp string. |
| └─ currency | string | Currency, ISO 4217. |
| └─ subtotal | string | Subtotal amount as a decimal string. |
| └─ total | string | Total amount as a decimal string. |
| └─ amountPaid | string | Amount already paid, as a decimal string. Sandbox verified (2026-10-19): not returned while the invoice is unpaid (PAYMENT_PENDING). |
| └─ subscriptionDetail | object | Subscription information object. Not returned for non-subscription scenarios. |
| └─ └─ subscriptionId | string | PingPong subscription ID. |
| └─ └─ partnerSubscriptionId | string | Merchant-side subscription ID. |
| └─ └─ startAt | string | Start of the billing period covered by this invoice, as a 10-digit second-level timestamp string. |
| └─ └─ endAt | string | End of the billing period covered by this invoice, as a 10-digit second-level timestamp string. |
| └─ customer | object | Customer object, same structure as the customer API: /en/notes/subscription/invoice/customer/query/ response body. |
| └─ └─ customerId | string | PingPong customer ID. |
| └─ └─ partnerCustomerId | string | Merchant-side customer identifier, i.e. the user's member ID on the merchant's website. Unique within the same store. |
| └─ └─ firstName | string | First name. |
| └─ └─ lastName | string | Last name. |
| └─ └─ companyName | string | Company name. |
| └─ └─ email | string | Email address. |
| └─ └─ phone | string | Phone number. |
| └─ └─ address | object | Address object, same structure as the request address. |
| └─ └─ └─ country | string | Two-letter country code, ISO 3166. |
| └─ └─ └─ state | string | State or province. |
| └─ └─ └─ city | string | City. |
| └─ └─ └─ postalCode | string | Postal code. |
| └─ └─ └─ line1 | string | Address line 1. |
| └─ └─ └─ line2 | string | Address line 2. |
| └─ └─ language | string | Preferred language and locale. |
| └─ └─ metadata | string | Merchant-defined custom string. |
| └─ └─ createdAt | string | Creation time as a 10-digit second-level timestamp string. |
| └─ └─ updatedAt | string | Last update time as a 10-digit second-level timestamp string. |
| └─ merchant | object | Issuer (merchant) object. |
| └─ └─ legalName | string | Merchant legal name. |
| └─ └─ address | object | Merchant address object. |
| └─ └─ └─ businessAddressEn | string | Merchant business address in English. |
| └─ └─ └─ postCode | string | Postal code. |
| └─ └─ └─ country | string | Country. Sandbox responses return the full country name (e.g. China ). |
| └─ └─ website | string | Merchant website. |
| └─ payment | object | Payment information object. |
| └─ └─ status | string | Payment status. |
| └─ └─ transactionId | string | PingPong transaction ID. |
| └─ └─ merchantTransactionId | string | Merchant transaction ID. |
| └─ └─ methodType | string | Payment method: the card brand for card payments (e.g. VISA ), or an upper-case APM name (such as PAYNOW ). |
| └─ └─ transactionTime | string | Payment completion time, ISO 8601 UTC. |
| └─ download | object | File download object. Can also use the Invoice Download: /en/notes/subscription/invoice/download/ API to obtain the download URL. |
| └─ └─ url | string | Download URL, valid for 30 days. |
| └─ └─ expiresAt | string | URL expiration time as a 10-digit second-level timestamp string. |
| └─ └─ version | integer | Invoice version that the file corresponds to. |
| └─ └─ format | string | File format, currently PDF . |

### Response Example

```json
{
  "clientId": "20250101123456",
  "accId": "ACC001",
  "signType": "MD5",
  "sign": "SIGN_VALUE",
  "code": "000000",
  "description": "SUCCESS",
  "bizContent": "{\"requestId\":\"req_20260507_0011\",\"invoiceId\":\"INV-260507100000000001\",\"invoiceNumber\":\"INV-2605070001\",\"version\":1,\"status\":\"FINALIZED\",\"createdAt\":\"2026-05-07T00:00:00Z\",\"finalizedAt\":\"2026-05-07T00:01:00Z\",\"paidAt\":\"2026-05-07T00:02:00Z\",\"currency\":\"USD\",\"subtotal\":\"10.00\",\"total\":\"10.00\",\"amountPaid\":\"10.00\",\"subscriptionDetail\":{\"subscriptionId\":\"SUB-2605070001\",\"partnerSubscriptionId\":\"sub_20260507_0002\",\"startAt\":\"2026-05-07T00:00:00Z\",\"endAt\":\"2026-06-07T00:00:00Z\"},\"customer\":{\"customerId\":\"CUS-260507100000000001\",\"partnerCustomerId\":\"USER_001\",\"firstName\":\"James\",\"lastName\":\"LeBron\",\"email\":\"james@example.com\"},\"merchant\":{\"legalName\":\"Example Pte. Ltd.\",\"address\":{\"businessAddressEn\":\"10 Marina Boulevard, Singapore\",\"postCode\":\"018983\",\"country\":\"SG\"},\"website\":\"https://merchant.example.com\"},\"payment\":{\"status\":\"SUCCESS\",\"transactionId\":\"260507100000000001\",\"merchantTransactionId\":\"M202605070001\",\"methodType\":\"CARD\",\"transactionTime\":\"2026-05-07T00:02:00Z\"},\"download\":{\"url\":\"https://example.com/invoice/INV-2605070001.pdf\",\"expiresAt\":\"2026-06-06T00:00:00Z\",\"version\":1,\"format\":\"PDF\"}}"
}
```