FulfillbotDocs
Menu
MarkdownDownload

Purchase orders

A purchase order is what we buy for you from a seller: from a reorder or sourcing request, from auto purchase when orders are short of stock, or one you placed yourself from Search in the portal. When its goods arrive and are checked, they become stock in your inventory.

You can read purchase orders here. Purchase orders from auto purchase are paid from your wallet automatically when your available balance covers them; otherwise they wait and are paid automatically after a top-up (Charges and your wallet). Pay all other purchase orders in the portal; the API can't pay yet. Webhook purchase_order.status_changed reports every status change. The list is sorted newest first and includes cancelled purchase orders. There is no updatedSince here: use webhooks and GET, or read the first pages again to find new ones (the list is newest first). See Incremental sync.

Purchase order statuses

Value Meaning
AWAITING_PAYMENT Waiting for your payment. Pay purchase orders in the portal.
DEPOSIT_PAID We received a deposit; the rest is due later.
PAID Paid in full; we are about to buy the goods.
PURCHASING We are buying the goods from the seller. The statuses from here to ARRIVED say how far the goods have got, not whether you have paid; payment may still be partly or fully due.
ORDERED Ordered from the seller (shown as Purchasing in the portal).
IN_TRANSIT On the way to our warehouse.
PARTIALLY_ARRIVED Some of the goods arrived at our warehouse.
ARRIVED All goods arrived at our warehouse.
STORED All goods are in stock in our warehouse (or settled as short); some payment is still due.
COMPLETED Paid in full and all goods are in stock (or settled as short).
CANCELLED Cancelled. cancelledAt says when.

List purchase orders

GET /v1/purchase-orders

All your purchase orders, including cancelled ones. Newest first.

Property Value
URL https://api.rephut.com/v1/purchase-orders
Permission purchase_orders:read
Access Read: counts towards the read limit and works while your account is on hold
Idempotency-Key Not used
Success 200 OK

Query parameters

Field Type Required Description
page integer No Page number. See Pagination. From 1 to 10,000. Default: 1.

Headers

Header Required Value
Authorization Yes Bearer <your API key>. See Authentication.

Response

200 with data, a list of objects with the fields below (up to one page), and meta with total, page, limit and pageCount. See Pagination.

Field Type Description
id string Purchase order id.
number string Our purchase order number.
status string Purchase order status. See Purchase order statuses. One of AWAITING_PAYMENT, DEPOSIT_PAID, PAID, PURCHASING, ORDERED, IN_TRANSIT, PARTIALLY_ARRIVED, ARRIVED, STORED, COMPLETED, CANCELLED.
statusLabel string English text for display. It may change; rely on the code next to it.
itemCount integer Number of products on the purchase order.
currency string Currency of every amount. Always USD.
receivableCents integer What you pay: the total minus short-shipped items.
paidCents integer Paid so far minus refunds, in US cents.
dueCents integer Still to pay, in US cents; 0 when the purchase order is cancelled.
createdAt string (date-time) When the purchase order was created.

Errors

Code HTTP status Meaning
invalid_api_key 401 The API key is missing, malformed, revoked or no longer valid.
account_action_required 403 Sign in to the portal and finish the required account steps first.
api_not_enabled 403 API access is not enabled for this account.
insufficient_scope 403 The API key does not have the permission this call needs.
validation_failed 422 The input is not valid. details lists each field and the reason.
rate_limited 429 Too many requests. Wait for the number of seconds in Retry-After.
internal_error 500 Unexpected error. Quote X-Request-Id when you contact support.

Handle errors by code. See Errors.

Get a purchase order

GET /v1/purchase-orders/{id}

Property Value
URL https://api.rephut.com/v1/purchase-orders/{id}
Permission purchase_orders:read
Access Read: counts towards the read limit and works while your account is on hold
Idempotency-Key Not used
Success 200 OK

Path parameters

Name Type Description
id string Purchase order id, from GET /v1/purchase-orders. An id that doesn't exist, isn't yours or isn't a valid id returns 404 not_found.

Headers

Header Required Value
Authorization Yes Bearer <your API key>. See Authentication.

Response

200 with data, an object with the fields below.

Field Type Description
id string Purchase order id.
number string Our purchase order number.
status string Purchase order status. See Purchase order statuses. One of AWAITING_PAYMENT, DEPOSIT_PAID, PAID, PURCHASING, ORDERED, IN_TRANSIT, PARTIALLY_ARRIVED, ARRIVED, STORED, COMPLETED, CANCELLED.
statusLabel string English text for display. It may change; rely on the code next to it.
createdAt string (date-time) When the purchase order was created.
cancelledAt string (date-time) or null When it was cancelled; null otherwise.
paymentMethodName string or null The payment method set for this purchase order; null when none.
note string Note on the purchase order.
placedViaSearch boolean true when you placed it yourself from Search in the portal.
currency string Currency of every amount. Always USD.
items array of objects Products on the purchase order.
items[].productId string Our product id.
items[].sku string Our SKU.
items[].name string Product name in English.
items[].attributes string Variant details in English.
items[].customerSku string Your SKU for the product when it is mapped; empty otherwise.
items[].qty integer Quantity on the purchase order.
items[].unitPriceCents integer Unit price in US cents.
items[].amountCents integer Line amount in US cents.
items[].orderedQty integer Quantity we have ordered from the seller.
items[].inWarehouseQty integer Quantity received in our warehouse in good condition.
items[].shortQty integer Short-shipped or refunded by the seller.
charges array of objects Other charges on the purchase order, such as domestic shipping.
charges[].label string What the charge is for.
charges[].amountCents integer Amount in US cents.
totalCents integer Goods plus charges, in US cents.
shortageCents integer Value of short-shipped or refunded items, in US cents.
receivableCents integer What you pay: totalCents minus shortageCents.
paidCents integer Paid so far minus refunds, in US cents.
dueCents integer Still to pay, in US cents; 0 when the purchase order is cancelled.
payments array of objects Payments received.
payments[].paidOn string (date) The day of the payment (YYYY-MM-DD, China time).
payments[].amountCents integer Amount in US cents.
payments[].methodLabel string Payment method.
refunds array of objects Refunds to you.
refunds[].label string What was refunded.
refunds[].amountCents integer Amount in US cents.
refunds[].refundedAt string (date-time) When it was refunded.
paymentInstructions array of objects How to pay; empty when nothing is due.
paymentInstructions[].name string Payment method name.
paymentInstructions[].instructions string How to pay with this method.

Errors

Code HTTP status Meaning
invalid_api_key 401 The API key is missing, malformed, revoked or no longer valid.
account_action_required 403 Sign in to the portal and finish the required account steps first.
api_not_enabled 403 API access is not enabled for this account.
insufficient_scope 403 The API key does not have the permission this call needs.
not_found 404 The resource does not exist or does not belong to this account.
validation_failed 422 The input is not valid. details lists each field and the reason.
rate_limited 429 Too many requests. Wait for the number of seconds in Retry-After.
internal_error 500 Unexpected error. Quote X-Request-Id when you contact support.

Handle errors by code. See Errors.