Skip to main content

Upload Dropship Batch

POST 
/api/portal/dropship/batches

Uploads a CSV of dropship orders and dry-runs it: rows are grouped into orders by order_number, and every order is checked against your dropship catalog, prices, stock, shipping services, address rules and your open orders — nothing is created yet. The batch is kept as staged so you can review each order's problems, download the error rows, fix them and re-upload, then Submit (or Discard) the batch.

Not yet available to API tokens

This endpoint currently requires session authentication; Personal Access Token scope support is in progress.

Accepts the template format (see Download Dropship CSV Template; order_number, sku and quantity columns are required) or a Shopify order export. Maximum 5 MB and 2,000 rows.

Auth: a portal session bearer token, or a portal API key (pfk_…) with the dropship:write scope, sent as Authorization: Bearer. A Viewer-role buyer (or a key owned by one) is refused with 403 viewer_read_only. Requires an enabled dropship program; 60 requests a minute.

Body (multipart/form-data):

  • file (file, required) — a .csv or .txt file, max 5 MB.

Returns 201 with the staged batch, including its orders.

Batch fields: id, original_filename, format (sku_template or shopify_export) with format_label, status (staged → submitting → completed or completed_with_errors; or discarded) with status_label, totals (rows, orders, lines, ready, warning, error, to_create, and once submitted processed, created, failed, repriced — orders whose price changed since the dry run — and repriced_delta), submittable_count, can_submit, can_discard, tracked_job_log_id (the background job creating the orders, once submitted), uploaded_by, created_at, updated_at.

Staged orders (orders): one entry per order in the file — index, order_number, rows (CSV row numbers, header = row 1), status (ready, warning — will be created, e.g. backordered stock or an address format warning — or error — will not be created), consumer (name, city, state, country_code), ship_to (the address columns as uploaded), service, gift_message, item_count, lines (row, sku, quantity as uploaded, and once matched product_id, name, unit_price, line_total), issues (each with level, code, row, field — the CSV column — message and an optional SKU suggestion), preview totals (subtotal, dropship_fee, shipping, total, currency; null for an order with errors), and after submit result (status: created, duplicate, pending_approval or failed, plus sales_order_id, sales_order_number, approval_id, and code/error when it failed).

Issue codes include missing_order_number, duplicate_order (you already sent that order number), duplicate_in_file, address_conflict, address_incomplete, international_not_allowed, unsupported_service, gift_message_too_long, missing_sku, invalid_quantity, empty_order, unknown_sku, not_dropship_eligible, unpriced, insufficient_stock (errors) and low_stock plus address format codes (warnings).

Errors: 422 validation when the file is missing, not CSV or too large; 422 unreadable_file when the file cannot be read, lacks the required columns, has no orders or has more than 2,000 rows; 403 dropship_not_enabled when CSV intake is not enabled for your program.

Request​

Responses​

Created

Response Headers
    Content-Type