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

# Create Shipment

### Overview

This endpoint can be used to create new shipments.

A maximum of 10 shipments can be created in a single request.

Endpoint: `/api/v1/shipments`

Method: `POST`

<Warning>
  It is critical that you [verify the fulfillment and destination addresses](/guide/api/addresses/verify) before using them.

  Failure to verify the addresses may result in loss or delayed shipments.

  You may also be **charged** should address correction be necessary by the carrier.
</Warning>

### Request

<Note>
  When creating a shipment, you can use either of the following two approaches to specify the fulfillment and destination addresses:

  * Use the `fulfillment_address_id` and `destination_address_id` fields to reference existing addresses that have already been stored on ArtPort.
  * Provide the address details directly in the `fulfillment_address` and `destination_address` fields.

  You can also combine these approaches. For example, by using a `fulfillment_address_id` and a `destination_address`, or vice versa.

  For examples of how to use these fields, see the request examples on this page.
</Note>

<ResponseField name="shipments" type="array" required>
  Array of shipment objects to be created.

  Minimum objects in the array: `1`

  Maximum objects in the array: `10`

  Each shipment object must consist of the following fields:

  <Expandable title="shipments" defaultOpen="true">
    <ResponseField name="title" type="string" required>
      The name or a brief description of the piece. You can also use an internal reference number.

      Minimum character length: `2`

      Maximum character length: `50`
    </ResponseField>

    <ResponseField name="value" type="integer" required>
      The value of the artwork in USD \$.

      Always use an accurate value to make sure that any insurance claims are properly honored.

      Minimum value: `50`

      Maximum value: `10000`
    </ResponseField>

    <ResponseField name="length" type="integer" required>
      The length of the piece in inches.

      Minimum length: `17`

      Maximum length: `44`
    </ResponseField>

    <ResponseField name="height" type="integer" required>
      The height of the piece in inches.

      Minimum height: `13`

      Maximum height: `34`
    </ResponseField>

    <ResponseField name="depth" type="integer" required>
      The depth of the piece in inches.

      Minimum depth: `1`

      Maximum depth: `4`
    </ResponseField>

    <ResponseField name="service" type="integer" required>
      A [Service](/guide/enums/services) enum representing the service to be used for the shipment.
    </ResponseField>

    <ResponseField name="fulfillment_address_id" type="integer">
      The ID of an existing address to be used as the fulfillment address.

      <Note>This field is required if the `fulfillment_address` field is not provided.</Note>
    </ResponseField>

    <ResponseField name="fulfillment_address" type="array">
      An object containing the fulfillment address details.

      <Note>This field is required if the `fulfillment_address_id` field is not provided.</Note>

      <Expandable title="fulfillment_address" defaultOpen="true">
        <ResponseField name="name" type="string" required>
          For example, "John Smith" or "Acme Products".

          Minimum character length: `2`

          Maximum character length: `50`
        </ResponseField>

        <ResponseField name="email" type="string" required>
          The contact email address.

          Carriers may send one or more shipment tracking notifications to this email address.

          Minimum character length: `6`

          Maximum character length: `100`
        </ResponseField>

        <ResponseField name="phone" type="string" required>
          The contact phone number.

          This must be formatted using the [E.164 standard](/guide/concepts/formatting#phone-numbers).

          Minimum character length: `7`

          Maximum character length: `30`
        </ResponseField>

        <ResponseField name="line_1" type="string" required>
          Line 1 of the address.

          Minimum character length: `2`

          Maximum character length: `35`
        </ResponseField>

        <ResponseField name="line_2" type="string">
          Line 2 of the address.

          Minimum character length: `2`

          Maximum character length: `35`
        </ResponseField>

        <ResponseField name="city" type="string" required>
          The address' town or city.

          Minimum character length: `2`

          Maximum character length: `35`
        </ResponseField>

        <ResponseField name="region" type="string" required>
          The address' state, province, or region.

          Minimum character length: `2`

          Maximum character length: `30`
        </ResponseField>

        <ResponseField name="post_code" type="string" required>
          The address' post code.

          Minimum character length: `2`

          Maximum character length: `16`
        </ResponseField>

        <ResponseField name="country" type="integer" required>
          A [Country](/guide/enums/countries) enum representing the address' country.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="destination_address_id" type="integer">
      The ID of an existing address to be used as the destination address.

      <Note>This field is required if the `destination_address` field is not provided.</Note>
    </ResponseField>

    <ResponseField name="destination_address" type="array">
      An object containing the destination address details.

      <Note>This field is required if the `destination_address_id` field is not provided.</Note>

      <Expandable title="destination_address" defaultOpen="true">
        <ResponseField name="name" type="string" required>
          For example, "John Smith" or "Acme Products".

          Minimum character length: `2`

          Maximum character length: `50`
        </ResponseField>

        <ResponseField name="email" type="string" required>
          The contact email address.

          Carriers may send one or more shipment tracking notifications to this email address.

          Minimum character length: `6`

          Maximum character length: `100`
        </ResponseField>

        <ResponseField name="phone" type="string" required>
          The contact phone number.

          This must be formatted using the [E.164 standard](/guide/concepts/formatting#phone-numbers).

          Minimum character length: `7`

          Maximum character length: `30`
        </ResponseField>

        <ResponseField name="line_1" type="string" required>
          Line 1 of the address.

          Minimum character length: `2`

          Maximum character length: `35`
        </ResponseField>

        <ResponseField name="line_2" type="string">
          Line 2 of the address.

          Minimum character length: `2`

          Maximum character length: `35`
        </ResponseField>

        <ResponseField name="city" type="string" required>
          The address' town or city.

          Minimum character length: `2`

          Maximum character length: `35`
        </ResponseField>

        <ResponseField name="region" type="string" required>
          The address' state, province, or region.

          Minimum character length: `2`

          Maximum character length: `30`
        </ResponseField>

        <ResponseField name="post_code" type="string" required>
          The address' post code.

          Minimum character length: `2`

          Maximum character length: `16`
        </ResponseField>

        <ResponseField name="country" type="integer" required>
          A [Country](/guide/enums/countries) enum representing the address' country.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Response

If the shipments are successfully created, the API will return a `201 Created` status code.

The response will contain the following content:

<ResponseField name="shipments" type="array" required>
  Details of the newly created shipments.

  <Expandable title="shipments" defaultOpen="true">
    <ResponseField name="id" type="integer" required>
      The ID of the newly created shipment.
    </ResponseField>

    <ResponseField name="title" type="string" required>
      The title of the newly created shipment.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```json Request (with address IDs) theme={"system"}
  {
      "shipments": [
          {
              "title": "Test Shipment",
              "value": 1000,
              "length": 17,
              "height": 13,
              "depth": 1,
              "service": 1,
              "fulfillment_address_id": 123,
              "destination_address_id": 456,
          },
          // Additional shipments to be created...
      ]
  }
  ```

  ```json Request (with address details) theme={"system"}
  {
      "shipments": [
          {
              "title": "Test Shipment",
              "value": 1000,
              "length": 17,
              "height": 13,
              "depth": 1,
              "service": 1,
              "fulfillment_address": {
                  "name": "Schaefer, Nolan and Wehner",
                  "email": "dave45@gmail.com",
                  "phone": "+12069536978",
                  "line_1": "492 Quitzon Avenue Apt. 157",
                  "line_2": "Apt. 027",
                  "city": "Gustside",
                  "region": "Massachusetts",
                  "post_code": "17594-7013",
                  "country": 1
              },
              "destination_address": {
                  "name": "Krajcik, Kuhn and Eichmann",
                  "email": "teresa93@gmail.com",
                  "phone": "+12069536978",
                  "line_1": "1712 Marina Ramp Suite 512",
                  "line_2": "Apt. 235",
                  "city": "Port Marlon",
                  "region": "Indiana",
                  "post_code": "62893",
                  "country": 1
              }
          },
          // Additional shipments to be created...
      ]
  }
  ```

  ```json Request (mixed) theme={"system"}
  {
      "shipments": [
          {
              "title": "Test Shipment",
              "value": 1000,
              "length": 17,
              "height": 13,
              "depth": 1,
              "service": 1,
              "fulfillment_address_id": 123,
              "destination_address": {
                  "name": "Krajcik, Kuhn and Eichmann",
                  "email": "teresa93@gmail.com",
                  "phone": "+12069536978",
                  "line_1": "1712 Marina Ramp Suite 512",
                  "line_2": "Apt. 235",
                  "city": "Port Marlon",
                  "region": "Indiana",
                  "post_code": "62893",
                  "country": 1
              }
          },
          // Additional shipments to be created...
      ]
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={"system"}
  {
      "shipments": [
          {
              "id": 10011,
              "title": "Shipment 1",
          },
          {
              "id": 10012,
              "title": "Shipment 2",
          }
      ]
  }
  ```
</ResponseExample>