Shipping

Shipping zones and prices.

This page covers the shipping rate card object and the shipping quote object.

Endpoints

The shipping rate card object

What buyers pay for shipping. An order ships for the base_price of the tier of its heaviest single item (never the summed weight), plus per_additional_item for every other item. Items under extra_small_max_weight_grams ride along without the additional charge, unless they come with extra parts. Example: three small items and one medium item to EU Core cost the medium base price plus three additional items. When a zone has no price of its own for a tier, checkout charges that tier at the zone medium price (per additional item charge included), or, when the zone prices no medium tier either, a flat default for the whole parcel with no per additional item charge. The prices here already show that fallback, so they are always what checkout charges.

Attributes

objectstring
Names the type of this object. Always shipping_rate_card.
currencystring
Currency of every price on the card.
Always usd
tiersarray of object
Tier limits, lightest first.
extra_small_max_weight_gramsinteger
Items under this weight do not add the per-additional-item charge. Extra small is a flag on an item, not a tier you can quote: such an item is priced as small when it is the heaviest in the parcel, and is left out of additional_items otherwise.
zonesarray of ShippingZone
Every active zone, or only the matching one with country.

The shipping rate card object

{
  "object": "shipping_rate_card",
  "currency": "usd",
  "tiers": [
    {
      "tier": "small",
      "max_weight_grams": 600
    },
    {
      "tier": "medium",
      "max_weight_grams": 2000
    },
    {
      "tier": "large",
      "max_weight_grams": null
    }
  ],
  "extra_small_max_weight_grams": 100,
  "zones": [
    {
      "code": "eu-core",
      "object": "shipping_zone",
      "name": "EU Core",
      "countries": [
        "DE",
        "NL",
        "BE",
        "PL",
        "RO"
      ],
      "rest_of_world": false,
      "base_price": {
        "small": {
          "amount": 599,
          "currency": "usd"
        },
        "medium": {
          "amount": 799,
          "currency": "usd"
        },
        "large": {
          "amount": 1299,
          "currency": "usd"
        }
      },
      "per_additional_item": {
        "amount": 100,
        "currency": "usd"
      }
    },
    {
      "code": "rest-of-world",
      "object": "shipping_zone",
      "name": "Rest of World",
      "countries": [],
      "rest_of_world": true,
      "base_price": {
        "small": {
          "amount": 1599,
          "currency": "usd"
        },
        "medium": {
          "amount": 1999,
          "currency": "usd"
        },
        "large": {
          "amount": 2999,
          "currency": "usd"
        }
      },
      "per_additional_item": {
        "amount": 100,
        "currency": "usd"
      }
    }
  ]
}

Get the shipping rate card

GET/v2/shipping/rates

Public: no API key needed.

Credentials: None: the endpoint is public.
For: Designers and Integrators
Operation id: get_shipping_rates

Returns every shipping zone with its prices per tier. Public: no credentials needed. An order ships for the base_price of the tier of its heaviest single item (never the summed weight), plus per_additional_item for every other item. Items under extra_small_max_weight_grams ride along without the additional charge, unless they come with extra parts. Example: three small items and one medium item to EU Core cost the medium base price plus three additional items. When a zone has no price of its own for a tier, checkout charges that tier at the zone medium price (per additional item charge included), or, when the zone prices no medium tier either, a flat default for the whole parcel with no per additional item charge. The prices here already show that fallback, so they are always what checkout charges. For a single price, use the shipping quote instead.

Query parameters

countrystring
Only return the zone that ships to this country. Russia, Belarus, Iran and Syria return no zones: 3DAPI does not deliver there.

Returns200 OK

The rate card. Returns the shipping rate card object.

Responses

200
The rate card.
400
The request is invalid. details.errors lists each problem (validation_failed), or an expand[] path is unknown (invalid_expand).
429
Too many requests (rate_limited): the limit is 120 per minute per IP address. Wait for the number of seconds in the Retry-After header, then retry; details has limit, window_seconds, reset_at and retry_after_seconds.

Errors use the error object.

GET/v2/shipping/rates

curl "https://public-api.dapi.digital/v2/shipping/rates"

Response

{
  "object": "shipping_rate_card",
  "currency": "usd",
  "tiers": [
    {
      "tier": "small",
      "max_weight_grams": 600
    },
    {
      "tier": "medium",
      "max_weight_grams": 2000
    },
    {
      "tier": "large",
      "max_weight_grams": null
    }
  ],
  "extra_small_max_weight_grams": 100,
  "zones": [
    {
      "code": "eu-core",
      "object": "shipping_zone",
      "name": "EU Core",
      "countries": [
        "DE",
        "NL",
        "BE",
        "PL",
        "RO"
      ],
      "rest_of_world": false,
      "base_price": {
        "small": {
          "amount": 599,
          "currency": "usd"
        },
        "medium": {
          "amount": 799,
          "currency": "usd"
        },
        "large": {
          "amount": 1299,
          "currency": "usd"
        }
      },
      "per_additional_item": {
        "amount": 100,
        "currency": "usd"
      }
    },
    {
      "code": "rest-of-world",
      "object": "shipping_zone",
      "name": "Rest of World",
      "countries": [],
      "rest_of_world": true,
      "base_price": {
        "small": {
          "amount": 1599,
          "currency": "usd"
        },
        "medium": {
          "amount": 1999,
          "currency": "usd"
        },
        "large": {
          "amount": 2999,
          "currency": "usd"
        }
      },
      "per_additional_item": {
        "amount": 100,
        "currency": "usd"
      }
    }
  ]
}

The shipping quote object

The shipping price for one parcel to one country.

Attributes

objectstring
Names the type of this object. Always shipping_quote.
zoneobject
The zone that serves the country.
country_codestring
ISO 3166-1 alpha-2 country code, uppercase. A code that is not a real country is refused with validation_failed.
tierShippingTier
Weight class of an item, by the greater of its actual and volumetric weight: small up to 600 g, medium up to 2 kg, large above.
Possible valuessmallmediumlarge
base_priceobject
Base price of the tier in this zone. When the zone does not price the tier, the fallback checkout charges: the zone medium price, else the flat default.
additional_itemsinteger
Items charged on top of the heaviest one.
Range at least 0.
per_additional_itemobject
Charge for each additional item in this zone.
totalobject
What the shipping costs: base_price plus per_additional_item times additional_items.

The shipping quote object

{
  "object": "shipping_quote",
  "zone": {
    "code": "eu-core",
    "name": "EU Core"
  },
  "country_code": "DE",
  "tier": "medium",
  "base_price": {
    "amount": 799,
    "currency": "usd"
  },
  "additional_items": 3,
  "per_additional_item": {
    "amount": 100,
    "currency": "usd"
  },
  "total": {
    "amount": 1099,
    "currency": "usd"
  }
}

Get a shipping price

GET/v2/shipping/quote

Public: no API key needed.

Credentials: None: the endpoint is public.
For: Designers and Integrators
Operation id: get_shipping_quote

Returns what one parcel costs to ship to a country, given the tier of its heaviest item and how many other items travel with it. Public: no credentials needed. Computed exactly as checkout does, including its fallback for a tier the zone does not price (the zone medium price, else a flat default for the whole parcel with per_additional_item 0). Every country is served except Russia, Belarus, Iran and Syria, which 3DAPI does not deliver to (422 shipping_destination_not_served); the rest-of-world zone covers countries no other zone lists. A code that is not a country is a 400.

Query parameters

countrystringRequired
Destination country.
tierstringRequired
Tier of the heaviest item in the parcel. There is no extra_small tier: an extra-small item is quoted as small.
Possible valuessmallmediumlarge
additional_itemsinteger or null
How many other items ship in the same parcel, extra-small items excluded. 0 for a single item.
Range 0 to 1000. Defaults to 0.

Returns200 OK

The price. Returns the shipping quote object.

Responses

200
The price.
400
The request is invalid. details.errors lists each problem (validation_failed), or an expand[] path is unknown (invalid_expand).
404
No active zone serves the country (shipping_zone_not_found). Only possible if 3DAPI has switched off the rest-of-world zone.
422
3DAPI does not deliver to the country (shipping_destination_not_served): Russia, Belarus, Iran and Syria.
429
Too many requests (rate_limited): the limit is 120 per minute per IP address. Wait for the number of seconds in the Retry-After header, then retry; details has limit, window_seconds, reset_at and retry_after_seconds.

Errors use the error object.

GET/v2/shipping/quote

curl "https://public-api.dapi.digital/v2/shipping/quote?country=DE&tier=small"

Response

{
  "object": "shipping_quote",
  "zone": {
    "code": "eu-core",
    "name": "EU Core"
  },
  "country_code": "DE",
  "tier": "medium",
  "base_price": {
    "amount": 799,
    "currency": "usd"
  },
  "additional_items": 3,
  "per_additional_item": {
    "amount": 100,
    "currency": "usd"
  },
  "total": {
    "amount": 1099,
    "currency": "usd"
  }
}