Artashippinginc

Artashippinginc Shipment Exceptions API

The shipment_exceptions API from Artashippinginc — 2 operation(s) for shipment_exceptions.

GitHub OpenAPI
Business capability
Logistics Operations Management BC-520.50

Operations 4

GET /shipment_exceptions List Shipment Exceptions #
POST /shipment_exceptions Create Shipment Exception #
GET /shipment_exceptions/{shipment_exception_id} Get a Shipment Exception #
PATCH /shipment_exceptions/{shipment_exception_id} Update a Shipment Exception #

Specifications

⚙
OpenAPI
https://artifacts.apis.io/artashippinginc/openapi/artashippinginc-shipment-exceptions-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/artashippinginc/json-schema/artashippinginc-shipment-exception-schema.json
📊
JSONSchema
https://artifacts.apis.io/artashippinginc/json-schema/artashippinginc-shipment-exception-create-schema.json
📊
JSONSchema
https://artifacts.apis.io/artashippinginc/json-schema/artashippinginc-shipment-exception-update-schema.json

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/artashippinginc:artashippinginc-shipment-exceptions-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

artashippinginc-shipment-exceptions-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  contact:
    email: hello@arta.io
    name: Arta
    url: https://manual.arta.io/
  description: The Arta Public API provides quote generation, transport booking, and tracking capabilities. Additionally the API enables Arta partner organizations to configure email and webhook notifications for their accounts.
  termsOfService: https://www.arta.io/legal/terms
  title: Arta Public Shipment Exceptions API
  version: '2021-01-01'
servers:
- url: https://api.arta.io
  variables: {}
security: []
tags:
- name: shipment_exceptions
paths:
  /shipment_exceptions:
    get:
      callbacks: {}
      deprecated: false
      description: Retrieve a paginated collection of Shipment Exceptions belonging to your Organization
      operationId: shipmentExceptions/list
      parameters:
      - description: Authorize your API calls with an Arta API token
        example: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y
        in: header
        name: Authorization
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: Page number of the results to fetch.
        in: query
        name: page
        schema:
          default: 1
          type: integer
          x-struct: null
          x-validate: null
      - description: Results per page (max 50)
        in: query
        name: page_size
        schema:
          default: 20
          type: integer
          x-struct: null
          x-validate: null
      - description: An optional sort order for the returned collection.
        in: query
        name: sort
        required: false
        schema:
          enum:
          - created_at_asc
          - created_at_desc
          - updated_at_asc
          - updated_at_desc
          type: string
          x-struct: null
          x-validate: null
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  items:
                    items:
                      $ref: '#/components/schemas/ShipmentException'
                    type: array
                    x-struct: null
                    x-validate: null
                  metadata:
                    properties:
                      page:
                        example: 1
                        format: int64
                        readOnly: true
                        type: integer
                        x-struct: null
                        x-validate: null
                      page_size:
                        example: 20
                        format: int64
                        readOnly: true
                        type: integer
                        x-struct: null
                        x-validate: null
                      total_count:
                        example: 1
                        format: int64
                        readOnly: true
                        type: integer
                        x-struct: null
                        x-validate: null
                    type: object
                    x-struct: null
                    x-validate: null
                type: object
                x-struct: null
                x-validate: null
          description: A paginated collection of Shipment Exceptions
          headers:
            content-type:
              example: application/json
              schema:
                type: string
                x-struct: null
                x-validate: null
              style: simple
            x-arta-request-id:
              description: A unique identifier for the Arta API call
              example: FkBjuxbwLLTx4RoAARkx
              schema:
                type: string
                x-struct: null
                x-validate: null
              style: simple
      summary: List Shipment Exceptions
      tags:
      - shipment_exceptions
    post:
      callbacks: {}
      deprecated: false
      description: 'Create a Shipment Exception for a Shipment


        * Clients can create shipment exceptions of a single type currently:`requested_hold_to_collect`


        * A shipment must have a `pending` or `confirmed` status to create a `requested_hold_to_collect` shipment exception.


        * `hold_until` date cannot be greater than 30 days from the associated shipment''s `created_at` timestamp.'
      operationId: shipmentExceptions/create
      parameters:
      - description: Authorize your API calls with an Arta API token
        example: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y
        in: header
        name: Authorization
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentExceptionCreate'
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentException'
          description: Successful response
          headers:
            content-type:
              example: application/json
              schema:
                type: string
                x-struct: null
                x-validate: null
              style: simple
            x-arta-request-id:
              description: A unique identifier for the Arta API call
              example: FkBjuxbwLLTx4RoAARkx
              schema:
                type: string
                x-struct: null
                x-validate: null
              style: simple
      summary: Create Shipment Exception
      tags:
      - shipment_exceptions
  /shipment_exceptions/{shipment_exception_id}:
    get:
      callbacks: {}
      deprecated: false
      description: Retrieve an existing Shipment Exception
      operationId: shipmentExceptions/get
      parameters:
      - description: Authorize your API calls with an Arta API token
        example: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y
        in: header
        name: Authorization
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: shipment_exception_id parameter
        in: path
        name: shipment_exception_id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentException'
          description: Successful Shipment Exception response
          headers:
            content-type:
              example: application/json
              schema:
                type: string
                x-struct: null
                x-validate: null
              style: simple
            x-arta-request-id:
              description: A unique identifier for the Arta API call
              example: FkBjuxbwLLTx4RoAARkx
              schema:
                type: string
                x-struct: null
                x-validate: null
              style: simple
        '404':
          content:
            application/json:
              schema:
                properties:
                  errors:
                    properties:
                      detail:
                        example: string
                        type: string
                        x-struct: null
                        x-validate: null
                    type: object
                    x-struct: null
                    x-validate: null
                title: NotFound
                type: object
                x-struct: null
                x-validate: null
          description: Not Found
          headers:
            content-type:
              example: application/json
              schema:
                type: string
                x-struct: null
                x-validate: null
              style: simple
            x-arta-request-id:
              description: A unique identifier for the Arta API call
              example: FkBjuxbwLLTx4RoAARkx
              schema:
                type: string
                x-struct: null
                x-validate: null
              style: simple
      summary: Get a Shipment Exception
      tags:
      - shipment_exceptions
    patch:
      callbacks: {}
      deprecated: false
      description: Update an existing Shipment Exception
      operationId: shipmentExceptions/update
      parameters:
      - description: Authorize your API calls with an Arta API token
        example: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y
        in: header
        name: Authorization
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: shipment_exception_id parameter
        in: path
        name: shipment_exception_id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentExceptionUpdate'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentException'
          description: Successful Shipment Exception response
          headers:
            content-type:
              example: application/json
              schema:
                type: string
                x-struct: null
                x-validate: null
              style: simple
            x-arta-request-id:
              description: A unique identifier for the Arta API call
              example: FkBjuxbwLLTx4RoAARkx
              schema:
                type: string
                x-struct: null
                x-validate: null
              style: simple
        '404':
          content:
            application/json:
              schema:
                properties:
                  errors:
                    properties:
                      detail:
                        example: string
                        type: string
                        x-struct: null
                        x-validate: null
                    type: object
                    x-struct: null
                    x-validate: null
                title: NotFound
                type: object
                x-struct: null
                x-validate: null
          description: Not Found
          headers:
            content-type:
              example: application/json
              schema:
                type: string
                x-struct: null
                x-validate: null
              style: simple
            x-arta-request-id:
              description: A unique identifier for the Arta API call
              example: FkBjuxbwLLTx4RoAARkx
              schema:
                type: string
                x-struct: null
                x-validate: null
              style: simple
      summary: Update a Shipment Exception
      tags:
      - shipment_exceptions
components:
  schemas:
    ShipmentExceptionUpdate:
      example:
        shipment_exception:
          hold_until: '2023-08-15'
          status: resolved
      properties:
        shipment_exception:
          properties:
            hold_until:
              description: Optionally provide a date to hold collection for the shipment. Values should be in the `YYYY-MM-DD` format. Hold until dates must be fewer than 30 days from the shipment's `created_at` datetime.
              type: string
              x-struct: null
              x-validate: null
            status:
              description: The current status for this exception
              example: resolved
              type: string
              x-struct: null
              x-validate: null
          type: object
          x-struct: null
          x-validate: null
      required:
      - shipment_exception
      title: ShipmentExceptionUpdate
      type: object
      x-struct: Elixir.DocsWeb.Schemas.RequestBody.ShipmentExceptionUpdate
      x-validate: null
    ShipmentExceptionCreate:
      example:
        shipment_exception:
          hold_until: '2023-08-15'
          shipment_id: 5baff45a-281d-416e-9310-a4a7c637952e
          type: requested_hold_to_collect
      properties:
        shipment_exception:
          properties:
            hold_until:
              description: Optionally provide a date to hold collection for the shipment. Values should be in the `YYYY-MM-DD` format. Hold until dates must be fewer than 30 days from the shipment's `created_at` datetime.
              type: string
              x-struct: null
              x-validate: null
            shipment_id:
              description: The ID for the shipment associated to the shipment exception
              type: string
              x-struct: null
              x-validate: null
            type:
              description: The type ID for this resource. Options are defined in the Shipment Exception Types metadata endpoint. Currently, the only accepted type for client-created shipment exceptions is `requested_hold_to_collect`.
              enum:
              - requested_hold_to_collect
              example: requested_hold_to_collect
              type: string
              x-struct: null
              x-validate: null
          required:
          - type
          - shipment_id
          type: object
          x-struct: null
          x-validate: null
      required:
      - shipment_exception
      title: ShipmentExceptionCreate
      type: object
      x-struct: Elixir.DocsWeb.Schemas.RequestBody.ShipmentExceptionCreate
      x-validate: null
    ShipmentException:
      example:
        created_at: '2023-05-26T19:33:19.693833'
        exception_type_label: null
        hold_until: null
        id: d686ad3b-33fd-454c-a7aa-94b1ecbc539f
        package_id: 4366794
        resolution: null
        shipment_id: a5cbb58c-43ab-4658-9999-98a33b0070d5
        source: api
        status: new
        type: held_at_customs
        updated_at: '2023-05-26T19:33:19.693833'
      properties:
        created_at:
          description: A NaiveDatetime-formatted timestamp describing when the exception was created with microsecond precision
          example: '2024-08-13T22:44:39.593704'
          format: date-time
          type: string
          x-struct: null
          x-validate: null
        exception_type_label:
          description: An additional label providing context about the exception type (optional)
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        hold_until:
          description: The date the shipment will be held until
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        id:
          description: The id of the exception in UUID format
          format: uuid
          type: string
          x-struct: null
          x-validate: null
        package_id:
          description: The package associated with this exception (optional)
          example: '12345'
          format: int64
          nullable: true
          type: integer
          x-struct: null
          x-validate: null
        resolution:
          description: A brief description of the method by which this exception was resolved
          example: Balance Cleared
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        shipment_id:
          description: The id of the shipment associated with this exception
          format: uuid
          type: string
          x-struct: null
          x-validate: null
        source:
          description: The source of the exception
          example: arta_team
          type: string
          x-struct: null
          x-validate: null
        status:
          description: The current status for this exception
          enum:
          - new
          - in_progress
          - resolved
          example: resolved
          type: string
          x-struct: null
          x-validate: null
        type:
          description: The type of exception
          example: prepayment_required
          type: string
          x-struct: null
          x-validate: null
        updated_at:
          description: A NaiveDatetime-formatted timestamp describing when the exception was last updated with microsecond precision
          example: '2024-08-13T22:44:39.593704'
          format: date-time
          type: string
          x-struct: null
          x-validate: null
      title: ShipmentException
      type: object
      x-struct: Elixir.DocsWeb.Schemas.Response.ShipmentException
      x-validate: null
x-topics:
- content: 'The Arta API accepts server-to-server communications authenticated by API keys. Your API keys are self-managed and unique to your organization.


    Using your API key to authenticate an API call is straightforward. Simply include your API Key token in the Authorization header of every call made to the system. This is the only place that it is accepted.'
  example: "```shell\n\n$ curl \\ \n\n -X GET https://api.arta.io/shipments \\ \n\n -H \"Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y\""
  title: Authentication
- content: "Arta imposes rate limits on API requests to maintain system stability and ensure fair usage. If you exceed these limits, the API will return a `429 Too Many Requests` error. Below are the rate limits for both Live and Test modes.\n\n**Live Mode:**\n\n*\tConcurrent requests: 15 API calls at the same time (any type)\n* Instant quote requests: 20 calls per minute\n* Overall requests: 1000 API calls per minute (any type)\n\n**Test Mode:**\n\n* Concurrent requests: 10 API calls at the same time (any type)\n* Instant quote requests: 10 calls per minute\n* Overall requests: 500 API calls per minute (any type)\n\nWhen a rate limit is exceeded, we recommend implementing retry logic with exponential backoff to handle 429 errors effectively."
  title: Rate Limits
- content: 'The Arta API supports flexible search functionality across multiple resources, including Shipments, Requests, Hosted Sessions, Tags, and others. Using the search query parameter, you can construct structured queries to filter results based on specific criteria.


    Key features of the search functionality include:


    * Support for negation, wildcards, numeric filters, and date comparisons.

    * Each search query consists of one or more clauses, where each clause contains a `field`, an operator, and a `value`.

    * Clauses operating on the same field are combined using OR logic, while clauses across different fields are combined using AND logic.


    * Use quotation marks to keep multi-word search terms together.


    This allows for powerful and precise filtering to retrieve the exact data you need from the API.


    **Syntax and operators**


    The following table lists the operators and syntax that you can use to construct a search query clause.


    | Operator     | Usage                          | Description                                                                 | Examples                                                            |

    |------------|--------------------------------|-----------------------------------------------------------------------------|---------------------------------------------------------------------|

    | `:`        | `field:value`                  | Exact match operator (case insensitive)                                     | `status:pending` returns records where the status is `pending` |

    | `*`        | `value*`                       | Use an asterisk (wildcard operator) at the end of a term to match fields that start with the fragment                                    | `art*` returns records that match "arta" and "artist" but not "smart" |

    | `*`        | `*value`                       | Use an asterisk at the start of a term to match fields that end with the fragment                                    | `*art` returns "smart" but not "martian" |

    | `-`        | `-field:value`                 | Returns records that don’t match the clause                                 | `-status:pending` returns records that do not have a status of pending                 |

    | `>, <, =`  | `field:<value`, `field:>value`, `field:>=value`, `field:<=value` | Greater than/less than operators              | `created-at:<=2021-01-01` returns records from the beginning of time through January 1, 2021   |

    | `..`       | `field:value1..value2`                 | Filters for values within a given range where the first number is the lowest value and the second is the highest                                 | `created-at:2021-05-01..2021-05-15` returns records where the `created_at` field is between May 1, 2021 and May 15, 2021                 |




    **Hosted Session search fields**


    | Field | Type |

    |------------|--------------|

    | `created-at` | date |

    | `destination-address-line-1` | string |

    | `destination-city` | string |

    | `destination-contacts-emails` | string |

    | `destination-contacts-names` | string |

    | `destination-contacts-phone-numbers` | string |

    | `destination-country` | string |

    | `destination-postal-code` | string |

    | `destination-region` | string |

    | `insurance` | string |

    | `internal-reference` | string |

    | `object-creators` | string |

    | `object-descriptions` | string |

    | `object-internal-references` | string |

    | `object-public-references` | string |

    | `object-titles` | string |

    | `origin-address-line-1` | string |

    | `origin-city` | string |

    | `origin-contacts-emails` | string |

    | `origin-contacts-names` | string |

    | `origin-contacts-phone-numbers` | string |

    | `origin-country` | string |

    | `origin-postal-code` | string |

    | `origin-region` | string |

    | `public-reference` | string |

    | `quote-type` | string |

    | `shipping-notes` | string |

    | `shortcode` | string |

    | `status` | string |

    | `type` | string |

    | `tags` | string |


    **Request search fields**


    | Field | Type |

    |------------|--------------|

    | `bookable` | string |

    | `created-at` | date |

    | `destination-address-line-1` | string |

    | `destination-city` | string |

    | `destination-contacts-emails` | string |

    | `destination-contacts-names` | string |

    | `destination-contacts-phone-numbers` | string |

    | `destination-country` | string |

    | `destination-postal-code` | string |

    | `destination-region` | string |

    | `hosted-session` | string |

    | `internal-reference` | string |

    | `object-creators` | string |

    | `object-descriptions` | string |

    | `object-internal-references` | string |

    | `object-public-references` | string |

    | `object-titles` | string |

    | `origin-address-line-1` | string |

    | `origin-city` | string |

    | `origin-contacts-emails` | string |

    | `origin-contacts-names` | string |

    | `origin-contacts-phone-numbers` | string |

    | `origin-country` | string |

    | `origin-postal-code` | string |

    | `origin-region` | string |

    | `public-reference` | string |

    | `quote-type` | string |

    | `shipping-notes` | string |

    | `shortcode` | string |

    | `status` | string |

    | `tags` | string |


    **Shipment search fields**


    | Field | Type |

    |------------|--------------|

    | `created-at` | date |

    | `destination-address-line-1` | string |

    | `destination-city` | string |

    | `destination-contacts-emails` | string |

    | `destination-contacts-names` | string |

    | `destination-contacts-phone-numbers` | string |

    | `destination-country` | string |

    | `destination-postal-code` | string |

    | `destination-region` | string |

    | `eei-form-status` | string |

    | `hosted-session` | string |

    | `internal-reference` | string |

    | `object-creators` | string |

    | `object-descriptions` | string |

    | `object-internal-references` | string |

    | `object-public-references` | string |

    | `object-titles` | string |

    | `origin-address-line-1` | string |

    | `origin-city` | string |

    | `origin-contacts-emails` | string |

    | `origin-contacts-names` | string |

    | `origin-contacts-phone-numbers` | string |

    | `origin-country` | string |

    | `origin-postal-code` | string |

    | `origin-region` | string |

    | `public-reference` | string |

    | `quote-type` | string |

    | `request-shortcode` | string |

    | `shipping-notes` | string |

    | `shortcode` | string |

    | `status` | string |

    | `tags` | string |

    | `total` | numeric |

    | `total-currency` | string |

    | `tracking-numbers` | string |


    **Tag search fields**


    | Field | Type |

    |------------|--------------|

    | `color` | string |

    | `description` | string |

    | `is_active` | string |

    | `name` | string |


    '
  title: Search