Dropship - Kibo Documentation

Overview

Dropship Overview

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.

How This Domain Fits Into Kibo

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.

Prerequisites

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).

Retrieve EDI 850 Purchase Order

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.

What the service does

Verifies the tenant is enabled for Drop Ship.
Fetches the shipment from the Fulfillment service.
Validates the shipment (see Validation rules).
Resolves the vendor from the shipment’s fulfillment location.
Maps the shipment to a complete EDI 850 transaction set and returns it.

Response: EDI 850 transaction set

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.

Example

curl -X GET \
  "https://t1000000.sb.usc1.gcp.kibocommerce.com/api/commerce/dropship/purchaseorder/40057" \
  -H "Authorization: Bearer {access_token}"

A representative (trimmed) response showing the populated segments:

{
  "transactionSetHeader": [
    { "transactionSetIdentifierCode": "850", "transactionSetControlNumber": "202606171453018842" }
  ],
  "beginningSegmentForPurchaseOrder": [
    { "transactionSetPurposeCode": "00", "purchaseOrderTypeCode": "DS", "purchaseOrderNumber": "40057", "date": "20260617" }
  ],
  "currency": [
    { "entityIdentifierCode": "BT", "currencyCode": "USD" }
  ],
  "referenceInformation": [
    { "referenceIdentificationQualifier": "Order Number", "referenceIdentification": "118" },
    { "referenceIdentificationQualifier": "Shipment Number", "referenceIdentification": "40057" }
  ],
  "n1_loop": [
    {
      "partyIdentification": [{ "entityIdentifierCode": "ST", "name": "Jane Doe" }],
      "partyLocation": [{ "addressInformation": "123 Market St" }],
      "geographicLocation": [
        { "cityName": "Austin", "stateOrProvinceCode": "TX", "postalCode": "78701", "countryCode": "US" }
      ]
    }
  ],
  "pO1_loop": [
    {
      "baselineItemData": [
        {
          "assignedIdentification": "1",
          "quantity": "2",
          "unitOrBasisForMeasurementCode": "EA",
          "unitPrice": "12.50",
          "productServiceIDQualifier": "SK",
          "productServiceID": "VEND-SKU-001"
        }
      ]
    }
  ],
  "ctT_loop": [
    { "transactionTotals": [{ "numberOfLineItems": "1", "hashTotal": "2" }] }
  ],
  "transactionSetTrailer": [
    { "numberOfIncludedSegments": "9", "transactionSetControlNumber": "202606171453018842" }
  ]
}

Validation rules

The shipment must satisfy all of the following or the request fails with a validation error:

The shipment exists.
The shipment has a shipment number.
The shipment has an orderId.
The shipment contains at least one item.
The shipment destination has an address.

A missing customer email or order number does not block generation; the service proceeds and logs a warning.

Translate Shipment

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.

What the service does

Verifies the tenant is enabled for Drop Ship.
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.

Response fields

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.
`quantity`	integer (`int32`)	No	Quantity on the shipment.
`name`	string	Yes	Product name.
`imageUrl`	string	Yes	Product image URL.

Example

curl -X GET \
  "https://t1000000.sb.usc1.gcp.kibocommerce.com/api/commerce/dropship/translate/40057" \
  -H "Authorization: Bearer {access_token}"

{
  "orderId": "5e9c1a2b3c4d5e6f7a8b9c0d",
  "shipmentNumber": 40057,
  "vendorCode": "acme-supply",
  "subtotal": 25.00,
  "shippingAddress": {
    "firstName": "Jane",
    "lastNameOrSurname": "Doe",
    "email": "jane.doe@example.com",
    "address1": "123 Market St",
    "cityOrTown": "Austin",
    "stateOrProvince": "TX",
    "postalOrZipCode": "78701",
    "countryCode": "US"
  },
  "items": [
    {
      "lineId": 1,
      "originalOrderItemId": "a1b2c3",
      "productCode": "SHIRT-001",
      "variationProductCode": "SHIRT-001-BLU-M",
      "sku": "SHIRT-001-BLU-M",
      "vendorSku": "VEND-SKU-001",
      "unitPrice": 19.99,
      "vendorContractedPrice": 12.50,
      "subtotal": 25.00,
      "quantity": 2,
      "name": "Classic Tee",
      "imageUrl": "https://cdn.example.com/shirt-001-blu.jpg"
    }
  ]
}

Error handling

Condition	Result
Tenant is not enabled for Drop Ship	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.

Extending the endpoints

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:

Endpoint	Before action	After action
Retrieve EDI 850 Purchase Order	`http.commerce.dropship.purchaseOrder.before`	`http.commerce.dropship.purchaseOrder.after`
Translate Shipment	`http.commerce.dropship.translate.before`	`http.commerce.dropship.translate.after`

​Overview

Dropship Overview

EDI Reference

​How This Domain Fits Into Kibo

​Prerequisites

​Retrieve EDI 850 Purchase Order

​What the service does

​Response: EDI 850 transaction set

​Example

​Validation rules

​Translate Shipment

​What the service does

​Response fields

​Example

​Error handling

​Extending the endpoints

Overview

How This Domain Fits Into Kibo

Prerequisites

Retrieve EDI 850 Purchase Order

What the service does

Response: EDI 850 transaction set

Example

Validation rules

Translate Shipment

What the service does

Response fields

Example

Error handling

Extending the endpoints