Arta Shipping Service Documentation

Backend
1

A comprehensive shipping service platform tailored for art, design, and luxury goods businesses, offering end-to-end logistics solutions.

Overview

Arta simplifies the complexities of shipping by providing:

  • White glove services - Premium handling for valuable items
  • Custom quotes - Tailored pricing for unique shipping needs
  • Real-time shipping rates - Dynamic pricing based on current conditions
  • Shipment tracking - End-to-end visibility of your shipments
  • Webhook event updates - Real-time notifications for status changes
  • Multiple service tiers - Premium, Select, Parcel, and Self Ship options

Getting Started

Prerequisites

  1. Contact Arta to obtain API credentials
  2. Choose your preferred payment model (Prepayment or Terms)

Base URL

https://api.arta.io

Authentication

All API requests require authentication using your API key in the header:

Authorization: ARTA_APIKey YOUR_API_KEY

Payment Models

Prepayment Model

Best for: Quick integration launches, post-checkout booking flows

  • Clients or customers pay Arta directly for shipping costs
  • API provides payment URL in response
  • Customers complete payment to confirm booking
  • Arta handles all payment complexity

Terms Model

Best for: E-commerce platforms, internal logistics systems

Benefits:

  • Control shipping pricing on your platform
  • Add markup for revenue generation
  • Discount or subsidize shipping for promotions
  • Split costs between sellers and buyers

API Workflow

[Start]
   |
   v
[Create Quote Request]  (POST /requests)
   |                           +-----------------+
   v                           |                 |
[Quote Request State]-------->| Quoted          | Disqualified |
   |                           |                 |              |
   |                           |                 |              |
   |                           v                 v              |
   |                      [Proceed to Shipment] [Create Custom Quote] (POST /custom_quotes)
   |                                            |                           |
   |                                            v                           |
   |                                      [Arta Manual Review]              |
   |                                            |                           |
   |                                            v                           |
   |                                      [Add Quotes]                      |
   |                                            |                           |
   |                                            v                           |
   |                                      [Quoted State]                    |
   |                                            |                           |
   v                                            v                           |
[Create Shipment] (POST /shipments) <--------------------------------------+
   |
   v
[End]

The typical Arta API workflow follows these steps:

1. Fetch Metadata → 2. Create Quote Request → 3. Select Quote → 4. Create Shipment → 5. Track Shipment

Step-by-Step Process

  1. Fetch Metadata - Get supported currencies, object types, and service tiers
  2. Create Quote Request - Submit shipment details to get pricing options
  3. Review Quotes - Evaluate returned quotes by service tier (Premium, Select, Parcel)
  4. Create Shipment - Book a shipment using a selected quote ID
  5. Track & Monitor - Use webhooks and tracking URLs for real-time updates

Metadata Endpoints

Before creating quotes, fetch the supported options from these endpoints:

Supported Currencies

The list of currencies supported by Arta’s API.

GET /metadata/currencies

Response:

[
  {
    "id": "USD",
    "name": "US Dollar", 
    "symbol": "$"
  },
  {
    "id": "EUR",
    "name": "Euro",
    "symbol": "€"
  }
]

Insurance Types

The list of insurance types supported by Arta’s API.

GET /metadata/insurances

Response:

[
  {
    "description": "Arta full risk coverage transit insurance.",
    "id": "arta_transit_insurance",
    "name": "Arta Full Risk"
  }
]

Object Types

The list of object types supported by Arta’s API.

GET /metadata/objects

Response:

[
  {
    "description": "Works of art various media including paintings, sculpture, or works on paper.",
    "id": "art",
    "name": "Works of art",
    "subtypes": [
      {
        "description": "A painting that is framed behind a glass face.",
        "id": "painting_framed_glass", 
        "name": "Painting (framed with glass)"
      }
    ]
  }
]

Quote Types (Service Tiers)

GET /metadata/quotes

Available Service Tiers:

  • Premium - Specialized, climate-controlled transport with trained technicians (wall-to-wall white glove)
  • Select - Mid-tier with partial white glove services (room-of-choice delivery, unpacking)
  • Parcel - Standard small-parcel shipping for packaged items
  • Self Ship - DIY option with Arta documentation and tracking

Quote Management

Creating Quote Requests

Generate shipping quotes by submitting your shipment details:

POST /requests

Required Headers:

Authorization: ARTA_APIKey YOUR_API_KEY
Content-Type: application/json
Arta-Quote-Timeout: 6000  # Optional timeout in milliseconds

Minimum Required Fields:

  • objects - Items being shipped (with dimensions, weight, value)
  • origin - Pickup location details
  • destination - Delivery location details

Sample Request:

{
  "currency": "USD",
  "origin": {
    "country": "US",
    "postal_code": "10001",
    "address_line_1": "123 Art Street",
    "city": "New York",
    "region": "NY",
    "contacts": [
      {
        "name": "Gallery Manager",
        "email_address": "manager@gallery.com",
        "phone_number": "(212) 555-0123"
      }
    ]
  },
  "destination": {
    "country": "US", 
    "postal_code": "94103",
    "address_line_1": "456 Museum Ave",
    "city": "San Francisco",
    "region": "CA",
    "contacts": [
      {
        "name": "Curator",
        "email_address": "curator@museum.com",
        "phone_number": "(415) 555-0456"
      }
    ]
  },
  "objects": [
    {
      "title": "Framed Artwork",
      "subtype": "painting_framed_glass",
      "depth": "5",
      "height": "20", 
      "width": "30",
      "unit_of_measurement": "in",
      "value": "1500.00",
      "value_currency": "USD",
      "weight": "10",
      "weight_unit": "lb"
    }
  ]
}

Quote Request Lifecycle

Status Description
quoted Successfully generated shipping quotes - ready to book
disqualified No quotes available - may be eligible for custom quote
in_progress Under manual review for custom quote
closed Quote has been booked into a shipment
expired Request expired after 30 days
cancelled Request was cancelled

Understanding Quote Responses

In the response you will get list of qoutes if the request is in quoted state

A successful quote response includes:

Quote Structure:

{
  "id": "9d8892bc-f4c6-4b45-88e2-0ccd28eb73cc",
  "tags": [],
  "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": []
  },
  "quotes": [
    {
      "id": 61,
      "total": "2",
      "status": "published",
      "quote_type": "premium",
      "total_currency": "USD",
      "included_services": [
        {
          "name": "Specialized Shuttle",
          "type": "transport",
          "amount": "1",
          "subtype": "specialized",
          "metadata": {
            "reference_rate": {
              "provider": "arta",
              "service_level": "arta"
            }
          },
          "is_required": true,
          "sub_subtype": "specialized_shuttle",
          "is_requested": false,
          "amount_currency": "USD",
          "included_services": []
        },
        {
          "name": "Shadowbox",
          "type": "packing",
          "amount": "1",
          "subtype": "packing_materials",
          "metadata": {},
          "is_required": true,
          "sub_subtype": "shadow_box",
          "is_requested": false,
          "amount_currency": "USD",
          "included_services": []
        }
      ],
      "optional_services": [
        {
          "name": "Debris Disposal",
          "type": "handling",
          "amount": "1",
          "subtype": "debris_disposal",
          "sub_subtype": "debris_disposal",
          "amount_currency": "USD",
          "included_services": [
            {
              "name": "Soft Packed Disposal",
              "type": "handling",
              "subtype": "debris_disposal",
              "sub_subtype": "soft_packed_disposal"
            }
          ]
        },
        {
          "name": "Assembly",
          "type": "handling",
          "amount": "1",
          "subtype": "installation",
          "sub_subtype": "assembly",
          "amount_currency": "USD",
          "included_services": []
        },
        {
          "name": "Placement",
          "type": "handling",
          "amount": "1",
          "subtype": "installation",
          "sub_subtype": "placement",
          "amount_currency": "USD",
          "included_services": []
        },
        {
          "name": "Installation",
          "type": "handling",
          "amount": "1",
          "subtype": "installation",
          "sub_subtype": "installation",
          "amount_currency": "USD",
          "included_services": []
        },
        {
          "name": "Condition Check (destination)",
          "type": "handling",
          "amount": "1",
          "subtype": "condition",
          "sub_subtype": "destination_condition_check",
          "amount_currency": "USD",
          "included_services": []
        },
        {
          "name": "Condition Check (origin)",
          "type": "handling",
          "amount": "1",
          "subtype": "condition",
          "sub_subtype": "origin_condition_check",
          "amount_currency": "USD",
          "included_services": []
        },
        {
          "name": "Condition Report (destination)",
          "type": "handling",
          "amount": "1",
          "subtype": "condition",
          "sub_subtype": "destination_full_condition_report",
          "amount_currency": "USD",
          "included_services": []
        },
        {
          "name": "Condition Report (origin)",
          "type": "handling",
          "amount": "1",
          "subtype": "condition",
          "sub_subtype": "origin_full_condition_report",
          "amount_currency": "USD",
          "included_services": []
        },
        {
          "name": "Unpacking (destination)",
          "type": "handling",
          "amount": "1",
          "subtype": "unpacking",
          "sub_subtype": "destination_unpacking",
          "amount_currency": "USD",
          "included_services": [
            {
              "name": "Unpacking Soft Materials (destination)",
              "type": "handling",
              "subtype": "unpacking",
              "sub_subtype": "destination_unpacking_soft"
            }
          ]
        }
      ],
      "included_insurance_policy": null
    },
    {
      "id": 62,
      "total": "4",
      "status": "published",
      "quote_type": "select",
      "total_currency": "USD",
      "included_services": [
        {
          "name": "Debris Disposal",
          "type": "handling",
          "amount": "1",
          "subtype": "debris_disposal",
          "metadata": {},
          "is_required": true,
          "sub_subtype": "debris_disposal",
          "is_requested": false,
          "amount_currency": "USD",
          "included_services": [
            {
              "name": "Soft Packed Disposal",
              "type": "handling",
              "subtype": "debris_disposal",
              "sub_subtype": "soft_packed_disposal"
            }
          ]
        },
        {
          "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": []
        },
        {
          "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": "Consolidated Trucking",
          "type": "transport",
          "amount": "1",
          "subtype": "consolidated",
          "metadata": {
            "reference_rate": {
              "provider": "arta",
              "service_level": null
            }
          },
          "is_required": true,
          "sub_subtype": "road_groupage",
          "is_requested": false,
          "amount_currency": "USD",
          "included_services": []
        }
      ],
      "optional_services": [
        {
          "name": "Unpacking (destination)",
          "type": "handling",
          "amount": "1",
          "subtype": "unpacking",
          "sub_subtype": "destination_unpacking",
          "amount_currency": "USD",
          "included_services": [
            {
              "name": "Unpacking Soft Materials (destination)",
              "type": "handling",
              "subtype": "unpacking",
              "sub_subtype": "destination_unpacking_soft"
            }
          ]
        },
        {
          "name": "Condition Check (destination)",
          "type": "handling",
          "amount": "1",
          "subtype": "condition",
          "sub_subtype": "destination_condition_check",
          "amount_currency": "USD",
          "included_services": []
        },
        {
          "name": "Condition Check (origin)",
          "type": "handling",
          "amount": "1",
          "subtype": "condition",
          "sub_subtype": "origin_condition_check",
          "amount_currency": "USD",
          "included_services": []
        }
      ],
      "included_insurance_policy": null
    },
    {
      "id": 63,
      "total": "4",
      "status": "published",
      "quote_type": "parcel",
      "total_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": []
        },
        {
          "name": "Collection",
          "type": "location",
          "amount": "1",
          "subtype": "collection",
          "metadata": {},
          "is_required": true,
          "sub_subtype": "collection",
          "is_requested": false,
          "amount_currency": "USD",
          "included_services": []
        },
        {
          "name": "Ply Box",
          "type": "packing",
          "amount": "1",
          "subtype": "packing_materials",
          "metadata": {},
          "is_required": true,
          "sub_subtype": "ply_box",
          "is_requested": false,
          "amount_currency": "USD",
          "included_services": []
        },
        {
          "name": "UPS Ground",
          "type": "transport",
          "amount": "1",
          "subtype": "parcel",
          "metadata": {
            "reference_rate": {
              "provider": "fedex",
              "service_level": "fedex_ground"
            }
          },
          "is_required": true,
          "sub_subtype": "parcel",
          "is_requested": false,
          "amount_currency": "USD",
          "included_services": []
        }
      ],
      "optional_services": [],
      "included_insurance_policy": null
    },
    {
      "id": 64,
      "total": "4",
      "status": "published",
      "quote_type": "parcel",
      "total_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": []
        },
        {
          "name": "Collection",
          "type": "location",
          "amount": "1",
          "subtype": "collection",
          "metadata": {},
          "is_required": true,
          "sub_subtype": "collection",
          "is_requested": false,
          "amount_currency": "USD",
          "included_services": []
        },
        {
          "name": "Ply Box",
          "type": "packing",
          "amount": "1",
          "subtype": "packing_materials",
          "metadata": {},
          "is_required": true,
          "sub_subtype": "ply_box",
          "is_requested": false,
          "amount_currency": "USD",
          "included_services": []
        },
        {
          "name": "UPS Second Day Air",
          "type": "transport",
          "amount": "1",
          "subtype": "parcel",
          "metadata": {
            "reference_rate": {
              "provider": "fedex",
              "service_level": "fedex_2_day"
            }
          },
          "is_required": true,
          "sub_subtype": "parcel",
          "is_requested": false,
          "amount_currency": "USD",
          "included_services": []
        }
      ],
      "optional_services": [],
      "included_insurance_policy": null
    },
    {
      "id": 65,
      "total": "4",
      "status": "published",
      "quote_type": "parcel",
      "total_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": []
        },
        {
          "name": "Collection",
          "type": "location",
          "amount": "1",
          "subtype": "collection",
          "metadata": {},
          "is_required": true,
          "sub_subtype": "collection",
          "is_requested": false,
          "amount_currency": "USD",
          "included_services": []
        },
        {
          "name": "Ply Box",
          "type": "packing",
          "amount": "1",
          "subtype": "packing_materials",
          "metadata": {},
          "is_required": true,
          "sub_subtype": "ply_box",
          "is_requested": false,
          "amount_currency": "USD",
          "included_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": []
        }
      ],
      "optional_services": [],
      "included_insurance_policy": null
    }
  ],
  "status": "quoted",
  "objects": [
    {
      "id": 1644,
      "type": "art",
      "depth": "2",
      "value": "15000",
      "width": "10",
      "height": "10.5",
      "images": [],
      "weight": "3.5",
      "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"
    }
  ],
  "bookable": {
    "ready": true,
    "missing": []
  },
  "currency": "USD",
  "insurance": null,
  "shortcode": "DEMO-R29NAW",
  "created_at": "2021-01-21T17:22:08.818747",
  "updated_at": "2021-01-21T17:22:10.129653",
  "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": []
  },
  "quote_types": [
    "premium",
    "select",
    "parcel"
  ],
  "object_count": 1,
  "log_request_id": "FpL53jSpPbCUXRAAKPRS",
  "shipping_notes": null,
  "payment_process": "invoicing",
  "public_reference": null,
  "disqualifications": [],
  "hosted_session_id": 723,
  "internal_reference": null,
  "additional_services": [],
  "preferred_quote_types": [],
  "preferred_parcel_transport_services": []
}

Custom Quotes

For complex shipments requiring manual review:

PATCH /requests/{request_id}/custom

This converts a disqualified request to manual review for custom pricing.

Shipment Creation

Once you have quotes, create a shipment by selecting a quote ID:

POST /shipments

Headers:

Authorization: ARTA_APIKey YOUR_API_KEY
Content-Type: application/json

Sample Payload:

{
  "shipment": {
    "quote_id": 62,
    "internal_reference": "PO-2801",
    "public_reference": "Order #1437", 
    "shipping_notes": "New customer – deliver after 5 PM",
    "tags": ["vip", "fragile"]
  }
}

Response includes:

  • Unique shipment ID
  • Tracking URL for customer use
  • Package details and current status
  • Service breakdown and costs
  • Estimated delivery schedule

Sample Response:

{
  "id": "6b12c76a-5217-4cd6-82d8-7aa5265ebaad",
  "url": "https://connect.shiparta.com/shipments/...",
  "status": "pending",
  "total": "250.00",
  "total_currency": "USD",
  "shortcode": "MA-452144",
  "packages": [
    {
      "id": 131,
      "eta": "05/09/2022",
      "status": "pending",
      "packing_materials": ["strongbox"]
    }
  ]
}

Webhooks

Webhooks provide real-time notifications for shipment and quote request events.

Webhook Event Structure

{
  "data": { /* Complete request or shipment object */ },
  "object": "request" | "shipment",
  "type": "event.type.name"
}

Event Types

Request Events:

  • request.created - Quote request has been created
  • request.status.updated - Quote request status changed
  • request.updated - Request details have changed

Shipment Events:

  • shipment.created - Shipment has been booked
  • shipment.status.updated - Shipment status changed
  • shipment.tracking.updated - Tracking information updated
  • shipment.schedule.updated - Pickup or delivery schedule updated
  • shipment.exceptions.updated - Shipment exception occurred

Webhook Security

Verify webhook authenticity using the Arta-Signature header:

Arta-Signature: t=1623359782,s=BASE64_HMAC_SIGNATURE

Verification Steps:

  1. Extract timestamp (t) and signature (s) from header
  2. Construct signed payload: "${timestamp}.${rawRequestBody}"
  3. Generate HMAC-SHA256 using your webhook secret
  4. Compare computed signature with provided signature
  5. Validate timestamp is within acceptable range (±5 minutes)

Examples

Complete Workflow Example

1. Get Metadata

# Get supported object types
curl -X GET 'https://api.arta.io/metadata/objects' \
  -H "Authorization: ARTA_APIKey YOUR_API_KEY"

# Get supported currencies  
curl -X GET 'https://api.arta.io/metadata/currencies' \
  -H "Authorization: ARTA_APIKey YOUR_API_KEY"

2. Create Quote Request

curl -X POST 'https://api.arta.io/requests' \
  -H "Authorization: ARTA_APIKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD",
    "origin": {
      "country": "US", 
      "postal_code": "10001",
      "address_line_1": "123 Gallery St",
      "city": "New York",
      "region": "NY"
    },
    "destination": {
      "country": "US", 
      "postal_code": "94103",
      "address_line_1": "456 Museum Ave", 
      "city": "San Francisco",
      "region": "CA"
    },
    "objects": [{
      "title": "Abstract Painting",
      "subtype": "painting_unframed",
      "height": "24", 
      "width": "18", 
      "depth": "2",
      "unit_of_measurement": "in",
      "value": "5000.00", 
      "value_currency": "USD",
      "weight": "5", 
      "weight_unit": "lb"
    }]
  }'

3. Create Shipment from Quote

curl -X POST 'https://api.arta.io/shipments' \
  -H "Authorization: ARTA_APIKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shipment": {
      "quote_id": 62,
      "internal_reference": "ORDER-123",
      "shipping_notes": "Handle with extreme care - valuable artwork"
    }
  }'

Support & Resources

3 Likes