Shipment API

International Shipping

Endpoint

Global default server with tenant, region, environment, and version variables

https://...sh.example.com/

Download schema

Operations for managing customs documentation, duties, and international shipment processes.

Update customs documentation

PUT

https://acme-logistics.us-east-1.prod.sh.example.com/v1

/shipments/{shipmentId}/customs

Update or add customs documentation for international shipments

Update customs documentation › path Parameters

shipmentId

string · uuid · required

Update customs documentation › Headers

X-Correlation-ID

string · uuid

Unique identifier for tracking requests across multiple services

Idempotency-Key

string · uuid

Unique key to ensure idempotency of the request

X-Customs-Region

string · enum

Customs processing region for the shipment

Enum values:

APAC

Default: NA

Update customs documentation › Request Body

object[] · required

purpose

string · enum

Enum values:

COMMERCIAL

PERSONAL

GIFT

RETURN

REPAIR

incoterm

string · enum

Enum values:

DAP

DDP

FCA

EXW

Update customs documentation › Responses

200

Customs documentation updated successfully

id

string · uuid

status

string · enum

Enum values:

PENDING

APPROVED

REJECTED

customsValue

number · float

currency

string

object[]

PUT/shipments/{shipmentId}/customs

const options = {
  method: 'PUT',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    items: [
      {
        description: 'Smartphone',
        quantity: 10,
        value: 399.99,
        weight: 0.18,
        hsCode: '851712',
        originCountry: 'CN'
      },
      {
        description: 'Protective Cases',
        quantity: 10,
        value: 9.99,
        weight: 0.05,
        hsCode: '392690',
        originCountry: 'CN'
      }
    ],
    purpose: 'COMMERCIAL',
    incoterm: 'DDP'
  })
};

fetch('https://acme-logistics.us-east-1.prod.sh.example.com/v1/shipments/:shipmentId/customs', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Example Request Body

{
  "items": [
    {
      "description": "Smartphone",
      "quantity": 10,
      "value": 399.99,
      "weight": 0.18,
      "hsCode": "851712",
      "originCountry": "CN"
    },
    {
      "description": "Protective Cases",
      "quantity": 10,
      "value": 9.99,
      "weight": 0.05,
      "hsCode": "392690",
      "originCountry": "CN"
    }
  ],
  "purpose": "COMMERCIAL",
  "incoterm": "DDP"
}

json

application/json

Example Responses

{
  "id": "a1b2c3d4-e5f6-4a5b-9c8d-1a2b3c4d5e6f",
  "status": "APPROVED",
  "customsValue": 4099.8,
  "currency": "USD",
  "documents": [
    {
      "type": "COMMERCIAL_INVOICE",
      "url": "https://api.sh.example.com/v1/customs/docs/invoice_12345.pdf"
    },
    {
      "type": "DECLARATION",
      "url": "https://api.sh.example.com/v1/customs/docs/declaration_12345.pdf"
    }
  ]
}

json

application/json

Pay import duties

POST

https://acme-logistics.us-east-1.prod.sh.example.com/v1

/shipments/{shipmentId}/customs/duties

Pay import duties and taxes for an international shipment

Pay import duties › path Parameters

shipmentId

string · uuid · required

Pay import duties › Request Body

paymentMethod

string · enum · required

Enum values:

CREDIT_CARD

BANK_TRANSFER

ACCOUNT_BALANCE

object

Pay import duties › Responses

200

Duties paid successfully

amount

number · float

currency

string

receipt

string · uri

POST/shipments/{shipmentId}/customs/duties

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({paymentMethod: 'CREDIT_CARD', paymentDetails: {last4: '4242', brand: 'visa'}})
};

fetch('https://acme-logistics.us-east-1.prod.sh.example.com/v1/shipments/:shipmentId/customs/duties', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Example Request Body

{
  "paymentMethod": "CREDIT_CARD",
  "paymentDetails": {
    "last4": "4242",
    "brand": "visa"
  }
}

json

application/json

Example Responses

{
  "amount": 125.5,
  "currency": "GBP",
  "receipt": "https://api.sh.example.com/v1/receipts/duty_123456.pdf"
}

json

application/json

Rates & Billing Documentation

Update customs documentation

PUT

https://acme-logistics.us-east-1.prod.sh.example.com/v1

/shipments/{shipmentId}/customs

Update or add customs documentation for international shipments

Update customs documentation › path Parameters

shipmentId

string · uuid · required

Update customs documentation › Headers

X-Correlation-ID

string · uuid

Unique identifier for tracking requests across multiple services

Idempotency-Key

string · uuid

Unique key to ensure idempotency of the request

X-Customs-Region

string · enum

Customs processing region for the shipment

Enum values:

APAC

Default: NA

Update customs documentation › Request Body

object[] · required

purpose

string · enum

Enum values:

COMMERCIAL

PERSONAL

GIFT

RETURN

REPAIR

incoterm

string · enum

Enum values:

DAP

DDP

FCA

EXW

Update customs documentation › Responses

200

Customs documentation updated successfully

id

string · uuid

status

string · enum

Enum values:

PENDING

APPROVED

REJECTED

customsValue

number · float

currency

string

object[]

const options = { method: 'PUT', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({ items: [ { description: 'Smartphone', quantity: 10, value: 399.99, weight: 0.18, hsCode: '851712', originCountry: 'CN' }, { description: 'Protective Cases', quantity: 10, value: 9.99, weight: 0.05, hsCode: '392690', originCountry: 'CN' } ], purpose: 'COMMERCIAL', incoterm: 'DDP' }) }; fetch('https://acme-logistics.us-east-1.prod.sh.example.com/v1/shipments/:shipmentId/customs', options) .then(response => response.json()) .then(response => console.log(response)) .catch(err => console.error(err));

{ "items": [ { "description": "Smartphone", "quantity": 10, "value": 399.99, "weight": 0.18, "hsCode": "851712", "originCountry": "CN" }, { "description": "Protective Cases", "quantity": 10, "value": 9.99, "weight": 0.05, "hsCode": "392690", "originCountry": "CN" } ], "purpose": "COMMERCIAL", "incoterm": "DDP" }

{ "id": "a1b2c3d4-e5f6-4a5b-9c8d-1a2b3c4d5e6f", "status": "APPROVED", "customsValue": 4099.8, "currency": "USD", "documents": [ { "type": "COMMERCIAL_INVOICE", "url": "https://api.sh.example.com/v1/customs/docs/invoice_12345.pdf" }, { "type": "DECLARATION", "url": "https://api.sh.example.com/v1/customs/docs/declaration_12345.pdf" } ] }

Pay import duties

POST

https://acme-logistics.us-east-1.prod.sh.example.com/v1

/shipments/{shipmentId}/customs/duties

Pay import duties and taxes for an international shipment

Pay import duties › path Parameters

shipmentId

string · uuid · required

Pay import duties › Request Body

paymentMethod

string · enum · required

Enum values:

CREDIT_CARD

BANK_TRANSFER

ACCOUNT_BALANCE

object

Pay import duties › Responses

200

Duties paid successfully

amount

number · float

currency

string

receipt

string · uri

const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({paymentMethod: 'CREDIT_CARD', paymentDetails: {last4: '4242', brand: 'visa'}}) }; fetch('https://acme-logistics.us-east-1.prod.sh.example.com/v1/shipments/:shipmentId/customs/duties', options) .then(response => response.json()) .then(response => console.log(response)) .catch(err => console.error(err));