Create a Shipment

POST /shipments

This endpoint is used for two purposes:

1. Generating standard Arta shipments

All standard shipments are actively facilitated by Arta. Working in tandem with our extensive logistics carrier network, Arta fulfills shipments with Premium, Select, and Parcel quote types from scheduling collection, to coordinating packing, through delivery. For shipments with the Self Ship quote type, Arta will generate labels on your behalf with commercial carriers such as FedEx, UPS, and DHL.

To book a standard Arta shipment, you must first create a shipping quote request. You can then use a quote_id returned by the quote request endpoint to create the shipment.

2. Generating Track shipments

Track shipments provide a similar customer tracking and notification experience as standard Arta shipments but for shipments you have booked with commercial carriers outside of the Arta platform.

To create a Track shipment, you provide the carrier and tracking_number purchased externally and the Arta platform provides status automation, tracking pages, and customer notifications. You may optionally provide additional supplementary information such as origin, destination, and package details for Track shipments.

Note that Track shipments are a beta feature. Please contact your account manager or hello@arta.io to request access for your organization.

Headers

  • Authorization string Required

    Authorize your API calls with an Arta API token

application/json

Body object

One of:
ArtaShipmentPayload object TrackShipmentPayload object

Responses

  • 201 application/json

    The created shipment

    Hide headers attributes Show headers attributes
    • content-type string
    • x-arta-request-id string

      A unique identifier for the Arta API call

    Hide response attributes Show response attributes object
    • created_at string(date-time)

      A NaiveDatetime-formatted timestamp describing when the resource was created with microsecond precision

    • destination object
      Hide destination attributes Show destination attributes object
      • access_restrictions array[string] Deprecated

        Id of location restriction type

      • address_line_1 string

        First line of address

      • address_line_2 string | null

        Second line of address

      • address_line_3 string | null

        Third line of address

      • city string

        City

      • contacts array[object]

        A list of contacts at the location

        Hide contacts attributes Show contacts attributes object
        • email_address string
        • name string Required
        • phone_number string
      • country string Required

        The ISO 3166-1 alpha-2 country code of the current or last known location if available

        Minimum length is 2, maximum length is 2.

      • postal_code string

        The postal code

      • region string

        Political region name, for US states and Canada provinces, use 2 letter abbreviations

      • title string

        The title or name of the location

    • eei_form_status string | null

      The status of an associated electronic export information document required for customs clearance. Returns null if the shipment does not have an associated EEI Form

      Values are not_required, required, submitted, approved, or rejected.

    • eei_form_url string | null

      The URL for an associated electronic export information form required for customs clearance. Returns null if the shipment does not have an associated EEI Form

    • emissions string | null

      The estimated CO2 emissions for the shipment

    • emissions_unit string | null

      The unit of measurement for emissions for this shipment. Typically measured in "kg_co2e" or "kilograms of carbon dioxide equivalent"

    • exceptions array[object]

      Shipment exceptions provide context about holds, delays, and other circumstances that may interrupt a shipment's fulfillment

      Hide exceptions attributes Show exceptions attributes object
      • created_at string(date-time)

        A NaiveDatetime-formatted timestamp describing when the exception was created with microsecond precision

      • exception_type_label string | null

        An additional label providing context about the exception type (optional)

      • hold_until string(date) | null

        The date the shipment will be held until

      • id string(uuid)

        The id of the exception in UUID format

      • package_id integer(int64) | null

        The package associated with this exception (optional)

      • resolution string | null

        A brief description of the method by which this exception was resolved

      • source string

        The source of the exception

      • status string

        The current status for this exception

        Values are new, in_progress, or resolved.

      • type string

        The type of exception

      • updated_at string(date-time)

        A NaiveDatetime-formatted timestamp describing when the exception was last updated with microsecond precision

    • hosted_session_id integer | null

      The ID of the HostedSession through which this shipment was created

    • id string(uuid)

      The id of the shipment in UUID format

    • insurance_policy object | null
      Hide insurance_policy attributes Show insurance_policy attributes object | null
      • amount string

        Format should match the following pattern: ^(0|([1-9]+[0-9]*))(\.[0-9]{1,2})?$.

      • amount_currency string

        ISO 4217 three-letter alphabetic currency code. Options are defined in the Currencies metadata endpoint

        Minimum length is 3, maximum length is 3. Format should match the following pattern: ^[A-Z]{3}$. Default value is USD.

      • id string
      • insured_value string

        Format should match the following pattern: ^(0|([1-9]+[0-9]*))(\.[0-9]{1,2})?$.

      • insured_value_currency string

        ISO 4217 three-letter alphabetic currency code. Options are defined in the Currencies metadata endpoint

        Minimum length is 3, maximum length is 3. Format should match the following pattern: ^[A-Z]{3}$. Default value is USD.

    • internal_reference string | null

      This field can be used to pass through any character data that you may want returned unaltered for your own later usage

      Maximum length is 255.

    • log_request_id string | null

      A string identifying the API request that created the shipment. This log_request_id may be used to find the Log associated with the source API request

    • object_count integer(int64)

      The count of objects included in the shipment

    • origin object
      Hide origin attributes Show origin attributes object
      • access_restrictions array[string] Deprecated

        Id of location restriction type

      • address_line_1 string

        First line of address

      • address_line_2 string | null

        Second line of address

      • address_line_3 string | null

        Third line of address

      • city string

        City

      • contacts array[object]

        A list of contacts at the location

        Hide contacts attributes Show contacts attributes object
        • email_address string
        • name string Required
        • phone_number string
      • country string Required

        The ISO 3166-1 alpha-2 country code of the current or last known location if available

        Minimum length is 2, maximum length is 2.

      • postal_code string

        The postal code

      • region string

        Political region name, for US states and Canada provinces, use 2 letter abbreviations

      • title string

        The title or name of the location

    • package_count integer(int64)

      The count of packages included in the shipment

    • packages array[object]
      Hide packages attributes Show packages attributes object
      • depth string

        The depth of the object

      • eta string | null

        The expected delivery date for this package in the MM/DD/YYYY format

      • handle_with_care boolean

        Set this flag to true if the package should be handled with care

      • height string

        The height of the object

      • id integer(int64)

        The id of the package

      • is_sufficiently_packed boolean

        Set this flag to true if the package is sufficiently packed

      • objects array[object]

        A list of objects in the package

        Hide objects attributes Show objects attributes object
        • current_packing array[string]

          A list of packing subtype IDs describing how the item is currently packed

        • customs object
          Hide customs attributes Show customs attributes object
          • country_of_origin string

            The ISO 3166-1 alpha-2 country code where the object was made or manufactured

            Minimum length is 2, maximum length is 2.

          • hs_code string

            The Harmonized System code for the object. This is a 6-10 digit code used to classify traded products

          • medium string

            The medium of the object. This is a description of the material or materials used to create the object

          • temporary_admission boolean

            Select true if the goods are currently in the country under a temporary admission declaration

        • depth string

          The depth of the object

        • details object
          Hide details attributes Show details attributes object
          • creation_date string

            Details about the timing in which an object was created

          • creator string

            The creator of the object

          • is_cites boolean

            Set to true if the object is governed by the Convention on International Trade in Endangered Species of Wild Fauna and Flora

            Default value is false.

          • is_fragile boolean

            Set this flag to true is the item is fragile. This may effect packing and handling costs

            Default value is false.

          • materials array[string] Deprecated

            A list of IDs describing the types of materials used

          • notes string

            Any notes about the item

          • title string

            The object title

        • height string

          The height of the object

        • id integer(int64)
        • images array[string(uri)]

          A list image urls of the object

        • internal_reference string

          This field can be used to pass through any data that you may want returned unaltered for your own later usage

          Maximum length is 255.

        • public_reference string

          A client defined name for the object. The value provided for public_reference may be presented in notification emails and on shipment detail pages

          Maximum length is 255.

        • subtype string

          The object subtype ID. Options are defined in the Object types metadata endpoint

          Format should match the following pattern: ^[0-9a-z_]{1,56}$.

        • unit_of_measurement string

          Values are in or cm.

        • value string

          Format should match the following pattern: ^(0|([1-9]+[0-9]*))(\.[0-9]{1,2})?$.

        • value_currency string

          ISO 4217 three-letter alphabetic currency code. Options are defined in the Currencies metadata endpoint

          Minimum length is 3, maximum length is 3. Format should match the following pattern: ^[A-Z]{3}$. Default value is USD.

        • weight string

          The weight of the object

        • weight_unit string

          The unit of the object

          Values are lb or kg.

        • width string

          The width of the object

      • packing_materials array[string]

        The id of a material.

      • status string | null

        The status of the package

      • unit_of_measurement string

        Values are in or cm.

      • weight string

        The weight of the object

      • weight_unit string

        The unit of the object

        Values are lb or kg.

      • width string

        The width of the object

    • payment_process string

      The primary method by which payment to Arta will be handled for any shipment booked through this hosted session

      Values are checkout or invoicing.

    • public_reference string | null

      A client defined name for the resource. The value provided for the public_reference field may appear in notification emails and public web pages

      Maximum length is 255.

    • quote_type string

      The ID of the quote type associated with this shipment

      Values are premium, select, parcel, or self_ship.

    • schedule object

      The schedule for the shipment

      Hide schedule attributes Show schedule attributes object
      • delivery_end string(date) | null
      • delivery_start string(date) | null
      • delivery_window_modifier string

        A qualifying word indicating how delivery_start and delivery_end together shape the delivery window. When present, values may be "after", "by", "on", or "between"

      • pickup_end string(date) | null
      • pickup_start string(date) | null
      • pickup_window_modifier string

        A qualifying word indicating how delivery_start and delivery_end together shape the delivery window. When present, values may be "after", "by", "on", or "between"

    • services array[object]

      A list of services included in the shipment

      Hide services attributes Show services attributes object
      • amount string

        Format should match the following pattern: ^(0|([1-9]+[0-9]*))(\.[0-9]{1,2})?$.

      • amount_currency string

        ISO 4217 three-letter alphabetic currency code. Options are defined in the Currencies metadata endpoint

        Minimum length is 3, maximum length is 3. Format should match the following pattern: ^[A-Z]{3}$. Default value is USD.

      • included_services array[object]

        A list of service IDs that are included in the service

        Hide included_services attributes Show included_services attributes object
        • name string

          The name of the service

        • sub_subtype string

          The service subsubtype ID. Options are defined in the Service types metadata endpoint

          Format should match the following pattern: ^[0-9a-z_]{1,56}$.

        • subtype string

          The service subtype ID. Options are defined in the Service types metadata endpoint

          Format should match the following pattern: ^[0-9a-z_]{1,56}$.

        • type string

          The service type ID. Options are defined in the Service types metadata endpoint

          Format should match the following pattern: ^[0-9a-z_]{1,56}$.

      • is_requested boolean

        Set this flag to true if the service is requested

      • is_required boolean

        Set this flag to true if the service is required

      • metadata object

        Additional data about the service. For services with a type value of "transport" generated through instant quoting, metadata may include reference_rate.provider and reference_rate.service_level fields that indicate the carrier and mode of transport used to price this service

      • name string

        The name of the service

      • sub_subtype string

        The service subsubtype ID. Options are defined in the Service types metadata endpoint

        Format should match the following pattern: ^[0-9a-z_]{1,56}$.

      • subtype string

        The service subtype ID. Options are defined in the Service types metadata endpoint

        Format should match the following pattern: ^[0-9a-z_]{1,56}$.

      • type string

        The service type ID. Options are defined in the Service types metadata endpoint

        Format should match the following pattern: ^[0-9a-z_]{1,56}$.

    • shipping_notes string | null

      Any additional unstructured notes to Arta about the shipment

      Maximum length is 255.

    • shortcode string

      A brief identifier for this shipment

    • status string

      The status for this shipment

      Maximum length is 255. Values are pending, confirmed, collected, in_transit, completed, or cancelled.

    • tags array[object]

      A list of tags associated with the shipment

      Hide tags attributes Show tags attributes object
      • color string

        The hexadecimal color code for the tag, without the leading #.

        Minimum length is 6, maximum length is 6. Format should match the following pattern: ^[0-9A-F]{6}$.

      • created_at string(date-time)

        A NaiveDatetime-formatted timestamp describing when the resource was created with microsecond precision

      • created_by integer(int64) | null

        The user ID associated with the user who created the tag when applicable.

      • description string | null

        An optional, brief description for this tag.

        Maximum length is 255.

      • id string(uuid)

        The id of the tag in UUID format

      • is_active boolean

        Indicates whether or not the tag is active. Inactive tags may not be associated to new resources

      • name string

        The name for the tag. It may contain lower case letters, dashes, and alphanumeric characters only. The maximum character count is 50.

        Maximum length is 50. Format should match the following pattern: ^[a-z0-9-]{1,50}$.

      • updated_at string(date-time)

        A NaiveDatetime-formatted timestamp describing when the resource was last updated with microsecond precision

      • updated_by integer(int64) | null

        The user ID associated with the last user to edit the tag when applicable.

    • total string

      Format should match the following pattern: ^(0|([1-9]+[0-9]*))(\.[0-9]{1,2})?$.

    • total_currency string

      ISO 4217 three-letter alphabetic currency code. Options are defined in the Currencies metadata endpoint

      Minimum length is 3, maximum length is 3. Format should match the following pattern: ^[A-Z]{3}$. Default value is USD.

    • tracking array[object]

      A list of tracking details for the packages in a shipment

      Hide tracking attributes Show tracking attributes object
      • carrier_name string

        The name of the carrier providing transport services for a specific package

      • label_format_urls object | null

        A map of shipping label format types to their respective download URLs. Returns null if no shipping label exists

        Hide label_format_urls attributes Show label_format_urls attributes object | null
        • pdf_4_x_6 string | null

          PDF 4x6 inch label - centered and scaled to full size with 0.5 inch margins on all sides

        • pdf_a4 string | null

          PDF A4 (8.3x11.7 inch) - centered and scaled to full size with 1 inch top/bottom and 1.25 inch left/right margins

        • pdf_a4_half_page string | null

          PDF A4 landscape (11.7x8.3 inch) - 4x6 label on left half with 1.15 inch top/bottom and 1.85 inch left/right margins

        • pdf_letter string | null

          PDF US Letter (8.5x11 inch) - centered and scaled to full size with 1 inch margins on all sides

        • pdf_letter_half_page string | null

          PDF US Letter landscape (11x8.5 inch) - 4x6 label on left half with 1.5 inch top/bottom and 1.25 inch left/right margins

        • png_4_x_6 string | null

          PNG 4x6 inch label - centered on the page and scaled to fill exactly 4x6 inches (no margins)

        • zpl_12dpmm string | null

          ZPL for 12 dots/mm (300 DPI) printers - 4x6 label centered on the media at native resolution

        • zpl_8dpmm string | null

          ZPL for 8 dots/mm (203 DPI) printers - 4x6 label centered on the media at native resolution

      • label_url string | null

        A URL at which parcel package shipping labels may be downloaded and printed

      • package_id integer(int64)

        The ID associated with the tracking detail's corresponding package

      • tracking_number string

        The carrier-providing tracking number for this package

      • url string

        A carrier-provided URL for fetching delivery events related to this package's transport

    • updated_at string(date-time)

      A NaiveDatetime-formatted timestamp describing when the resource was last updated with microsecond precision

    • url string

      The track URL for this shipment on the Arta web platform
  • 400 application/json

    Bad Request

    Hide headers attributes Show headers attributes
    • content-type string
    • x-arta-request-id string

      A unique identifier for the Arta API call

    Hide response attribute Show response attribute object
    • errors object
      Hide errors attribute Show errors attribute object
      • detail string
  • 403 application/json

    Forbidden

  • 404 application/json

    Not Found

    Hide headers attributes Show headers attributes
    • content-type string
    • x-arta-request-id string

      A unique identifier for the Arta API call

    Hide response attribute Show response attribute object
    • errors object
      Hide errors attribute Show errors attribute object
      • detail string
  • 422 application/json

    Unprocessible entity

    Hide response attribute Show response attribute object
    • errors object
      Hide errors attribute Show errors attribute object
      • detail string

        A human-readable explanation specific to this occurrence of the problem
POST /shipments 
curl \
 --request POST 'https://api.arta.io/shipments' \
 --header "Content-Type: application/json" \
 --header "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y" \
 --data '{"shipment":{"internal_reference":"Purchase Order: 2801","public_reference":"Order #1437","quote_id":"12345","shipping_notes":"New customer","tags":["vip"]}}'
Request examples 
# Headers
Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y

# Payload
{
  "shipment": {
    "internal_reference": "Purchase Order: 2801",
    "public_reference": "Order #1437",
    "quote_id": "12345",
    "shipping_notes": "New customer",
    "tags": [
      "vip"
    ]
  }
}
# Headers
Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y

# Payload
{
  "shipment": {
    "destination": {
      "access_restrictions": [
        "string"
      ],
      "address_line_1": "87 Richardson St",
      "address_line_2": "string",
      "address_line_3": "string",
      "city": "Brooklyn",
      "contacts": [
        {
          "email_address": "docs@arta.io",
          "name": "Contact Name",
          "phone_number": "646 828 7333"
        }
      ],
      "country": "US",
      "postal_code": "11211",
      "region": "NY",
      "title": "Gallery"
    },
    "internal_reference": "Purchase Order: 2801",
    "origin": {
      "access_restrictions": [
        "string"
      ],
      "address_line_1": "87 Richardson St",
      "address_line_2": "string",
      "address_line_3": "string",
      "city": "Brooklyn",
      "contacts": [
        {
          "email_address": "docs@arta.io",
          "name": "Contact Name",
          "phone_number": "646 828 7333"
        }
      ],
      "country": "US",
      "postal_code": "11211",
      "region": "NY",
      "title": "Gallery"
    },
    "packages": [
      {
        "depth": "3",
        "height": "32",
        "objects": [
          {
            "current_packing": [
              "no_packing"
            ],
            "customs": {
              "country_of_origin": "US",
              "hs_code": "123456",
              "medium": "oil on canvas",
              "temporary_admission": true
            },
            "depth": "3",
            "details": {
              "creation_date": "1980",
              "creator": "Bob Smithson",
              "is_cites": false,
              "is_fragile": false,
              "materials": [
                "canvas"
              ],
              "notes": "Artist signature in the lower left corner",
              "title": "Black Rectangle"
            },
            "height": "32",
            "images": [
              "http://example.com/image.jpg"
            ],
            "internal_reference": "Accession ID: 823",
            "public_reference": "Round Smithson work",
            "subtype": "painting_unframed",
            "unit_of_measurement": "in",
            "value": "2500.00",
            "value_currency": "USD",
            "weight": "3.0",
            "weight_unit": "lb",
            "width": "15"
          }
        ],
        "packing_materials": [
          "cardboard"
        ],
        "unit_of_measurement": "in",
        "weight": "3.0",
        "weight_unit": "lb",
        "width": "15"
      }
    ],
    "public_reference": "Order #1437",
    "shipping_notes": "New customer",
    "tags": [
      "vip"
    ],
    "tracking": [
      {
        "carrier": "ups",
        "tracking_number": "1ZXXXXXXXXXXXXXXXX",
        "url": "string"
      }
    ]
  }
}
Response examples (201) 
{
  "id": "6b12c76a-5217-4cd6-82d8-7aa5265ebaad",
  "url": "https://connect.shiparta.com/shipments/6b12c76a-5217-4cd6-82d8-7aa5265egood/5xTRnCvYkdMFdcFFMWUZaCmXz",
  "tags": [],
  "total": "4",
  "origin": {
    "city": "New York",
    "title": "Warehouse",
    "region": "NY",
    "country": "US",
    "contacts": [
      {
        "name": "Mary Quinn Sullivan",
        "phone_number": "(333) 333-3333",
        "email_address": "mary@example.com"
      }
    ],
    "postal_code": "10019",
    "address_line_1": "11 W 53rd St",
    "address_line_2": null,
    "address_line_3": null,
    "access_restrictions": []
  },
  "status": "pending",
  "packages": [
    {
      "id": 131,
      "eta": "05/09/2022",
      "depth": "6.0",
      "width": "14.0",
      "height": "14.5",
      "status": "pending",
      "weight": "3.5",
      "objects": [
        {
          "id": 620,
          "type": "art",
          "depth": "2",
          "value": "1500",
          "width": "10",
          "height": "10.5",
          "images": [],
          "weight": "3.5",
          "customs": {
            "medium": "oil on canvas",
            "hs_code": "123456",
            "country_of_origin": "US",
            "temporary_admission": true
          },
          "details": {
            "title": "All That Jazz",
            "creator": "Robert Irwin",
            "is_cites": false,
            "materials": [],
            "is_fragile": false,
            "creation_date": null
          },
          "subtype": "painting_unframed",
          "weight_unit": "lb",
          "value_currency": "USD",
          "current_packing": [],
          "public_reference": null,
          "internal_reference": null,
          "unit_of_measurement": "in"
        }
      ],
      "weight_unit": "lb",
      "handle_with_care": false,
      "packing_materials": [
        "strongbox"
      ],
      "is_sufficiently_packed": false
    }
  ],
  "schedule": {
    "pickup_end": null,
    "delivery_end": null,
    "pickup_start": null,
    "delivery_start": null,
    "pickup_window_modifier": "",
    "delivery_window_modifier": ""
  },
  "services": [
    {
      "name": "UPS Next Day Air",
      "type": "transport",
      "amount": "1",
      "subtype": "parcel",
      "metadata": {
        "reference_rate": {
          "provider": "fedex",
          "service_level": "fedex_standard_overnight"
        }
      },
      "is_required": true,
      "sub_subtype": "parcel",
      "is_requested": false,
      "amount_currency": "USD",
      "included_services": []
    },
    {
      "name": "Strongbox",
      "type": "packing",
      "amount": "1",
      "subtype": "packing_materials",
      "metadata": {},
      "is_required": true,
      "sub_subtype": "strongbox",
      "is_requested": false,
      "amount_currency": "USD",
      "included_services": []
    },
    {
      "name": "Collection",
      "type": "location",
      "amount": "1",
      "subtype": "collection",
      "metadata": {},
      "is_required": true,
      "sub_subtype": "collection",
      "is_requested": false,
      "amount_currency": "USD",
      "included_services": []
    },
    {
      "name": "Fuel Surcharge",
      "type": "taxes_duties_fees",
      "amount": "1",
      "subtype": "fees",
      "metadata": {},
      "is_required": true,
      "sub_subtype": "fuel_surcharge",
      "is_requested": false,
      "amount_currency": "USD",
      "included_services": []
    }
  ],
  "tracking": [],
  "emissions": "0.03",
  "shortcode": "MA-452144",
  "created_at": "2021-01-21T21:00:58.403150",
  "exceptions": [],
  "quote_type": "parcel",
  "updated_at": "2021-01-21T21:00:58.579870",
  "destination": {
    "city": "New York",
    "title": "Home",
    "region": "NY",
    "country": "US",
    "contacts": [
      {
        "name": "Alfred Barr",
        "phone_number": "(222) 222-2222",
        "email_address": "al@example.com"
      }
    ],
    "postal_code": "11249",
    "address_line_1": "87 Richardson St",
    "address_line_2": null,
    "address_line_3": null,
    "access_restrictions": []
  },
  "eei_form_url": null,
  "object_count": 1,
  "package_count": 1,
  "emissions_unit": "kg_co2e",
  "shipping_notes": null,
  "total_currency": "USD",
  "eei_form_status": null,
  "payment_process": "invoicing",
  "insurance_policy": null,
  "public_reference": null,
  "internal_reference": null
}
Response examples (400) 
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "errors": {
    "detail": "string"
  }
}
Response examples (404) 
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "errors": {
    "detail": "string"
  }
}
Response examples (422) 
{
  "errors": {
    "detail": "string"
  }
}