FulfillbotDocs
Menu
MarkdownDownload

Charges and your wallet

The API follows the same money rules as the portal. orders:write doesn't mean "free": creating orders reserves stock and holds money, and our warehouse charges your wallet when it weighs a parcel. The portal shows this note when you create a key that can create orders:

Orders created through the API can use your wallet balance

  • Creating an order doesn't charge your wallet. When the order has no problems, we reserve its stock and hold the estimated shipping and handling fee from your available balance.
  • When our warehouse weighs the parcel, the shipping and handling fee is charged to your wallet automatically.
  • If auto purchase is on and an order is short of stock, we place and pay for a purchase order automatically, within the limits you set.
  • Confirming a shipment doesn't charge your wallet. It creates an amount due that you pay separately.

Step by step

Action What happens to your wallet
POST /v1/orders/preview Nothing. It shows the hold (charges.holdCents) and how much to top up (charges.topUpCents).
POST /v1/orders, PATCH /v1/orders/{id} No charge. An order without problems reserves its stock; once its stock is fully reserved, it holds the estimated shipping and handling fee from your available balance (shippingHold on the order). A BACKORDERED order holds nothing yet, and an order with problems holds nothing until it is fixed.
POST /v1/orders/{id}/cancel No charge; the hold, if any, is released.
Our warehouse weighs the parcel The shipping and handling fee is charged to your wallet automatically and the hold is released. If your available balance doesn't cover it, the order waits for payment: payment on the order shows the amount, and the webhook order.awaiting_payment is sent. Top up in the portal.
An order is short of stock and auto purchase is on We place and pay for a purchase order automatically, within the limits you set in the portal.
POST /v1/shipments No charge. The stock is reserved.
POST /v1/shipments/{id}/confirm No charge. It creates an amount due (dueCents), which you pay in the portal.
POST /v1/requests/sourcing, POST /v1/requests/reorder No charge. We reply with a quote or a purchase order.

Your available balance is availableCents from GET /v1/wallet: balanceCents + creditLimitCents - heldForShippingCents. GET /v1/wallet/ledger lists every movement.

Paying

The API can't move money yet. Pay purchase orders and shipments, and top up your wallet, in the portal.