Fulfillment finance

Balance, transaction ledger, and overseas commercial invoice requests for the HioBuy fulfillment account.

Availability: Sandbox / Gateway MOCK is live. No live tax-authority PDF binary in this phase.

All money fields use monetary_unit: CNY_minor (fen), same as Balance.

List Transactions

Returns fulfillment account transaction records, including credits, charges, refunds and account adjustments.

IDs: txn_* (read-only list/detail; no create/update/delete).

Enums

List filters

GET /v1/fulfillment/transactions — all filters optional. Enum values are uppercased; invalid enum → 422 (INVOICE_VALIDATION_FAILED).

Notes:

• type / category / invoice_status / related_resource_type are single-value only (no comma multi-select).
• related_resource_type and related_resource_id may be used alone or together (AND).

GET /v1/fulfillment/transactions?category=SHIPPING&invoice_status=AVAILABLE&page=1&page_size=20

Get Transaction

Returns details for a single fulfillment account transaction.

No list filters — lookup by {id} only. Includes balance_before, balance_after, optional related_resource and metadata.

Create Invoice

Creates an overseas commercial / billing invoice request for one or more eligible fulfillment wallet transactions.

This is not a Chinese mainland VAT invoice (no personal-vs-company buyer type, no domestic special-VAT fields such as registered address / bank account). It is a bill-to invoice for overseas developers and legal entities.

billing_address

Missing billing_address object → 422 INVALID_BILLING_ADDRESS. Invalid nested fields → 422 INVOICE_VALIDATION_FAILED with details.fields[].

Server computes the total from selected transactions — do not send an amount / total. Validation is atomic: any ineligible txn fails the whole request.

On success: invoice PENDING, selected txns → INVOICE_PENDING.

{
  "transaction_ids": [
    "txn_01K2ABC002",
    "txn_01K2ABC004"
  ],
  "invoice_title": "Acme Trading Co., Ltd.",
  "billing_address": {
    "address1": "88 Gangnam-daero",
    "address2": "Suite 1204",
    "city": "Seoul",
    "state": "Seoul",
    "postal_code": "06236",
    "country_code": "KR"
  },
  "tax_number": "EU123456789",
  "email": "billing@example.com",
  "remark": "August fulfillment charges"
}

Availability note: Sandbox / Gateway MOCK only in this phase — status flow and a temporary download URL are available; no live tax authority PDF binary.

List Invoices

Returns invoice requests created for the current fulfillment account.

IDs: inv_*.

Status enum

List filters

GET /v1/fulfillment/invoices — all filters optional. status is uppercased; invalid enum → 422 (INVOICE_VALIDATION_FAILED).

Notes:

• created_* filters by request time; issued_* by issue time. Both may be combined (AND).
• To list downloadable invoices, use status=ISSUED (optionally with issued_from / issued_to).
• Detail GET …/invoices/{id} has no filters — lookup by id only.

GET /v1/fulfillment/invoices?status=ISSUED&issued_from=2026-08-01T00:00:00Z&page=1&page_size=20

Get Invoice

Returns invoice details and the transactions included in the invoice.

Rejected invoices may include a public rejection_reason (no internal notes).

Download Invoice

Returns a temporary download URL for an issued invoice.

Only ISSUED. Others → 409 INVOICE_NOT_DOWNLOADABLE.

Sandbox

txn_01K2ABC001…006 · inv_01K2ABC001 (ISSUED) · inv_01K2ABC002 (PENDING) · inv_01K2ABC003 (REJECTED).
Latest txn balance_after matches Balance available 500000.

Reserved webhooks

transaction.created · invoice.issued · invoice.rejected (plus existing balance.low). Not delivered in this phase.

Related

• Fulfillment overview
• Errors