Account-API2026-11Preview

Saldo

Het geld waaruit je bestellingen worden betaald, in CN¥. Je zet het erop via ninjabuy.com; de API leest het en schrijft nooit iets af van een kaart.

Een bestelling die je saldo niet dekt, wacht als awaiting_payment en gaat na een opwaardering vanzelf verder.
Terugbetalingen voor een geannuleerde bestelling of een regel die we niet konden kopen, gaan terug naar het saldo. Kosten somt elke afschrijving op.

Endpoints

GET/v1/balanceHet saldo ophalen
GET/v1/balance/transactionsTransacties opvragen

Het Balance-object

availablemoney: Wat nieuwe bestellingen kunnen uitgeven, in CN¥.
reservedmoney: Gereserveerd voor bestellingen die worden ingekocht en pakketten die nog gewogen moeten worden.
top_up_urlstring: Waar je geld toevoegt, ingelogd op ninjabuy.com.

balance

{
  "available": { "amount": "2140.00", "currency": "CNY" },
  "reserved": { "amount": "264.20", "currency": "CNY" },
  "top_up_url": "https://www.ninjabuy.com/me/balance/top-up",
  "updated_at": "2026-11-04T09:20:03Z"
}

Het saldo ophalen

GET/v1/balance

Controleer het voordat je een grote partij bestellingen stuurt.

Scopebalance:read

curl "https://www.ninjabuy.com/api/v1/balance" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "available": { "amount": "2140.00", "currency": "CNY" },
  "reserved": { "amount": "264.20", "currency": "CNY" },
  "top_up_url": "https://www.ninjabuy.com/me/balance/top-up",
  "updated_at": "2026-11-04T09:20:03Z"
}

Transacties opvragen

GET/v1/balance/transactions

Opwaarderingen, bestel- en verzendkosten, en terugbetalingen, nieuwste eerst. Bedragen hebben een teken: een afschrijving is negatief.

Scopebalance:read

Queryparameters

typestring: Optioneel. top_up, order, shipping of refund.
orderstring: Optioneel. Een bestellings-id: alles wat die bestelling heeft verplaatst.
limit, cursor: Pagination

curl "https://www.ninjabuy.com/api/v1/balance/transactions?limit=3" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "data": [
    {
      "id": "txn_k22a",
      "type": "shipping",
      "order": "ord_3n7q",
      "amount": { "amount": "-134.52", "currency": "CNY" },
      "created_at": "2026-11-03T05:58:00Z"
    },
    {
      "id": "txn_k21d",
      "type": "order",
      "order": "ord_3n7q",
      "amount": { "amount": "-57.00", "currency": "CNY" },
      "created_at": "2026-11-01T09:14:02Z"
    },
    {
      "id": "txn_k1zz",
      "type": "top_up",
      "order": null,
      "amount": { "amount": "2000.00", "currency": "CNY" },
      "created_at": "2026-10-31T16:40:12Z"
    }
  ],
  "has_more": true,
  "cursor": "c_k1zz"
}