shippex v0.6.8 Shippex

Configuration

config :shippex,
  env: :dev,
  distance_unit: :in, # either :in or :cm
  weight_unit: :lbs, # either :lbs or :kg
  currency: :usd, # :usd, :can, :mxn, :eur
  carriers: [
    ups: [
      username: "MyUsername",
      password: "MyPassword",
      secret_key: "123123",
      shipper: %{
        account_number: "AB1234",
        name: "My Company",
        phone: "123-456-7890",
        address: "1234 Foo St",
        city: "Foo",
        state: "TX",
        zip: "78999"
      }
    ],
    usps: [
      username: "MyUsername",
      password: "MyPassword"
    ]
  ]

Create origin/destination addresses

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

destination = Shippex.Address.address(%{
  name: "Bar Baz",
  phone: "123-123-1234",
  address: "1234 Foo Blvd",
  address_line_2: nil,
  city: "Plano",
  state: "TX",
  zip: "75074"
})

Create a package

# Currently only inches and pounds (lbs) supported.
package = %Shippex.Package{
  length: 8,
  width: 8,
  height: 4,
  weight: 5,
  description: "Headphones"
}
shipment = %Shippex.Shipment{
  from: origin,
  to: destination,
  package: package
}

Fetch rates to present to the user.

rates = Shippex.fetch_rates(shipment)

Accept one of the services and print the label

{:ok, rate} = Enum.shuffle(rates) |> hd
{:ok, label} = Shippex.fetch_label(rate, shipment)

Write the label gif to disk

File.write!("#{label.tracking_number}.gif", Base.decode64!(label.image))

Link to this section Summary

Functions

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

Provides a method of returning all available carriers. This is based on the config and does not include validation

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

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

Link to this type response()
response() :: %{code: String.t, message: String.t}

Link to this section Functions

Link to this function cancel_transaction(transaction)
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)
cancel_transaction(Shippex.Carrier.t, Shippex.Shipment.t, String.t) :: {atom, response}
Link to this function carriers()
carriers() :: [Shippex.Carrier.t]

Provides a method of returning all available carriers. This is based on the config and does not include validation.

Shippex.carriers #=> [:ups]
Link to this function create_transaction(shipment, service)
create_transaction(Shippex.Shipment.t, Shippex.Service.t) :: {atom, Shippex.Transaction.t}

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)
fetch_rate(Shippex.Shipment.t, atom | Shippex.Service.t) :: {atom, Shippex.Rate.t}

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 \\ [])
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 validate_address(address, opts \\ [])
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",
  zip: "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