Shippex (shippex v0.15.0) View Source

Module documentation for Shippex.

Link to this section Summary

Functions

Cancels the transaction associated with label, if possible. The result is returned in a tuple.

Fetches the label for shipment for a specific Service. The service module contains the Carrier and selected delivery speed.

Fetches the rate for shipment for a specific Service. The service module contains the Carrier and selected delivery speed. You can also pass in the ID of the service.

Fetches rates for a given shipment. Possible options

Returns true if the carrier services the given country. An ISO-3166-compliant country code is required.

Returns the status for the given tracking numbers.

Performs address validation. If the address is completely invalid, {:error, result} is returned. For addresses that may have typos, {:ok, candidates} is returned. You can iterate through the list of candidates to present to the end user. Addresses that pass validation perfectly will still be in a list where length(candidates) == 1.

Link to this section Types

Specs

response() :: %{code: String.t(), message: String.t()}

Link to this section Functions

Link to this function

cancel_transaction(transaction)

View Source

Specs

cancel_transaction(Shippex.Transaction.t()) :: {atom(), response()}

Cancels the transaction associated with label, if possible. The result is returned in a tuple.

You may pass in either the transaction, or if the full transaction struct isn't available, you may pass in the carrier, shipment, and tracking number instead.

case Shippex.cancel_shipment(transaction) do
  {:ok, result} ->
    IO.inspect(result) #=> %{code: "1", message: "Voided successfully."}
  {:error, %{code: code, message: message}} ->
    IO.inspect(code)
    IO.inspect(message)
end
Link to this function

cancel_transaction(carrier, shipment, tracking_number)

View Source

Specs

cancel_transaction(Shippex.Carrier.t(), Shippex.Shipment.t(), String.t()) ::
  {atom(), response()}
Link to this function

create_transaction(shipment, service)

View Source

Specs

create_transaction(Shippex.Shipment.t(), Shippex.Service.t()) ::
  {:ok, Shippex.Transaction.t()} | {:error, response()}

Fetches the label for shipment for a specific Service. The service module contains the Carrier and selected delivery speed.

Shippex.create_transaction(shipment, service)
Link to this function

fetch_rate(shipment, service)

View Source

Specs

Fetches the rate for shipment for a specific Service. The service module contains the Carrier and selected delivery speed. You can also pass in the ID of the service.

Shippex.fetch_rate(shipment, service)
Link to this function

fetch_rates(shipment, opts \\ [])

View Source

Specs

fetch_rates(Shippex.Shipment.t(), Keyword.t()) :: [{atom(), Shippex.Rate.t()}]

Fetches rates for a given shipment. Possible options:

  • carriers - Fetches rates for all services for the given carriers
  • services - Fetches rates only for the given services

These may be used in combination. To fetch rates for all UPS services, as well as USPS Priority, for example:

Shippex.fetch_rates(shipment, carriers: :ups, services: [:usps_priority])

If no options are provided, Shippex will fetch rates for every service from every available carrier.

Link to this function

services_country?(carrier, country)

View Source

Specs

services_country?(Shippex.Carrier.t(), ISO.country_code()) :: boolean()

Returns true if the carrier services the given country. An ISO-3166-compliant country code is required.

iex> Shippex.services_country?(:usps, "US")
true

iex> Shippex.services_country?(:usps, "KP")
false
Link to this function

track_packages(carrier, tracking_numbers)

View Source

Specs

track_packages(Shippex.Carrier.t(), [String.t()]) :: {atom(), response()}

Returns the status for the given tracking numbers.

Link to this function

validate_address(address, opts \\ [])

View Source

Specs

validate_address(Shippex.Address.t(), Keyword.t()) ::
  {atom(), response() | [Shippex.Address.t()]}

Performs address validation. If the address is completely invalid, {:error, result} is returned. For addresses that may have typos, {:ok, candidates} is returned. You can iterate through the list of candidates to present to the end user. Addresses that pass validation perfectly will still be in a list where length(candidates) == 1.

Note that the candidates returned will automatically pass through Shippex.Address.address() for casting. Also, if :usps is used as the validation provider, the number of candidates will always be 1.

address = Shippex.Address.address(%{
  name: "Earl G",
  phone: "123-123-1234",
  address: "9999 Hobby Lane",
  address_line_2: nil,
  city: "Austin",
  state: "TX",
  postal_code: "78703"
})

case Shippex.validate_address(address) do
  {:error, %{code: code, message: message}} ->
    # Present the error.
  {:ok, candidates} when length(candidates) == 1 ->
    # Use the address
  {:ok, candidates} when length(candidates) > 1 ->
    # Present candidates to user for selection
end