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

# Create ASN

> Create an Advanced Shipping Notice for inbound shipments

<Note>
  This endpoint creates a new ASN (Advanced Shipping Notice) to notify about incoming shipments from suppliers. ASNs help warehouses prepare for receiving inventory and automate the receiving process.
</Note>

## Authentication

This endpoint requires a valid API key with `asns:write` permissions.

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Request Body

<ParamField body="purchase_order_id" type="string" required>
  The purchase order ID this ASN is associated with
</ParamField>

<ParamField body="supplier_id" type="string" required>
  The supplier ID sending the shipment
</ParamField>

<ParamField body="shipment_date" type="string" required>
  Date when the shipment was sent (ISO 8601)
</ParamField>

<ParamField body="expected_arrival_date" type="string" required>
  Expected delivery date at warehouse (ISO 8601)
</ParamField>

<ParamField body="warehouse_id" type="string" required>
  Destination warehouse ID
</ParamField>

<ParamField body="tracking_info" type="object" required>
  Shipping and tracking information

  <Expandable title="Tracking info properties">
    <ParamField body="carrier" type="string" required>
      Carrier name (e.g., "UPS", "FedEx", "DHL")
    </ParamField>

    <ParamField body="tracking_number" type="string" required>
      Primary tracking number
    </ParamField>

    <ParamField body="service_type" type="string">
      Service level (e.g., "Ground", "Express", "2-Day")
    </ParamField>

    <ParamField body="additional_tracking_numbers" type="array">
      Additional tracking numbers for multi-package shipments
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="items" type="array" required>
  Array of items being shipped

  <Expandable title="Item object properties">
    <ParamField body="sku" type="string" required>
      Product SKU
    </ParamField>

    <ParamField body="quantity_shipped" type="integer" required>
      Quantity being shipped
    </ParamField>

    <ParamField body="quantity_ordered" type="integer">
      Original quantity ordered (for reference)
    </ParamField>

    <ParamField body="unit_cost" type="object">
      Cost per unit

      <Expandable title="Cost properties">
        <ParamField body="amount" type="integer">
          Cost in cents
        </ParamField>

        <ParamField body="currency" type="string">
          ISO 4217 currency code
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="lot_number" type="string">
      Lot or batch number for tracking
    </ParamField>

    <ParamField body="expiration_date" type="string">
      Expiration date for perishable items (ISO 8601)
    </ParamField>

    <ParamField body="serial_numbers" type="array">
      Array of serial numbers for serialized items
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="packaging_details" type="object">
  Packaging and palletization information

  <Expandable title="Packaging properties">
    <ParamField body="total_packages" type="integer">
      Total number of packages/boxes
    </ParamField>

    <ParamField body="total_pallets" type="integer">
      Total number of pallets
    </ParamField>

    <ParamField body="total_weight" type="object">
      Total shipment weight

      <Expandable title="Weight properties">
        <ParamField body="value" type="number">
          Weight value
        </ParamField>

        <ParamField body="unit" type="string">
          Weight unit (e.g., "lb", "kg")
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="packages" type="array">
      Detailed package information

      <Expandable title="Package properties">
        <ParamField body="package_id" type="string">
          Unique package identifier
        </ParamField>

        <ParamField body="type" type="string">
          Package type (e.g., "box", "pallet", "crate")
        </ParamField>

        <ParamField body="dimensions" type="object">
          Package dimensions
        </ParamField>

        <ParamField body="weight" type="object">
          Package weight
        </ParamField>

        <ParamField body="items" type="array">
          Items contained in this package
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="shipping_documents" type="array">
  Related shipping documents

  <Expandable title="Document properties">
    <ParamField body="type" type="string" required>
      Document type (e.g., "packing\_list", "bill\_of\_lading", "commercial\_invoice")
    </ParamField>

    <ParamField body="document_number" type="string">
      Document reference number
    </ParamField>

    <ParamField body="url" type="string">
      URL to access the document
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="notes" type="string">
  Additional notes or special instructions for receiving
</ParamField>

<ParamField body="metadata" type="object">
  Additional custom fields as key-value pairs
</ParamField>

### Response

<ResponseField name="id" type="string">
  Unique ASN identifier
</ResponseField>

<ResponseField name="object" type="string">
  Always "asn"
</ResponseField>

<ResponseField name="asn_number" type="string">
  System-generated ASN number
</ResponseField>

<ResponseField name="status" type="string">
  ASN status: "pending", "in\_transit", "delivered", "received", "cancelled"
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of creation
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp of last update
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --location --request POST 'https://api.stateset.com/v1/asns' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data-raw '{
      "purchase_order_id": "po_123456789",
      "supplier_id": "sup_abc123",
      "shipment_date": "2024-01-15T14:00:00Z",
      "expected_arrival_date": "2024-01-18T10:00:00Z",
      "warehouse_id": "wh_001",
      "tracking_info": {
          "carrier": "UPS",
          "tracking_number": "1Z999AA10123456784",
          "service_type": "Ground"
      },
      "items": [
          {
              "sku": "WBH-001",
              "quantity_shipped": 500,
              "quantity_ordered": 500,
              "unit_cost": {
                  "amount": 7500,
                  "currency": "USD"
              },
              "lot_number": "LOT-2024-001"
          },
          {
              "sku": "USB-C-001",
              "quantity_shipped": 1000,
              "quantity_ordered": 1000,
              "unit_cost": {
                  "amount": 450,
                  "currency": "USD"
              },
              "lot_number": "LOT-2024-002"
          }
      ],
      "packaging_details": {
          "total_packages": 10,
          "total_pallets": 2,
          "total_weight": {
              "value": 250,
              "unit": "lb"
          }
      },
      "notes": "Please schedule receiving appointment. Fragile electronics."
  }'
  ```

  ```graphQL GraphQL theme={null}
  mutation CreateASN {
    createASN(input: {
      purchase_order_id: "po_123456789"
      supplier_id: "sup_abc123"
      shipment_date: "2024-01-15T14:00:00Z"
      expected_arrival_date: "2024-01-18T10:00:00Z"
      warehouse_id: "wh_001"
      tracking_info: {
        carrier: "UPS"
        tracking_number: "1Z999AA10123456784"
        service_type: "Ground"
      }
      items: [
        {
          sku: "WBH-001"
          quantity_shipped: 500
          unit_cost: {
            amount: 7500
            currency: "USD"
          }
        }
      ]
    }) {
      id
      asn_number
      status
      expected_arrival_date
      items {
        sku
        quantity_shipped
      }
    }
  }
  ```

  ```javascript Node.js theme={null}
  const asn = await stateset.asns.create({
    purchase_order_id: "po_123456789",
    supplier_id: "sup_abc123",
    shipment_date: "2024-01-15T14:00:00Z",
    expected_arrival_date: "2024-01-18T10:00:00Z",
    warehouse_id: "wh_001",
    tracking_info: {
      carrier: "UPS",
      tracking_number: "1Z999AA10123456784",
      service_type: "Ground"
    },
    items: [
      {
        sku: "WBH-001",
        quantity_shipped: 500,
        quantity_ordered: 500,
        unit_cost: {
          amount: 7500,
          currency: "USD"
        },
        lot_number: "LOT-2024-001"
      }
    ],
    packaging_details: {
      total_packages: 10,
      total_pallets: 2,
      total_weight: {
        value: 250,
        unit: "lb"
      }
    }
  });
  ```

  ```python Python theme={null}
  asn = stateset.asns.create({
      "purchase_order_id": "po_123456789",
      "supplier_id": "sup_abc123",
      "shipment_date": "2024-01-15T14:00:00Z",
      "expected_arrival_date": "2024-01-18T10:00:00Z",
      "warehouse_id": "wh_001",
      "tracking_info": {
          "carrier": "UPS",
          "tracking_number": "1Z999AA10123456784",
          "service_type": "Ground"
      },
      "items": [
          {
              "sku": "WBH-001",
              "quantity_shipped": 500,
              "quantity_ordered": 500,
              "unit_cost": {
                  "amount": 7500,
                  "currency": "USD"
              },
              "lot_number": "LOT-2024-001"
          }
      ]
  })
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "asn_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
    "object": "asn",
    "asn_number": "ASN-2024-00001",
    "status": "pending",
    "created_at": "2024-01-15T14:30:00Z",
    "updated_at": "2024-01-15T14:30:00Z",
    "purchase_order_id": "po_123456789",
    "supplier_id": "sup_abc123",
    "warehouse_id": "wh_001",
    "shipment_date": "2024-01-15T14:00:00Z",
    "expected_arrival_date": "2024-01-18T10:00:00Z",
    "actual_arrival_date": null,
    "tracking_info": {
      "carrier": "UPS",
      "tracking_number": "1Z999AA10123456784",
      "service_type": "Ground",
      "tracking_url": "https://www.ups.com/track?tracknum=1Z999AA10123456784"
    },
    "items": [
      {
        "id": "asn_item_123",
        "sku": "WBH-001",
        "product_name": "Wireless Bluetooth Headphones",
        "quantity_shipped": 500,
        "quantity_ordered": 500,
        "quantity_received": 0,
        "unit_cost": {
          "amount": 7500,
          "currency": "USD"
        },
        "lot_number": "LOT-2024-001",
        "status": "pending"
      },
      {
        "id": "asn_item_124",
        "sku": "USB-C-001",
        "product_name": "USB-C Charging Cable",
        "quantity_shipped": 1000,
        "quantity_ordered": 1000,
        "quantity_received": 0,
        "unit_cost": {
          "amount": 450,
          "currency": "USD"
        },
        "lot_number": "LOT-2024-002",
        "status": "pending"
      }
    ],
    "packaging_details": {
      "total_packages": 10,
      "total_pallets": 2,
      "total_weight": {
        "value": 250,
        "unit": "lb"
      }
    },
    "notes": "Please schedule receiving appointment. Fragile electronics.",
    "metadata": {}
  }
  ```
</ResponseExample>