> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skynetparts.com/llms.txt
> Use this file to discover all available pages before exploring further.

# place-an-order

> Create a B2B order for one or more parts.

Send a list of parts and quantities along with your PO number. The response confirms the order, your real B2B prices, and the total.

```http theme={null}
POST https://api.skynet-docs.skynetparts.com/public/api/v1/b2b/orders
```

Requires an API key. See [Authentication](/authentication) for how to get one.

<Warning>
  Always send a unique `Idempotency-Key` header. Without one, a network retry could create a duplicate order.
</Warning>

## Headers

| Header            | Required | Value                      |
| ----------------- | -------- | -------------------------- |
| `Authorization`   | Yes      | `Bearer sk_live_...`       |
| `Content-Type`    | Yes      | `application/json`         |
| `Idempotency-Key` | Yes      | A unique string per order. |

### About `Idempotency-Key`

A unique string you make up for each order anything you want, like your PO number plus today's date. If your network drops and you retry the same request with the same `Idempotency-Key`, we return the original order instead of creating a duplicate. Always send one.

## Body

<ParamField body="items" type="object[]" required>
  The parts to order. At least one entry.
</ParamField>

<ParamField body="items[].part_id" type="string" required>
  From the Look Up Parts response.
</ParamField>

<ParamField body="items[].quantity" type="integer" required>
  Positive integer.
</ParamField>

<ParamField body="po_number" type="string" required>
  Your internal purchase order number.
</ParamField>

<ParamField body="notes" type="string">
  Free-text note that appears on the order paperwork.
</ParamField>

<RequestExample>
  ```bash curl theme={null}
  curl -X POST https://api.skynet-docs.skynetparts.com/public/api/v1/b2b/orders \
    -H "Authorization: Bearer $SKYNET_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: ACME-PO-4471-2026-06-03" \
    -d '{
      "items": [
        { "part_id": "skynet_part_BWxLDSfV6dFV5o40VwVTV0arE-5dVB7VE22Jd1bb40zYqKv2eI7lRPsBJGk0JleZRO1NI5VQz6qe7KifEy24PQGAL0bZbcE", "quantity": 10 }
      ],
      "po_number": "ACME-PO-4471",
      "notes": "Deliver to Hangar B"
    }'
  ```

  ```javascript Node theme={null}
  const res = await fetch("https://api.skynet-docs.skynetparts.com/public/api/v1/b2b/orders", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.SKYNET_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": "ACME-PO-4471-2026-06-03",
    },
    body: JSON.stringify({
      items: [
        {
          part_id: "skynet_part_BWxLDSfV6dFV5o40VwVTV0arE-5dVB7VE22Jd1bb40zYqKv2eI7lRPsBJGk0JleZRO1NI5VQz6qe7KifEy24PQGAL0bZbcE",
          quantity: 10,
        },
      ],
      po_number: "ACME-PO-4471",
      notes: "Deliver to Hangar B",
    }),
  });
  console.log(await res.json());
  ```

  ```python Python theme={null}
  import os, requests

  res = requests.post(
      "https://api.skynet-docs.skynetparts.com/public/api/v1/b2b/orders",
      headers={
          "Authorization": f"Bearer {os.environ['SKYNET_API_KEY']}",
          "Idempotency-Key": "ACME-PO-4471-2026-06-03",
      },
      json={
          "items": [
              {
                  "part_id": "skynet_part_BWxLDSfV6dFV5o40VwVTV0arE-5dVB7VE22Jd1bb40zYqKv2eI7lRPsBJGk0JleZRO1NI5VQz6qe7KifEy24PQGAL0bZbcE",
                  "quantity": 10,
              }
          ],
          "po_number": "ACME-PO-4471",
          "notes": "Deliver to Hangar B",
      },
  )
  print(res.json())
  ```
</RequestExample>

<CodeGroup>
  ```bash Multiple parts in one order theme={null}
  curl -X POST https://api.skynet-docs.skynetparts.com/public/api/v1/b2b/orders \
    -H "Authorization: Bearer $SKYNET_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: ACME-PO-4471-2026-06-03" \
    -d '{
      "items": [
        { "part_id": "skynet_part_AAA...", "quantity": 10 },
        { "part_id": "skynet_part_BBB...", "quantity": 4 }
      ],
      "po_number": "ACME-PO-4471"
    }'
  ```
</CodeGroup>

<ResponseExample>
  ```json Success theme={null}
  {
    "success": true,
    "order": {
      "order_id": "skynet_order_8f2a1c",
      "status": "open",
      "po_number": "ACME-PO-4471",
      "line_items": [
        {
          "part_number": "MS21042L3",
          "title": "Self-Locking Nut, MS21042L3",
          "quantity": 10,
          "unit_price": { "amount": "11.16", "currency": "USD" },
          "line_total": { "amount": "111.60", "currency": "USD" }
        }
      ],
      "subtotal": { "amount": "111.60", "currency": "USD" },
      "created_at": "2026-06-03T14:30:00Z"
    }
  }
  ```

  ```json Not enough stock theme={null}
  {
    "success": false,
    "error": {
      "code": "INSUFFICIENT_INVENTORY",
      "message": "One or more items don't have enough stock.",
      "details": {
        "items": [
          {
            "part_number": "MS21042L3",
            "requested": 10,
            "available": 3
          }
        ]
      }
    }
  }
  ```

  ```json Invalid key theme={null}
  {
    "success": false,
    "error": {
      "code": "INVALID_API_KEY",
      "message": "Authorization header missing or malformed."
    }
  }
  ```
</ResponseExample>

## Response fields

<ResponseField name="success" type="boolean">
  `true` when the order is created.
</ResponseField>

<ResponseField name="order.order_id" type="string">
  An opaque order ID. Use this when contacting support about an order.
</ResponseField>

<ResponseField name="order.status" type="string">
  `open` means the order has been placed on your account's Net payment terms (unpaid until invoiced) and appears under Orders in your Skynet B2B account, pending fulfillment.
</ResponseField>

<ResponseField name="order.po_number" type="string">
  Your internal PO number, echoed back from the request.
</ResponseField>

<ResponseField name="order.line_items" type="object[]">
  One entry per item you ordered. Note: `line_items` do not include the `part_id` from your request once an order is placed, you reference it by `order_id` and `po_number`, not by individual part.
</ResponseField>

<ResponseField name="order.line_items[].part_number" type="string">
  The manufacturer part number for this line.
</ResponseField>

<ResponseField name="order.line_items[].title" type="string">
  Human-readable name for the part.
</ResponseField>

<ResponseField name="order.line_items[].quantity" type="integer">
  Units ordered on this line.
</ResponseField>

<ResponseField name="order.line_items[].unit_price" type="object">
  The price you actually pay per unit. This is your B2B price for this part  may be lower than the catalog price shown when you looked up the part. Contains `amount` and `currency`.
</ResponseField>

<ResponseField name="order.line_items[].line_total" type="object">
  `unit_price` × `quantity` for this line. Contains `amount` and `currency`.
</ResponseField>

<ResponseField name="order.subtotal" type="object">
  The sum of all `line_total` values. Final invoice may include tax, shipping, and other adjustments depending on your account terms.
</ResponseField>

<ResponseField name="order.created_at" type="string">
  ISO 8601 UTC timestamp.
</ResponseField>

## Errors

These codes apply to this endpoint:

| Code                      | HTTP | Meaning                                                                                           |
| ------------------------- | ---- | ------------------------------------------------------------------------------------------------- |
| `VALIDATION_FAILED`       | 400  | Body is missing a field or has the wrong type.                                                    |
| `INVALID_PART_TOKEN`      | 400  | A `part_id` you sent isn't recognized. Look up the part again.                                    |
| `INVALID_API_KEY`         | 401  | Your API key is missing, malformed, or wrong.                                                     |
| `KEY_REVOKED`             | 401  | The key was revoked. Email [info@skynetparts.com](mailto:info@skynetparts.com) for a replacement. |
| `INSUFFICIENT_INVENTORY`  | 409  | One or more items don't have enough stock. Response lists which.                                  |
| `IDEMPOTENCY_CONFLICT`    | 409  | You sent an `Idempotency-Key` we've already seen, but with a different order body.                |
| `IDEMPOTENCY_IN_PROGRESS` | 409  | A request with this `Idempotency-Key` is still being processed. Retry shortly.                    |
| `ORDER_FAILED`            | 502  | Order placement failed on our end. Your order was not placed. Safe to retry.                      |

See [Error codes](/reference/errors) for the full list and response shape.