# Bulk fulfill orders

`POST /orders/bulk-fulfill`

OMS API, Orders.

Fulfill multiple orders at once from a parsed CSV import, inside the request. Each entry specifies an order, tracking URL, and optionally a specific order item. For more than a few hundred entries, or to keep a record of the run, start a job with `POST /orders/bulk-fulfill/jobs` instead.

**Authentication:** Send `Authorization: Bearer <token>`. Either an identity token issued by the auth service (dashboard flow; requires the selected merchant account id in the `X-Odus-Merchant` header), or a merchant secret key (`sk_...`) for server-to-server calls. Both are sent as `Authorization: Bearer <token>`.

## Request body

Content type `application/json`, required.

Type: object (BulkFulfillOrderDTO).

- `entries` (array of object (BulkFulfillEntryDTO), required): Entries to fulfill. Minimum items 1.
  - `orderId` (string, required): The ID of the order to fulfill.
  - `trackingNumber` (string, required): Carrier-issued tracking number for the shipment. The tracking URL is derived from it.
  - `trackingUrl` (string): Tracking URL provided by the integration. When omitted it is derived from the tracking number.
  - `carrier` (string, required): Carrier name (e.g. "UPS", "USPS", "FedEx", "DHL").
  - `orderItemId` (string): The ID of the specific order item to fulfill. If omitted, all unfulfilled items in the order are fulfilled.
  - `externalOrderId` (string): Identifier of the order in the integration's own system (e.g. NextSmartShip's internal order id). When present it is stored on the order as its external order id.
  - `externalShipmentId` (string): Identifier of the shipment in the integration's own system (e.g. ShipBob's shipment id). When present it is stored on the fulfillment.
  - `shippedAt` (string (date-time)): Timestamp at which the shipment left the warehouse. Defaults to the current time when omitted.

## Responses

### `200`

Type: object (BulkFulfillResultDTO).

- `total` (number, required): Total number of fulfillment groups processed.
- `succeeded` (number, required): Number of successfully created fulfillments.
- `failed` (number, required): Number of failed fulfillment groups.
- `skipped` (number, required): Number of fulfillment groups skipped (e.g. because an identical fulfillment already exists for the order).
- `errors` (array of object, required): Details of each failed entry.
  - `orderId` (string, required)
  - `orderItemIds` (array of string, required)
  - `message` (string, required)
  - `reason` (string, required): One of `validation`, `not_found`, `internal`.
- `skippedEntries` (array of object, required): Details of each skipped entry.
  - `orderId` (string, required)
  - `orderItemIds` (array of string, required)
  - `reason` (string, required): One of `duplicate`.
  - `message` (string, required)

### `202`

The merchant is entitled but its OMS environment is not provisioned yet. Provisioning has been kicked off (exactly once) and is in progress; retry the request — it succeeds once the environment is ready. Returned only for identity-token (dashboard) requests bound to an active-entitled merchant, not for secret-key API calls; any such endpoint can return it while provisioning is underway.

Type: object (ProvisioningInProgress).

- `status` (string, required): Signals the merchant OMS environment is still being provisioned. One of `provisioning`.
- `merchantAccountId` (string, required): The merchant account whose OMS environment is being provisioned. Example: `dAI3aa87ROOeupeBCjNSKCOBOisBCYjB`.

### `400`

The request was rejected. `type` is `invalid_request_error`; when the failure is a validation failure `code` is `validation_failed` and `errors` lists every problem found, with field-attributable entries prefixed by the field’s path.

Type: object (ValidationErrorResponse).

- `statusCode` (number, required): HTTP status code. Example: `400`.
- `requestId` (string, required): Unique identifier for the request. Example: `dfc10de3-36bb-4bcc-b081-316216194033`.
- `message` (string, required): The first error message from the validation errors. Example: `note must be a string`.
- `type` (string, required): Coarse, stable classifier for the failure. Present on every error response including 5xx. This is the field to branch on: `statusCode` is too coarse and `message` is human prose that may be reworded. The set is closed and every member is permanent, so it is safe to handle exhaustively. One of `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `invalid_state_error`, `conflict_error`, `rate_limit_error`, `payment_error`, `api_error`. Example: `invalid_request_error`.
- `code` (string): Fine-grained identifier for the failure, present only where it adds something `type` does not — for example separating a replayed idempotency key from a held lock, or naming the reason a payment was declined. The set is open and grows over time, so treat an unrecognised value as absent and fall back to `type`. Example: `validation_failed`.
- `errors` (array of string): Complete list of validation errors.

### `401`

No credentials were supplied, or the identity token / secret key is not valid for the target merchant. `type` is `authentication_error`.

Type: object (ErrorResponse).

- `statusCode` (number, required): HTTP status code. Example: `400`.
- `requestId` (string, required): Unique identifier for the request. Example: `dfc10de3-36bb-4bcc-b081-316216194033`.
- `message` (string, required): Human-readable description of the failure. Example: `An error occurred`.
- `type` (string, required): Coarse, stable classifier for the failure. Present on every error response including 5xx. This is the field to branch on: `statusCode` is too coarse and `message` is human prose that may be reworded. The set is closed and every member is permanent, so it is safe to handle exhaustively. One of `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `invalid_state_error`, `conflict_error`, `rate_limit_error`, `payment_error`, `api_error`. Example: `invalid_request_error`.
- `code` (string): Fine-grained identifier for the failure, present only where it adds something `type` does not — for example separating a replayed idempotency key from a held lock, or naming the reason a payment was declined. The set is open and grows over time, so treat an unrecognised value as absent and fall back to `type`. Example: `validation_failed`.

### `403`

The credentials are valid but lack the permission this operation requires. `type` is `permission_error`.

Type: object (ErrorResponse).

- `statusCode` (number, required): HTTP status code. Example: `400`.
- `requestId` (string, required): Unique identifier for the request. Example: `dfc10de3-36bb-4bcc-b081-316216194033`.
- `message` (string, required): Human-readable description of the failure. Example: `An error occurred`.
- `type` (string, required): Coarse, stable classifier for the failure. Present on every error response including 5xx. This is the field to branch on: `statusCode` is too coarse and `message` is human prose that may be reworded. The set is closed and every member is permanent, so it is safe to handle exhaustively. One of `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `invalid_state_error`, `conflict_error`, `rate_limit_error`, `payment_error`, `api_error`. Example: `invalid_request_error`.
- `code` (string): Fine-grained identifier for the failure, present only where it adds something `type` does not — for example separating a replayed idempotency key from a held lock, or naming the reason a payment was declined. The set is open and grows over time, so treat an unrecognised value as absent and fall back to `type`. Example: `validation_failed`.

### `413`

The request exceeded a limit on what this API accepts and was refused before the operation ran, so nothing was created or changed. The body must be under 4 MB. `type` is `invalid_request_error`, and `message` names the limit that was met. Reduce the request below the limit and send it again.

Type: object (ErrorResponse).

- `statusCode` (number, required): HTTP status code. Example: `400`.
- `requestId` (string, required): Unique identifier for the request. Example: `dfc10de3-36bb-4bcc-b081-316216194033`.
- `message` (string, required): Human-readable description of the failure. Example: `An error occurred`.
- `type` (string, required): Coarse, stable classifier for the failure. Present on every error response including 5xx. This is the field to branch on: `statusCode` is too coarse and `message` is human prose that may be reworded. The set is closed and every member is permanent, so it is safe to handle exhaustively. One of `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `invalid_state_error`, `conflict_error`, `rate_limit_error`, `payment_error`, `api_error`. Example: `invalid_request_error`.
- `code` (string): Fine-grained identifier for the failure, present only where it adds something `type` does not — for example separating a replayed idempotency key from a held lock, or naming the reason a payment was declined. The set is open and grows over time, so treat an unrecognised value as absent and fall back to `type`. Example: `validation_failed`.

### `429`

Too many requests. The rate limit is applied per client across all operations. `type` is `rate_limit_error`.

Type: object (ErrorResponse).

- `statusCode` (number, required): HTTP status code. Example: `400`.
- `requestId` (string, required): Unique identifier for the request. Example: `dfc10de3-36bb-4bcc-b081-316216194033`.
- `message` (string, required): Human-readable description of the failure. Example: `An error occurred`.
- `type` (string, required): Coarse, stable classifier for the failure. Present on every error response including 5xx. This is the field to branch on: `statusCode` is too coarse and `message` is human prose that may be reworded. The set is closed and every member is permanent, so it is safe to handle exhaustively. One of `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `invalid_state_error`, `conflict_error`, `rate_limit_error`, `payment_error`, `api_error`. Example: `invalid_request_error`.
- `code` (string): Fine-grained identifier for the failure, present only where it adds something `type` does not — for example separating a replayed idempotency key from a held lock, or naming the reason a payment was declined. The set is open and grows over time, so treat an unrecognised value as absent and fall back to `type`. Example: `validation_failed`.

### `500`

The request could not be completed because of an unexpected error. `type` is `api_error`.

Type: object (ErrorResponse).

- `statusCode` (number, required): HTTP status code. Example: `400`.
- `requestId` (string, required): Unique identifier for the request. Example: `dfc10de3-36bb-4bcc-b081-316216194033`.
- `message` (string, required): Human-readable description of the failure. Example: `An error occurred`.
- `type` (string, required): Coarse, stable classifier for the failure. Present on every error response including 5xx. This is the field to branch on: `statusCode` is too coarse and `message` is human prose that may be reworded. The set is closed and every member is permanent, so it is safe to handle exhaustively. One of `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `invalid_state_error`, `conflict_error`, `rate_limit_error`, `payment_error`, `api_error`. Example: `invalid_request_error`.
- `code` (string): Fine-grained identifier for the failure, present only where it adds something `type` does not — for example separating a replayed idempotency key from a held lock, or naming the reason a payment was declined. The set is open and grows over time, so treat an unrecognised value as absent and fall back to `type`. Example: `validation_failed`.

### `503`

A dependency needed to serve the request is temporarily unavailable — for every operation the auth service that verifies credentials and resolves entitlement, and on the provisioning routes also the ODUS API the OMS reconciles against. `type` is `api_error`. Unlike a plain 500 the condition is transient rather than a fault in the request, so it is worth retrying with backoff.

Type: object (ErrorResponse).

- `statusCode` (number, required): HTTP status code. Example: `400`.
- `requestId` (string, required): Unique identifier for the request. Example: `dfc10de3-36bb-4bcc-b081-316216194033`.
- `message` (string, required): Human-readable description of the failure. Example: `An error occurred`.
- `type` (string, required): Coarse, stable classifier for the failure. Present on every error response including 5xx. This is the field to branch on: `statusCode` is too coarse and `message` is human prose that may be reworded. The set is closed and every member is permanent, so it is safe to handle exhaustively. One of `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `invalid_state_error`, `conflict_error`, `rate_limit_error`, `payment_error`, `api_error`. Example: `invalid_request_error`.
- `code` (string): Fine-grained identifier for the failure, present only where it adds something `type` does not — for example separating a replayed idempotency key from a held lock, or naming the reason a payment was declined. The set is open and grows over time, so treat an unrecognised value as absent and fall back to `type`. Example: `validation_failed`.

### `504`

The request exceeded the processing time limit and was abandoned. `type` is `api_error` and `code` is `timeout` — unlike a plain 500 the request may still have taken effect.

Type: object (ErrorResponse).

- `statusCode` (number, required): HTTP status code. Example: `400`.
- `requestId` (string, required): Unique identifier for the request. Example: `dfc10de3-36bb-4bcc-b081-316216194033`.
- `message` (string, required): Human-readable description of the failure. Example: `An error occurred`.
- `type` (string, required): Coarse, stable classifier for the failure. Present on every error response including 5xx. This is the field to branch on: `statusCode` is too coarse and `message` is human prose that may be reworded. The set is closed and every member is permanent, so it is safe to handle exhaustively. One of `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `invalid_state_error`, `conflict_error`, `rate_limit_error`, `payment_error`, `api_error`. Example: `invalid_request_error`.
- `code` (string): Fine-grained identifier for the failure, present only where it adds something `type` does not — for example separating a replayed idempotency key from a held lock, or naming the reason a payment was declined. The set is open and grows over time, so treat an unrecognised value as absent and fall back to `type`. Example: `validation_failed`.

---

Generated from the OMS API OpenAPI document, https://sandbox-oms-api.odus.com/openapi.json. Interactive page: https://docs.odus.com/docs/api/oms/order-controller-bulk-fulfill