CatalogApi v0.0.16 CatalogApi View Source

Contains top-level API functions for making requests to CatalogAPI.

Link to this section Summary

Functions

Adds the specified catalog item id to the user’s shopping cart

Places an order using the address and items in the cart. Deletes the cart if this request is successful. Returns an error if the order could not be placed

Removes the specified item from the user’s cart

Sets the shipping address for the given user’s cart

Unlocks a cart that has been unlocked via the cart_validate method

Validates the address and items in the cart. This is intended to be called just before placing an order to make sure that the order would not be rejected

Returns the contents of the specified user’s shopping cart

Returns a list of all item categories for the given socket_id

Returns a list of the domains tied to the used credentials and those domain’s sockets

Lists the orders placed by the user associated with the external_user_id

Provides tracking information for a specific order number. Provides information on the current status, as well as metadata around fulfillment

Searches for CatalogApi items which meet the specified criteria

Retrieves information about a specific CatalogApi item

Link to this section Functions

Link to this function cart_add_item(socket_id, external_user_id, catalog_item_id, opts \\ []) View Source

Adds the specified catalog item id to the user’s shopping cart.

Optional parameters include:

  • option_id (optional): The id of the option for the item that should be added to the cart. If there are multiple options (such as color, size, etc.) for a given item, this allows the correct option to be added. This parameter is optional.
  • quantity (default: 1): The quantity of the given item to add to the cart.
Link to this function cart_empty(socket_id, external_user_id) View Source
Link to this function cart_order_place(socket_id, external_user_id, opts \\ []) View Source
cart_order_place(integer(), integer(), Keyword.t()) ::
  {:ok, CatalogApi.Order.t()}
  | {:error, :cart_not_found}
  | {:error, :no_shipping_address}
  | {:error, :stale_cart_version}
  | {:error, {:bad_status, integer()}}
  | {:error, {:catalog_api_fault, CatalogApi.Error.extracted_fault()}}
  | {:error, Jason.DecodeError.t()}

Places an order using the address and items in the cart. Deletes the cart if this request is successful. Returns an error if the order could not be placed.

There is one allowed optional parameter:

  • cart_version: If this is supplied, this method will only succeed if the passed version matches the version of the current cart. This can be used to ensure that the state of the users cart in your application has not become stale before the order is placed.

If the cart_order_place/3 is invoked with cart version which does not match the current version of the cart, then an error tuple will be returned of the format {:error, :stale_cart_version}. This can be useful to ensure that the order being placed matches what the consuming application believes the current state of the cart to be,

Link to this function cart_remove_item(socket_id, external_user_id, catalog_item_id, opts \\ []) View Source

Removes the specified item from the user’s cart.

Optional parameters include:

  • option_id: If there are multiple versions of a single item id with different options, this can be used to only remove items with the given option.
  • quantity: The quantity of the given item to remove. If this is not specified, then all items of this type are removed from the cart.

If the item doesn’t actually exist or was not in the given user’s cart then this still returns a response indicating that the operation was successful. This is a behavior of the CatalogAPI API itself and not specific to this CatalogApi library.

Example

iex> CatalogApi.cart_remove_item(1061, 200, 123456)
{:ok, %{description: "Item quantity decreased."}}
Link to this function cart_set_address(socket_id, external_user_id, address) View Source
cart_set_address(integer(), integer(), map()) ::
  {:ok, %{description: String.t()}}
  | {:error, CatalogApi.Address.invalid_address_error()}
  | {:error, {:bad_status, integer()}}
  | {:error, {:catalog_api_fault, CatalogApi.Error.extracted_fault()}}
  | {:error, Jason.DecodeError.t()}
  | {:error, :unparseable_response_description}

Sets the shipping address for the given user’s cart.

Requires a socket_id, an external_user_id, and a map of address parameters.

The list of available address parameters can be found in the module documentation for CatalogApi.Address.

You can use a %CatalogApi.Address{} struct for the address parameters argument.

If the address parameters are not valid as per CatalogApi.Address.validate_params/1, then this function will return an error tuple without making a call to the CatalogApi endpoint.

Link to this function cart_set_item_quantity(socket_id, external_user_id, catalog_item_id, option_id, quantity) View Source
Link to this function cart_unlock(socket_id, external_user_id) View Source

Unlocks a cart that has been unlocked via the cart_validate method.

Link to this function cart_validate(socket_id, external_user_id, locked \\ false) View Source

Validates the address and items in the cart. This is intended to be called just before placing an order to make sure that the order would not be rejected.

If the locked argument is supplied as true, then the cart will be locked. A locked cart cannot be modified and the address cannot be changed. This should be used before processing a credit card transaction so that users cannot change relevant information after the transaction has been finalized.

Link to this function cart_view(socket_id, external_user_id) View Source
cart_view(integer(), integer()) ::
  {:ok,
   %{items: [CatalogApi.Item.t()], status: map() | :cart_status_unavailable}}
  | {:error, atom()}

Returns the contents of the specified user’s shopping cart.

The return contains the list of items in the cart casted as CatalogApi.CartItem{} structs.

Also returns the address associated with the cart in the form of a %CatalogApi.Address{} struct. If there is no address associated with the given cart, then this still returns a %CatalogApi.Address{} struct, but the keys are all empty strings.

The return also returns a map under the :status key which contains some information about the status of the cart. The keys contained in this map are as follows:

  • error: An error string describing the error. When there is no error, this is “”.
  • has_item_errors: Boolean indicating whether the cart contains errors specific to items.
  • is_valid: Boolean indicating whether the cart is valid. If this is false, than this cart cannot be used to place an order
  • needs_address: Boolean indicating whether the cart is missing an address.
  • locked: Boolean indicating whether the cart is locked or not. If the cart is locked, an order can be placed with it, but it cannot be altered.
  • cart_version: A String uuid indicating the current version of the cart. This can be used to ensure that the cart which is being used to place an order has not changed since the application’s state has been updated.

Examples

iex> CatalogApi.cart_view(1000, 500)
{:ok,
 %{
   address: %CatalogApi.Address{
     address_1: "123 st",
     address_2: "",
     address_3: "",
     city: "cleveland",
     country: "US",
     email: "",
     first_name: "john",
     last_name: "gotty",
     phone_number: "",
     postal_code: "44444",
     state_province: "OH"
   },
   items: [
     %CatalogApi.CartItem{
       cart_price: "50.00",
       catalog_item_id: 3870422,
       catalog_points: 1000,
       catalog_price: "50.00",
       currency: "USD",
       error: "",
       image_uri: "https://dck0i7x64ch95.cloudfront.net/asset/1/8/9/189373b3846ed28cb788f1051b2af5db_75_.jpg",
       is_available: true,
       is_valid: true,
       name: "Marshalls® eGift Card $50",
       points: 1000,
       quantity: 2,
       retail_price: "50.00",
       shipping_estimate: "0.00"
     }
   ],
   status: %{
     cart_version: "5dd19634-e2b9-4c35-a9ec-9453a59ec22b",
     error: "",
     has_item_errors: false,
     is_valid: true,
     locked: false,
     needs_address: false
   }
 }}

In the event that the cart is empty, the response will look a bit different:

iex> CatalogApi.cart_view(1000, 99999)
{:ok,
 %{
   address: %CatalogApi.Address{
     address_1: "",
     address_2: "",
     address_3: "",
     city: "",
     country: "",
     email: "",
     first_name: "",
     last_name: "",
     phone_number: "",
     postal_code: "",
     state_province: ""
   },
   items: [],
   status: :cart_status_unavailable
 }}
Link to this function catalog_breakdown(socket_id, opts \\ []) View Source

Returns a list of all item categories for the given socket_id.

Requires a socket_id.

There are two optional parameters which can be supplied:

  • is_flat: If true, the returned categories are in a flat list. If false or not supplied as an option, then the categories are returned in a nested format.

  • tags: Can specify tags which narrow down the categories. The official documentation explains: We have the ability to “tag” certain items based on custom criteria that is unique to our clients. If we setup these tags on your catalog, you can pass a tag name to receive back only categories that contain items matching the tag.

Link to this function list_available_catalogs() View Source

Returns a list of the domains tied to the used credentials and those domain’s sockets.

A domain is something tied to a specific account. This includes information about the account in general.

A domain (and by extension an account) can have multiple sockets. Each socket represents a different catalog of items, point exchange rates, currency, language, among other information.

Link to this function order_list(external_user_id, opts \\ []) View Source

Lists the orders placed by the user associated with the external_user_id.

Options that can be supplied:

  • per_page: Maximum number of results to be displayed per page. Defaults to

    1. Maximum of 50.
  • page: Page of results to return.
Link to this function order_track(order_number) View Source

Provides tracking information for a specific order number. Provides information on the current status, as well as metadata around fulfillment.

If the item is a gift card, then this method provides additional information around gift card redemption as well as other metadata.

Link to this function search_catalog(socket_id, opts \\ %{}) View Source
search_catalog(integer(), map() | Keyword.t()) ::
  {:ok, %{items: CatalogApi.Item.t(), page_info: map()}}
  | {:error, {:bad_status, integer()}}
  | {:error, {:catalog_api_fault, CatalogApi.Error.extracted_fault()}}
  | {:error, Jason.DecodeError.t()}

Searches for CatalogApi items which meet the specified criteria.

Requires a socket_id and a list of criteria that returned items must match. All search parameters are optional.

Allowed search parameters:

  • name: The name of the item.
  • search: Matches the name, description or model of items.
  • category_id: Matches only items within this category_id. (This includes any child categories of the category_id.) The category_id comes from the catalog_breakdown method.
  • min_points: Matches only items that cost a greater or equal number of points.
  • max_points: Matches only items that cost a lesser or equal number of points.
  • min_price: Matches only items that cost a great or equal amount.
  • max_price: Matches only items that cost a lesser or equal amount.
  • max_rank: Matches only items with a rank lesser than or equal to the specified value. The rank of an item indicates its popularity between 1 and

    1. A smaller value indicates a more popular item.
  • tag: Matches items with custom tags.
  • page: The page to retrieve.
  • per_page: The quantity of items to retrieve per page. Must be between 1 and 50. The default is 10 if this parameter is not specified
  • sort: The method to use to sort the results. Allowed values are:

    • "points desc" - Will return items worth the most points first.
    • "points asc" - Will return items worth the least points first.
    • "rank asc": Will return items with the most popular ones first.
    • "score desc" (default): Will return items with the the most relevant. ones first. Sorting by score only makes sense when you are searching with the “name” or “search” arguments.
    • "random asc": Will return the items in random order.
  • catalog_item_ids: Accepts an array of items. Matches only items that ar in the given list.
Link to this function view_item(socket_id, catalog_item_id) View Source
view_item(integer(), integer() | String.t()) ::
  {:ok, %{item: CatalogApi.Item.t()}}
  | {:error, {:bad_status, integer()}}
  | {:error, {:catalog_api_fault, CatalogApi.Error.extracted_fault()}}
  | {:error, Jason.DecodeError.t()}
  | {:error, :item_not_found}

Retrieves information about a specific CatalogApi item.

Requires a socket_id and an item_id.

Returns a %CatalogApi.Item{} struct upon a successful request.

If the item does not exist, this returns an error tuple of the format {:error, :item_not_found}