Understand the Dropship model, lifecycle, and two-portal architecture
EDI Reference
Review the EDI message set used in Dropship integrations
The Dropship API exposes two read endpoints that turn a Kibo shipment into the representation a drop-ship vendor needs in order to fulfill it:
Retrieve EDI 850 Purchase Order — converts a shipment into a fully mapped EDI 850 Purchase Order transaction set (returned as JSON), suitable for sending to a vendor over an EDI integration.
Translate Shipment — converts the same shipment into a lightweight JSON payload containing vendor SKU mappings and contracted pricing, suitable for a vendor portal or a custom API integration.
Both endpoints take a single shipmentNumber and resolve everything else — the vendor, the SKU mappings, the contracted prices, and the ship-to address — from the platform. The shipmentNumber is the Kibo Admin shipment number, which is the same value surfaced to vendors as the PO Number in the Vendor Portal.These endpoints are the programmatic equivalent of the EDI and API integration modes a vendor selects during onboarding. For the operator- and vendor-facing UI workflows, see the user guides linked at the bottom of this page.
Dropship runs natively on the Kibo platform and reuses the order routing, fulfillment, location, and pricing services rather than a separate system. When the order routing engine assigns part of an order to a vendor’s location, it creates a shipment against that fulfillment location. These endpoints operate on that shipment:
Resolved from the shipment
Source
Vendor
The vendor whose locationCode matches the shipment’s fulfillmentLocationCode
Vendor SKU and contracted price
The vendor’s SKU mapping for each item’s variation product code (falling back to the base product code)
Ship-to address
The shipment destination contact
Line items, quantities, weights, and dimensions
The shipment items
Because both endpoints derive the vendor from the shipment’s fulfillment location, a location with no matching vendor mapping cannot be translated or converted to an EDI 850.
A Kibo bearer token (JWT). Both endpoints require authorization satisfying the order update or order fulfillment behavior. The Translate Shipment endpoint additionally enforces vendor-scoped authorization.
The tenant must be enabled for Drop Ship. Both endpoints reject the request with a conflict error if it is not.
A shipment that exists and whose fulfillmentLocationCode maps to a configured vendor.
Vendor SKU mappings configured for the items you expect to receive vendor SKUs and contracted prices for (see Manage Vendors).
Both endpoints are scoped to the tenant and site context (/commerce/dropship).
Converts a shipment into an EDI 850 Purchase Order transaction set, returned as JSON.Endpoint:GET /commerce/dropship/purchaseorder/{shipmentNumber} — API reference
Parameter
In
Type
Required
Constraints
Description
shipmentNumber
path
integer (int32)
Yes
Positive 32-bit integer (max 2147483647)
The Kibo shipment number to generate the EDI 850 for.
The response body is a TransactionSet. The service populates the following segments — segments not listed are part of the EDI 850 schema but are not currently emitted:
EDI segment
JSON property
Mapped from
ST — Transaction Set Header
transactionSetHeader
Identifier code 850 and a generated control number.
BEG — Beginning Segment for Purchase Order
beginningSegmentForPurchaseOrder
Purpose code 00 (Original), type code DS (Drop Ship), purchase order number = shipment number, order date.
CUR — Currency
currency
Entity BT (Bill-To) and the shipment currency code. Omitted when the shipment has no currency code.
REF — Reference Information
referenceInformation
Order number, shipment number, customer account, customer email, tenant, site, serialized custom data, and one entry per shipment attribute.
PER — Administrative Communications Contact
administrativeCommunicationsContact
The resolved vendor’s name, phone (TE), and email (EM).
DTM — Date/Time Reference
dateTimeReference
Qualifier 002 (Requested Ship) = the shipment’s expected delivery date, when present.
N1 loop — Party Identification
n1_loop
Ship-To party (ST) only, with name, address lines, city, state/province, postal code, and country. Bill-To is intentionally omitted for drop-ship.
PO1 loop — Line Items
pO1_loop
One entry per shipment item: quantity, unit price (the vendor contracted price when a mapping exists, otherwise the item unit price), vendor SKU, product description, shipping method, physical weight/dimensions, and per-item references.
CTT loop — Transaction Totals
ctT_loop
Number of line items and a hash total of item quantities.
SE — Transaction Set Trailer
transactionSetTrailer
Included segment count and the matching control number.
The JSON property names preserve the original EDI loop casing — for example n1_loop, pO1_loop, and ctT_loop. Refer to the API reference for the complete schema.
Every EDI 850 element is serialized as a string and is optional — a segment or element appears only when the corresponding source data exists on the shipment (for example, currency is omitted when the shipment has no currency code, and dateTimeReference is omitted when there is no expected delivery date). The endpoint does not impose its own length limits; element lengths follow the source data and the X12 850 standard.
Converts a shipment into a lightweight payload with vendor SKU mappings and contracted pricing per item. Use this when you want the vendor-relevant view of a shipment without the full EDI 850 structure.Endpoint:GET /commerce/dropship/translate/{shipmentNumber} — API reference
Parameter
In
Type
Required
Constraints
Description
shipmentNumber
path
integer (int32)
Yes
Positive 32-bit integer (max 2147483647)
The Kibo shipment number to translate.
This endpoint enforces vendor-scoped authorization in addition to the order behaviors, so it is appropriate for vendor-facing integrations.
Fetches the shipment from the Fulfillment service.
Resolves the vendor from the shipment’s fulfillment location.
For each item, looks up the vendor SKU mapping (by variation product code, falling back to the base product code) and attaches the vendor SKU, contracted price, and per-item subtotal.
Computes the shipment subtotal from the items that have a contracted price.
Extracts the ship-to address from the shipment destination.
If an item has no vendor SKU mapping, its vendorSku, vendorContractedPrice, and subtotal are returned as null rather than failing the request. Those items are also excluded from the shipment-level subtotal.
The response imposes no maximum length on string fields; values reflect the underlying shipment, catalog, and vendor data. The Nullable column indicates whether the field may be null or absent.
Field
Type
Nullable
Description
orderId
string
No
The order the shipment belongs to.
shipmentNumber
integer (int32)
No
The shipment number that was translated.
vendorCode
string
Yes
The vendor resolved from the fulfillment location. Populated on success; the request fails before returning when no vendor maps to the location.
subtotal
number (double)
No
Sum of vendorContractedPrice * quantity across items that have a contracted price. Defaults to 0 when no item has a contracted price.
shippingAddress
object
Yes
Ship-to details (see below). null when the shipment destination has no contact.
items
array
Yes
Per-item detail (see below). May be an empty array when the shipment has no items.
shippingAddress object — every field is a nullable string (each is omitted from the source data when not set):
Field
Type
Nullable
Description
firstName
string
Yes
Recipient first name.
lastNameOrSurname
string
Yes
Recipient last name or surname.
companyOrOrganization
string
Yes
Recipient company or organization.
email
string
Yes
Recipient email.
address1
string
Yes
Street address line 1.
address2
string
Yes
Street address line 2.
cityOrTown
string
Yes
City or town.
stateOrProvince
string
Yes
State or province.
postalOrZipCode
string
Yes
Postal or ZIP code.
countryCode
string
Yes
Country code.
Each entry in items:
Field
Type
Nullable
Description
lineId
integer (int32)
No
Shipment line identifier. Defaults to 0 when the source line has no ID.
originalOrderItemId
string
Yes
The originating order item ID.
productCode
string
Yes
Base product code.
variationProductCode
string
Yes
Variation product code, when the item is a variation.
sku
string
Yes
The catalog SKU.
vendorSku
string
Yes
The vendor’s SKU from the mapping, or null when unmapped.
unitPrice
number (double)
No
The item unit price on the shipment.
vendorContractedPrice
number (double)
Yes
The contracted price from the vendor mapping, or null when unmapped.
subtotal
number (double)
Yes
vendorContractedPrice * quantity, or null when unmapped.
Conflict error — Tenant is not enabled for Drop Ship.
Shipment does not exist
Not found — Shipment {shipmentNumber} not found.
No vendor maps to the shipment’s fulfillment location
Not found — Vendor not found for location {locationCode}.
Shipment fails EDI 850 validation (Retrieve EDI 850 only)
Conflict error listing the specific validation failures.
For the Translate Shipment endpoint, a missing vendor SKU mapping on an individual item is not an error — the vendor-specific fields on that item are returned as null.
Both endpoints expose before- and after-controller action extension points, so you can inject custom logic (for example, enriching the response or applying additional authorization) without modifying the service. See the API Extensions reference for each action:
