Duck, Goose, Chicken & Game Bird Hatchery

API Documentation

availability_get error_list function_list order_cancel order_change_shipdate order_get order_list order_place order_search order_update ship_method_get_list sku_list substitutions_get_list

availability_get

Get a list of bird availabilty as of when this function is executed. The results are in list 'availability'. Each hash in that list has skuid, shipdate, available.

Parameters

Name Format Type List Entry Type Required Max Length Description Valid Values
include_sold true or false bool false Default is false. If true, include 'sold' in each output record that is a summary of the sales at the time this function is executed. The caller may use this to fine-tune the resulting availability in the case that the caller has orders that have not yet been sent to the client.

Output Fields

Name Description
_environment Notation of the environment in which the response was generated. For internal troubleshooting.
_hostname Notation of the host on which the response was generated. For internal troubleshooting.
availability List of availability records current as of the time this function was executed
availability.available Number of this item/SKU that are available
availability.shipdate Ship date on which this item/SKU is available
availability.skuid ID of the item/SKU that is available. See sku_list for more information about the SKUs.
availability.sold Only included if include_sold is true. A summary of the sales at the time this function is executed.

error_list

Get a list of all known error codes and the description mask for each.

Parameters

Name Format Type List Entry Type Required Max Length Description Valid Values

Output Fields

Name Description
_environment Notation of the environment in which the response was generated. For internal troubleshooting.
_hostname Notation of the host on which the response was generated. For internal troubleshooting.
errors List of all known API errors
errors.error_code Unique integer error code. The error_code field uniquely identifies an error condition and will be mostly stable over the lifespan of the API.
errors.description Description of the error. These descriptions may change over time.

function_list

Return a complete list of API functions, any required parameters for each, and a description of the output fields

Parameters

Name Format Type List Entry Type Required Max Length Description Valid Values

Output Fields

Name Description
_environment Notation of the environment in which the response was generated. For internal troubleshooting.
_hostname Notation of the host on which the response was generated. For internal troubleshooting.
functions List of available API functions
functions.function_name Name of the API function - case sensitive
functions.description Description of the function - operation, inputs and outputs
output_fields List of output fields of the function
output_fields.name Name of the output field
output_fields.description Description of the output field
parameters List of parameters to the function
parameters.name Name of the parameter, case sensitive
parameters.required Is the parameter always required?
parameters.type Type/format of the parameter value
parameters.max_length Maximum length of the string parameter
parameters.list_entry_type If this is a list, the type of entries that are allowed in the list
parameters.description Description of the parameter
parameters.format format of the parameter
parameters.valid_values List of valid values for this parameter

order_cancel

Cancel an order. You must specify at least one of orderid and partner_orderid. If you specify both, the orderid must match the order with the given partner_orderid in our system. If the cancel is successful, the output fields are the same as order_get.

Parameters

Name Format Type List Entry Type Required Max Length Description Valid Values
orderid integer integer false Internal ID of the order to cancel
partner_orderid string string false 60 Partner's unique order identfier
note string string false 500 Optional note to record on the order when it is caneled. This note may not ever be seen by anyone, but it will be on the records of the order.

Output Fields

Name Description
_environment Notation of the environment in which the response was generated. For internal troubleshooting.
_hostname Notation of the host on which the response was generated. For internal troubleshooting.

order_change_shipdate

Change the shipping date of an order. You must specify at least one of orderid and partner_orderid. If you specify both, the orderid must match the order with the given partner_orderid in our system. If the update is successful, the output fields are the same as order_get.

Parameters

Name Format Type List Entry Type Required Max Length Description Valid Values
orderid integer integer false Internal ID of the order to cancel
partner_orderid string string false 60 Partner's unique order identfier
assign_ship_date true or false bool false Default is false. If true, assign the first ship date on which the entire order is available. You must specify exactly one of assign_ship_date=true and ship_date.
ship_date yyyy-mm-dd date false Date on which this order is to ship. You must specify exactly one of assign_ship_date=true and ship_date.
carry_along true or false bool false Default is unspecified. If specified, the carry_along value of the order is changed to the specified value. Has this order been carried along, that is, delayed because of insufficient inventory.
error_on_no_change true or false bool false Default is true. If true, an error returned if no change in ship date is detected. If false, no error is returned if no change in ship date is detected.

Output Fields

Name Description
_environment Notation of the environment in which the response was generated. For internal troubleshooting.
_hostname Notation of the host on which the response was generated. For internal troubleshooting.

order_get

Get all available details for a single order, using the internal order ID

Parameters

Name Format Type List Entry Type Required Max Length Description Valid Values
orderid integer integer true Internal ID of the order to retrieve

Output Fields

Name Description
_environment Notation of the environment in which the response was generated. For internal troubleshooting.
_hostname Notation of the host on which the response was generated. For internal troubleshooting.
orderid The internal ID of this order. This is the field that must be used in other functions to manipulate orders, except those that specifically search or retrieve by external order ID.
canceled Is this order canceled? A canceled order will not ship or be billed/invoiced.
ship_date Currently assigned ship date, yyyy-MM-dd
ship_date_original The original assigned ship date, yyyy-MM-dd
created Date/time this order was first created in the system
can_bypass_availability Can the date on this order be changed to a date on which there is not enough calculated availability for the birds in the order. This may be set by the client in situations where an order cannot ship because of a shortage of birds (carry along).
ship_address Structure that shows the current shipping address of this order
ship_address.firstname First name of recipient. May be blank for businesses.
ship_address.initial Middle name/initial of recipient. May be blank for businesses.
ship_address.lastname Last name of recipieint. May be full name of a business.
ship_address.attn Attention line of shipping address
ship_address.address1 Shipping address line 1
ship_address.address2 Shipping address line 2
ship_address.address3 Shipping address line 3
ship_address.city Shipping city
ship_address.state Shipping state
ship_address.zip Shipping zip / postal code
ship_address.country Shipping country
ship_address.phone1 Shipping phone number 1
ship_address.phone1ext Shipping phone number 1 (extension)
ship_address.phone1type Shipping phone number 1 (type: 'home','work','mobile','fax','other')
ship_address.phone2 Shipping phone number 2
ship_address.phone2ext Shipping phone number 2 (extension)
ship_address.phone2type Shipping phone number 2 (type: 'home','work','mobile','fax','other')
physical_address Structure that shows the current physcial address of this order. The physical address should be used if the order is a bird order being shipped to a PO box. The physical address is used for the NPIP VS9-3 form.
physical_address.firstname First name of physcial address recipient. May be blank for businesses.
physical_address.initial Middle name/initial of physcial address recipient
physical_address.lastname Last name of physcial address recipieint. May be full name of a business.
physical_address.attn Attention line of physcial address
physical_address.address1 Physical address line 1
physical_address.address2 Physical address line 2
physical_address.address3 Physical address line 3
physical_address.city Physical city
physical_address.state Physical state
physical_address.zip Physical zip / postal code
physical_address.country Physical country
physical_address.phone1 Physical phone number 1
physical_address.phone1ext Physical phone number 1 (extension)
physical_address.phone1type Physical phone number 1 (type: 'home','work','mobile','fax','other')
physical_address.phone2 Physical phone number 2
physical_address.phone2ext Physical phone number 2 (extension)
physical_address.phone2type Physical phone number 2 (type: 'home','work','mobile','fax','other')
partner_orderid The partner's unique identifier for this order (external ID)
po_number The partner's purchase order (PO) number, if any
carry_along Has this order been 'carried along' = delayed due to insufficient hatched birds
ship_method Shipping method assigned to this order
substitutions What type of subsitiutions are allowed on this order if there are not enough of the requested items? similar_breeds=substitute from similar breeds. from_order=substitute from other breeds listed in the order. Blank or missing means no substitutions are allowed.
tracking_numbers List of tracking numbers for this order. Orders may have more than one shipment.
tracking_numbers.carrier The carrier with which this package was shipped
tracking_numbers.tracking_number The carrier's tracking number for this shipment
details List of details (line items) in the order
details.skuid SKU ID of this item (internal identifier)
details.quantity Quantity of this item included in the order
details.price Unit price of this line item
details.description Description of this line item
details.additional_info Optional additional information to print on the pack slip.

order_list

Get a list of orders matching the given partner order ID (external ID) exactly

Parameters

Name Format Type List Entry Type Required Max Length Description Valid Values
partner_orderid string string true Partner / external order number

Output Fields

Name Description
_environment Notation of the environment in which the response was generated. For internal troubleshooting.
_hostname Notation of the host on which the response was generated. For internal troubleshooting.
orders List of matching orders. The format of each order is exactly the same as that produced by order_get.

order_place

Place a new order. If successful, the output will be the same as the order_list function. Most invocations of this function should result in a single order, but it is possible that multiple orders will result.

Parameters

Name Format Type List Entry Type Required Max Length Description Valid Values
partner_orderid string string true 60 Partner's unique order identfier
single_order_only true or false bool false Default is true. Certain combination of items ordered could result in multiple orders in our system (e.g. birds and non-lives in the same order). If this value is true, and the incoming order would result in multiple orders in our system, the order will be rejected with a 1072 error. If this value is false, multiple internal orders are allowed. If a single incoming order results in multiple internal orders, you will not be able to use partner_orderid as the 'key' in functions that operate on a single order (order_cancel, order_change_shipdate, order_update).
assign_ship_date true or false bool false Default is false. If true, assign the first ship date on which the entire order is available. You must specify exactly one of assign_ship_date=true and ship_date.
ship_date yyyy-mm-dd date false Date on which this order is to ship. You must specify exactly one of assign_ship_date=true and ship_date.
ship_address hash_not_empty true Structure that shows the current shipping address of this order
ship_address.firstname string string false 100 First name of recipient. May be blank for businesses.
ship_address.initial string string false 100 Middle name/initial of recipient. May be blank for businesses.
ship_address.lastname string string true 100 Last name of recipieint. May be full name of a business.
ship_address.attn string string false 200 Attention line of shipping address
ship_address.address1 string string true 100 Shipping address line 1
ship_address.address2 string string false 100 Shipping address line 2
ship_address.address3 string string false 100 Shipping address line 3
ship_address.city string string true 100 Shipping city
ship_address.state string string true 100 Shipping state
ship_address.zip 5 digit US zip code zip true 50 Shipping zip / postal code
ship_address.country string string true 50 Shipping country
ship_address.phone1 10 digit phone number, no spaces or punctuation phone true Shipping phone number 1
ship_address.phone1ext string string false 10 Shipping phone number 1 (extension)
ship_address.phone1type phone_type false Shipping phone number 1 (type)
home home
work work
mobile mobile
fax fax
other other
ship_address.phone2 10 digit phone number, no spaces or punctuation phone false Shipping phone number 2
ship_address.phone2ext string string false 10 Shipping phone number 2 (extension)
ship_address.phone2type phone_type false Shipping phone number 2 (type)
home home
work work
mobile mobile
fax fax
other other
physical_address hash_not_empty false Structure that shows the physcial address of this order. The physical address is required if the order is a bird order being shipped to a PO box. The physical address is used for the NPIP VS9-3 form. If there is not a physical address, omit this field.
physical_address.firstname string string false 100 First name of physical address recipient. May be blank for businesses.
physical_address.initial string string false 100 Middle name/initial of physical address recipient. May be blank for businesses.
physical_address.lastname string string true 100 Last name of physical address recipieint. May be full name of a business.
physical_address.attn string string false 200 Attention line of Physical address
physical_address.address1 string string true 100 Physical address line 1
physical_address.address2 string string false 100 Physical address line 2
physical_address.address3 string string false 100 Physical address line 3
physical_address.city string string true 100 Physical city
physical_address.state string string true 100 Physical state
physical_address.zip 5 digit US zip code zip true 50 Physical zip / postal code
physical_address.country string string true 50 Physical country
physical_address.phone1 10 digit phone number, no spaces or punctuation phone true Physical phone number 1
physical_address.phone1ext string string false 10 Physical phone number 1 (extension)
physical_address.phone1type phone_type false Physical phone number 1 (type)
home home
work work
mobile mobile
fax fax
other other
physical_address.phone2 10 digit phone number, no spaces or punctuation phone false Physical phone number 2
physical_address.phone2ext string string false 10 Physical phone number 2 (extension)
physical_address.phone2type phone_type false Physical phone number 2 (type)
home home
work work
mobile mobile
fax fax
other other
internal_note string string false 5000 Internal-only note. Customer will not see this. Partner may not see it.
packslip_note string string false 100 Customer-visible note to print on pack slip
ship_method valid shipping method ship_method false Optional shipping method
EGGS Eggs Best Way 3 day
EXPR Express Mail
PRI Priority Mail
carry_along true or false bool false Default is false. Has this order been carried along, that is, delayed because of insufficient inventory
po_number string string false 30 Partner's purchase order number
substitutions valid substitutions value substitutions false What type of substitutions are allowed if there are not enough of a given item.
none No substitutions allowed
similar_breeds Substitute with similar breeds
from_order Substitute only from breeds in the order
vaccinate true or false bool false If client operates with order-level vaccinations, this must be a boolean indicating whether or not the order is to be vaccinated
details list_not_empty hash_not_empty true List of details (line items) in the order
details.skuid integer integer true SKU ID of this item (internal identifier)
details.quantity integer integer true Quantity of this item to include in the order
details.additional_info string string false 100 Optional additional information to print on the pack slip.

Output Fields

Name Description
_environment Notation of the environment in which the response was generated. For internal troubleshooting.
_hostname Notation of the host on which the response was generated. For internal troubleshooting.
orderid The internal ID of this order. This is the field that can be used in other functions to manipulate orders, except those that specifically search or retrieve by external order ID.
order_count Number of internal orders resulting from this function execution.

order_search

Search for orders by the given criteria

Parameters

Name Format Type List Entry Type Required Max Length Description Valid Values
from_ship_date yyyy-mm-dd date true Search from this ship date. If through_ship_date is omitted, only orders matching this date are returned.
through_ship_date yyyy-mm-dd date false Search through this ship date. If this date is omitted, only orders matching from_ship_date are returned.
search_term string string false If provided, only return orders that match this search term in the customer name, city or state.

Output Fields

Name Description
_environment Notation of the environment in which the response was generated. For internal troubleshooting.
_hostname Notation of the host on which the response was generated. For internal troubleshooting.
orders List of matching orders. The format of each order is exactly the same as that produced by order_get except that details and tracking_numbers are not included

order_update

Update an order based on the parameters supplied to the function. You must specify at least one of orderid and partner_orderid. If you specify both, the orderid must match the order with the given partner_orderid in our system. Only those parameters that are specified are updated. If the update is successful, the output is the same as order_get. Note: certain order checks are invoked when this function is executed, even if nothing changes on the order. It is feasible that that rules could have changed since the order was first placed, resulting in an error here when none was present when the order was first placed. If this happens, you need to take steps to correct or cancel the order.

Parameters

Name Format Type List Entry Type Required Max Length Description Valid Values
orderid integer integer false Internal ID of the order to cancel
partner_orderid string string false 60 Partner's unique order identfier
new_partner_orderid string string false 60 New value of partner's unique order identfier. The new value must not be the same as another un-canceled order in the system.
carry_along true or false bool false Default is false. Has this order been carried along, that is, delayed because of insufficient inventory
assign_ship_date true or false bool false Default is false. If true, assign the first ship date on which the entire order is available. You may specify exactly one of assign_ship_date=true and ship_date.
ship_date yyyy-mm-dd date false Date on which this order is to ship. You may specify exactly one of assign_ship_date=true and ship_date.
ship_address hash_not_empty false Structure that shows the current shipping address of this order. If included, all of the address fields must be present.
ship_address.firstname string string false 100 First name of recipient. May be blank for businesses.
ship_address.initial string string false 100 Middle name/initial of recipient. May be blank for businesses.
ship_address.lastname string string true 100 Last name of recipieint. May be full name of a business.
ship_address.attn string string false 200 Attention line of shipping address
ship_address.address1 string string true 100 Shipping address line 1
ship_address.address2 string string false 100 Shipping address line 2
ship_address.address3 string string false 100 Shipping address line 3
ship_address.city string string true 100 Shipping city
ship_address.state string string true 100 Shipping state
ship_address.zip 5 digit US zip code zip true 50 Shipping zip / postal code
ship_address.country string string true 50 Shipping country
ship_address.phone1 10 digit phone number, no spaces or punctuation phone true Shipping phone number 1
ship_address.phone1ext string string false 10 Shipping phone number 1 (extension)
ship_address.phone1type phone_type false Shipping phone number 1 (type)
home home
work work
mobile mobile
fax fax
other other
ship_address.phone2 10 digit phone number, no spaces or punctuation phone false Shipping phone number 2
ship_address.phone2ext string string false 10 Shipping phone number 2 (extension)
ship_address.phone2type phone_type false Shipping phone number 2 (type)
home home
work work
mobile mobile
fax fax
other other
physical_address hash_not_empty false Structure that shows the physcial address of this order. The physical address is required if the order is a bird order being shipped to a PO box. The physical address is used for the NPIP VS9-3 form. If included, all of the address fields must be present.
physical_address.firstname string string false 100 First name of physical address recipient. May be blank for businesses.
physical_address.initial string string false 100 Middle name/initial of physical address recipient. May be blank for businesses.
physical_address.lastname string string true 100 Last name of physical address recipieint. May be full name of a business.
physical_address.attn string string false 200 Attention line of Physical address
physical_address.address1 string string true 100 Physical address line 1
physical_address.address2 string string false 100 Physical address line 2
physical_address.address3 string string false 100 Physical address line 3
physical_address.city string string true 100 Physical city
physical_address.state string string true 100 Physical state
physical_address.zip 5 digit US zip code zip true 50 Physical zip / postal code
physical_address.country string string true 50 Physical country
physical_address.phone1 10 digit phone number, no spaces or punctuation phone true Physical phone number 1
physical_address.phone1ext string string false 10 Physical phone number 1 (extension)
physical_address.phone1type phone_type false Physical phone number 1 (type)
home home
work work
mobile mobile
fax fax
other other
physical_address.phone2 10 digit phone number, no spaces or punctuation phone false Physical phone number 2
physical_address.phone2ext string string false 10 Physical phone number 2 (extension)
physical_address.phone2type phone_type false Physical phone number 2 (type)
home home
work work
mobile mobile
fax fax
other other
internal_note string string false 5000 Internal-only note. Customer will not see this. Partner may not see it. If specified, this note is ADDED to the order unless there is already a note with the same text (case insenstivite).
packslip_note string string false 100 Customer-visible note to print on pack slip. If specified, this completely replaces any existing pack slip note. Specify an empty note to remove the pack slip note from the order.
ship_method valid shipping method ship_method false Optional shipping method
EGGS Eggs Best Way 3 day
EXPR Express Mail
PRI Priority Mail
po_number string string false 30 Partner's purchase order number. To remove the PO number, specify a blank value.
substitutions valid substitutions value substitutions false What type of substitutions are allowed if there are not enough of a given item.
none No substitutions allowed
similar_breeds Substitute with similar breeds
from_order Substitute only from breeds in the order
vaccinate true or false bool false If client operates with order-level vaccinations, this must be a boolean indicating whether or not the order is to be vaccinated
details list hash_not_empty false List of details (line items) in the order. If deails is specified, the list must be a complete list of the items that are to remain on the order. Any items not included in this list will be removed. Quantities may be changed depending on availability.
details.skuid integer integer true SKU ID of this item (internal identifier)
details.quantity integer integer true Quantity of this item to include in the order
details.additional_info string string false 100 Optional additional information to print on the pack slip. If this field is missing or has an empty value, any existing additional_info will be removed from the order for this item.

Output Fields

Name Description
_environment Notation of the environment in which the response was generated. For internal troubleshooting.
_hostname Notation of the host on which the response was generated. For internal troubleshooting.

ship_method_get_list

Get a list of valid ship methods.

Parameters

Name Format Type List Entry Type Required Max Length Description Valid Values

Output Fields

Name Description
_environment Notation of the environment in which the response was generated. For internal troubleshooting.
_hostname Notation of the host on which the response was generated. For internal troubleshooting.
list List of all valid ship methods
list.code Ship method code to use in API function calls
list.description Description of the ship method.

sku_list

Return a list of SKUs. Only SKUs with active=true can be ordered.

Parameters

Name Format Type List Entry Type Required Max Length Description Valid Values

Output Fields

Name Description
_environment Notation of the environment in which the response was generated. For internal troubleshooting.
_hostname Notation of the host on which the response was generated. For internal troubleshooting.
skus List of items/SKUs
skus.skuid ID of this item/SKU. This is the field that is referenced by other functions.
skus.sku Alphanumeric SKU designation. This is a shorthand notation for the item and generally also indicates the breed.
skus.sex Sex of this item. M=male, F=female, S=straight run / unsexed, blank=not a sexed item (e.g. non live)
skus.name Name of this SKU/item
skus.active Is this SKU active? Only SKUs with active=true can be ordered.
skus.type Description of the type of item. May change over time.
skus.isbn ISBN of the item. Only present if applicable.
skus.upc UPC of the item. Only present if applicable.

substitutions_get_list

Get a list of valid substitutions values.

Parameters

Name Format Type List Entry Type Required Max Length Description Valid Values

Output Fields

Name Description
_environment Notation of the environment in which the response was generated. For internal troubleshooting.
_hostname Notation of the host on which the response was generated. For internal troubleshooting.
list List of all valid substitutions values
list.code Code to use in API function calls
list.description Description of the substitution value
© Copyright 2009–2023 Metzer Farms
Glossary of Terms | Metzer Farms Catalog & Newsletter | Our Privacy Policy | Contact Us | Your IP Address: 35.172.164.32 | © Copyright 2009–2023 Metzer Farms
powered by HatcheryManager.com

}