> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kibocommerce.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Dropship
> Generate EDI 850 Purchase Orders and translate shipments into vendor SKU mappings with contracted pricing using the Kibo Dropship API
## Overview
Understand the Dropship model, lifecycle, and two-portal architecture
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:
1. **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.
2. **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](/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](/api-reference/dropship/retrieve-edi-850-purchase-order)
| 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
1. Verifies the tenant is enabled for Drop Ship.
2. Fetches the shipment from the Fulfillment service.
3. Validates the shipment (see [Validation rules](#validation-rules)).
4. Resolves the vendor from the shipment's fulfillment location.
5. 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](/api-reference/dropship/retrieve-edi-850-purchase-order) 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
```bash theme={null}
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:
```json theme={null}
{
"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](/api-reference/dropship/translate-shipment)
| 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
1. Verifies the tenant is enabled for Drop Ship.
2. Fetches the shipment from the Fulfillment service.
3. Resolves the vendor from the shipment's fulfillment location.
4. 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.
5. Computes the shipment subtotal from the items that have a contracted price.
6. 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
```bash theme={null}
curl -X GET \
"https://t1000000.sb.usc1.gcp.kibocommerce.com/api/commerce/dropship/translate/40057" \
-H "Authorization: Bearer {access_token}"
```
```json theme={null}
{
"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`](/pages/dropship-purchase-order-before) | [`http.commerce.dropship.purchaseOrder.after`](/pages/dropship-purchase-order-after) |
| Translate Shipment | [`http.commerce.dropship.translate.before`](/pages/dropship-translate-before) | [`http.commerce.dropship.translate.after`](/pages/dropship-translate-after) |