# Add items to an order from payments

`POST /orders/{orderId}/add-items`

OMS API, Orders.

Adds order items from existing payments (selected by id) to an unfulfilled order that has not been sent to your fulfillment provider. The order qualifies while no submission has been attempted (`lastSubmissionAttemptedAt` is empty) and its `tplSubmissionStatus` is either `pending` with `submitToTplAt` still ahead, or one no provider receives the order from: `null`, `skipped_no_route`, `skipped_no_country`, `skipped_no_shippable_items`, `skipped_route_conflict` or `skipped_integration_inactive`. Any other order is refused with a `400`, since your provider would never receive the added items: import the payments as an order of their own with `POST /orders/import` instead. All-or-nothing: if any payment is already imported, missing, not succeeded, reversed, charged back, failed to capture, has no line items belonging to a product enabled for Order Management, or does not match the order's customer/currency, no items are added and every failing payment is reported.

**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>`.

## Parameters

### Path parameters

- `orderId` (string, required)

## Request body

Content type `application/json`, required.

Type: object (AddOrderItemsRequestDTO).

- `paymentIds` (array of string, required): The ODUS payment IDs whose items are added to the order. Up to 10 per request. Minimum items 1.

## Responses

### `200`

Type: object (AddOrderItemsResultDTO).

- `orderId` (string, required): The order the items were added to.
- `total` (number, required): Number of unique payment IDs processed.
- `added` (number, required): Number of payments whose items were added to the order.
- `errors` (array of object, required): Per-payment errors. When this is non-empty no items are added, because the operation is all-or-nothing.
  - `paymentId` (string, required): The payment ID that could not be imported.
  - `reason` (string, required): Why the payment could not be imported. One of `already_imported`, `payment_not_found`, `payment_not_succeeded`, `payment_reversed`, `payment_chargebacked`, `no_shippable_products`, `currency_mismatch`, `customer_mismatch`.
  - `message` (string, required): Human-readable explanation of the error.

### `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`.

### `404`

No resource exists with the requested identifier. `type` is `not_found_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-add-items