JBI API — Customer Order Submission (v3)

Endpoint: POST /customer/v3/ordering/{accountId}
Base URL: https://api.jbi.bike
Version: v3
Content-Type: application/json

Overview

This endpoint allows authorized customers to submit an order into the JBI fulfillment system. The order is validated, priced, and inserted immediately upon receipt. A successful response confirms that the order has been accepted.

Authentication

Every request must include your API token in the request header.

Token-key: your-api-token-here

Your accountId and Token-key are provided by JBI. The token is validated per account — using a token that does not match the accountId in the URL will result in a 401 response.

URL Parameters

Example URL:

POST https://api.jbi.bike/customer/v3/ordering/10042

Request Body

The body must be a JSON array containing a single order object.

Minimal Example (Standard Ship-To Order)

[
  {
    "CustomerOrderNo": "ORD-2025-001",
    "AccountNumber": "10042",
    "ShipToID": "10042",
    "LineItems": [
      { "PartNumber": "6451",  "Qty": 2, "LocID": 1 },
      { "PartNumber": "49525", "Qty": 5, "LocID": 1 }
    ]
  }
]

Full Example (Dropship Order with Optional Fields)

[
  {
    "CustomerOrderNo": "ORD-2025-002",
    "PONumber": "98765",
    "AccountNumber": "10042",
    "ShipToID": "10042",
    "ShipDropship": "Y",
    "Comment": "",
    "CarrierID": 100011,
    "DropshipBilling": "PREPAID",
    "Residential": "Y",
    "ShipDateRequest": "",
    "EmailAddress": "customer@example.com",
    "DeliveryAddress": {
      "RecipientName": "Jane Smith",
      "Street1": "456 Oak Avenue",
      "Street2": "Apt 3B",
      "City": "Portland",
      "State": "OR",
      "Zip": "97201",
      "Phone": "503-555-9876"
    },
    "LineItems": [
      {
        "PartNumber": "6451",
        "Qty": 1,
        "LocID": 101
      }
    ]
  }
]

Request Fields

Order Object

LineItems

Each element in the LineItems array represents a single order line.

DeliveryAddress

Required when ShipDropship is "Y".

Carrier Codes

PREPAID — Charges included on your invoice

COLLECT — Billed to your carrier account

Account must be pre-authorized and your collect account number must be on file with JBI.

LABEL — Your own prepaid shipping label

Warehouse Location IDs

Use these values for the LocID field on each line item. When AutoSplit is "Y", the system selects the location automatically and LocID is ignored.

Dropship Billing

The DropshipBilling field controls how shipping charges are billed:

Contact JBI to have COLLECT or LABEL billing enabled for your account.

LABEL Shipping Requirements

Using your own shipping label requires a one-time setup with JBI before your first order:

• Submit a sample label in advance for approval and additional setup by JBI.
• File format: PDF only.
• Label dimensions: 4×6 inches. Labels formatted as 8×11 (even with a 4×6 label in a corner of the page) are not accepted — JBI's shipping system exclusively supports 4×6.
• File naming: {AccountNumber}-{CustomerOrderNo}.pdf
  • Example: account 1353, order ORD1001 → 1353-ORD1001.pdf
• Upload: Once your account is approved, a ship_label folder will be created in your FTP directory. Upload your label file there before the order is processed.

Responses

Success (HTTP 201)

{
  "success": true,
  "data": {
    "orderId": 84210,
    "customerOrderNo": "ORD-2025-001",
    "status": "submitted",
    "message": "Order successfully created"
  }
}

Note that all of these are success responses: success is true and the HTTP status is 201 in every case below, including "pending". The order always exists in JBI's system once you receive a 201 — status tells you whether it was also submitted for fulfillment.

Status Codes

The code field appears only when the outcome differs from a straightforward submission. When code is absent and status is "submitted", the order was accepted exactly as requested and no action is needed.

Codes 10 and 21 are produced by the auto-split routing engine and therefore only occur when you send AutoSplit: "Y". Orders sent with AutoSplit set to "N" or omitted are routed using the LocID you supply on each line and never return either code.

If you poll or reconcile orders programmatically, treat any "pending" status as not yet in fulfillment — a 21 in particular will stay open indefinitely until someone acts on it.

Example — order held for short inventory (21)

{
  "success": true,
  "data": {
    "orderId": 84211,
    "customerOrderNo": "ORD-2025-002",
    "status": "pending",
    "code": "21",
    "message": "Order not auto-submitted. One or more items could not be filled in full from available inventory. Login to jbi.bike to review and submit."
  }
}

Example — submitted, split across locations (10)

{
  "success": true,
  "data": {
    "orderId": 84212,
    "customerOrderNo": "ORD-2025-003",
    "status": "submitted",
    "code": "10",
    "message": "You requested shipment from a single location but it was not possible. Order will be sent in multiple shipments."
  }
}

Error Responses

All errors follow the same envelope structure:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

HTTP 400 — Bad Request

HTTP 401 — Unauthorized

HTTP 405 — Method Not Allowed

HTTP 422 — Unprocessable Entity

HTTP 500 — Server Error

Validation Error Detail (VALIDATION_FAILED)

When validation fails, the response includes a fields object identifying each invalid field:

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Request validation failed",
    "fields": {
      "CustomerOrderNo": "required",
      "LineItems.0.Qty": "required|numeric|min:1"
    }
  }
}

Order Uniqueness

Every order submitted to the API must have a unique combination of CustomerOrderNo + AccountNumber. The system stores the order under the internal name JBI-{CustomerOrderNo}-{AccountNumber}. Resubmitting the same combination will be rejected with DUPLICATE_ORDER.

Quick Reference

POST /customer/v3/ordering/{accountId} HTTP/1.1
Host: api.jbi.bike
Token-key: your-api-token-here
Content-Type: application/json

[
  {
    "CustomerOrderNo": "ORD-2025-001",
    "AccountNumber": "10042",
    "ShipToID": "SHP-001",
    "LineItems": [
      { "PartNumber": "6451", "Qty": 2, "LocID": 101 }
    ]
  }
]

Document version: 1.1 — 2026-08-27
For questions or to request feature access (Collect/Label billing), contact JBI.