FSN JSON API Documentation

Change Log:

About the API

The FSN JSON API communicates using HTTPS requests to FSN. The request format is application/x-www-form-urlencoded name-value pairs. JSON is also supported as a request format. The response format is JSON.

Authentication is performed via the __token parameter, which is present on every API function. The token identifies the API client and its permissions as well as the software used by the client. For example, the token will identify a florist and his point-of-sale system software used to access the API.

This API is intended to be extensible. All functions, parameters, and response values are to be supported as specified for the foreseeable future. New functions may be added at any time. New optional parameters may be added any time. New properties of response objects should be allowed at any time. Please implement this in such way that your software will ignore any unexpected response properties.

If it becomes necessary to remove a function, add a new required parameter, or remove a response property, we will contact you and work with you to make sure this is done in a way that causes no interruptions to your clients. We will avoid this if at all possible. Rather that adding a new required parameter, we would likely create a redundant function supported in parallel to an old function until the old function can be safely removed.

The API URL

The API URL is an HTTPS url, with a domain name that points to the FSN Dev or Live system, followed by a path that identifies the API function, beginning with /api/

Live API requests begin with:

https://api.flowershopnetwork.com/api/

Development API requests begin with

https://dev-api.flowershopnetwork.com/api/

Please coordinate with an FSN tech specialist to perform development testing to ensure Dev API access and to validate data.

The end of the URL idenfies the function. For example, this is the URL for the Florist Search function

https://api.flowershopnetwork.com/api/RelayUtil.apiSearchFlorists

The Request Format

Request parameters are formatted in name-value pairs in application/x-www-form-urlencoded format, the same way a web browser formats the data of from a <form method="POST" ...> element. A raw HTTPS requeest migt look like this:

POST /api/RelayOrder.apiGetOrder
Host: api.flowershopnetwork.com
User-Agent: My POS System
Content-Type: application/x-www-from-urlencoded; charset=UTF-8

__token=mylongapitokenstring&orderId=123456789

Values are URL-encoded, such as replacing " characters with %22. Your programming language of choice should have a function available for URL encoding. PHP using the "urlencode" function. Microsoft's .NET framework provides the "Uri.EscapeDataString" method.

Request parameters names may contain [ and ] characters, and these must be escaped as %5B and %5D respectively, for example:

taxes%5B0%5D%5Blabel%5D=State%20sales%20tax

The Response Format

Responses are JSON formatted. For example, the response body of a florist search might look like this:

{ "searchResult": [ { "id": "1234567890", "name": "Bob's Florist", "contact": "Bob Johnson", "address": "123 Main St.", "city": "Beverly Hills", "state": "CA", "zip": "90210", "preferred": true, "blacklisted: false } ] }

Per the JSON standard, all property names are " delimited, strings are also " delimited, and special characters in strings are escaped with \, such as this product description from a website product.

{ "product": { "id": "va6809", "recipe": "6 1\/4\" ginger vase\r\nfoliage: variegated pittosporum\r\n2 stems yellow Asiatic lilies\r\n4 orange 'Cherry Brandy' roses\r\n3 yellow snapdragons\r\n3 stems solidago\r\n3 fuchsia gerberas\r\n7 orange bi-colored tulips", "name": "SUN-DRENCHED COLOR Arrangement", "description": "SEND SUMMER'S COLOR-IFIC BLOOMS FROM BOB'S FLOWERS & GIFTS! Bursting with vibrant summer flowers, our Sun-Drenched Color Bouquet is a beautiful way to say Thank You... Happy Birthday... Congrats... or Thinking of You. Call direct or order summer flowers right now from our website!", "imageUrl": "https://cdn.atwilltech.com/flowerdatabase/v/VA6809LG.jpg", "prices": { "1": "80", "2": "90", "3": "100" } } }

Most programming languages should have a core utility for parsing JSON strings into structures objects or hashes. PHP using the json_decode function. Microsoft's .NET framework uses the System.Web.Script.Serialization.JavaScriptSerializer class.

Exception Responses

Errors, such as bad tokens or invalid requests, will return exceptions. Exceptions will be returned as a JSON-formatted object with a property of "exception". The "exception" has a property of "message", and possibly an array of "errors"

For example:

{ "exception": { "message": "Invalid API token" } }

Or, another example:

{ "exception": { "message": "A required field was missing", "errors": [ "Recipient first name is required" ] } }

Function list

Please note that all functions have __token as a required parameter. An invalid token will always return an exception.

Each function begins with a Capital letter and contains a "."

Also note that the function name may itself contain a "/" character.

API/ForeignSystem.apiGetPosToken

This function is the only function you will call that does not require a token. The purpose of this function is to generate a token for a shop based on their Flower Shop Network username and password. You will need to call this function during your program set up with the florist's username and password to generate your token one time. After that, you will no longer need the florist's username and password. Alternatively, FSN may provide a token for you.

Note that the URL for this function may look a little unusual since API is part of the base URL and also the beginning of the function name.

https://api.flowershopnetwork.com/api/API/ForeignSystem.apiGetPosToken

Request

username
The florist's fsnf2f.com username
password
The florist's fsnf2f.com password

Example:

username=1234567890&password=myfsnf2fpassword

Response

token
The token string you need to permanently and securely store in your system for all other requests

Example

{ "token": "123412341234123412341234123412341234123412341234-MYFLORIST" }

API/Token.apiCheck

This function checks the validity of the token. An invalid token returns an exception.

Note that the URL for this function may look a little unusual since API is part of the base URL and also the beginning of the function name.

https://api.flowershopnetwork.com/api/API/Token.apiCheck

Request

__token
Your valid API token string

Response

active
true (boolean)

MyfsnProduct.apiLoadProductData

This function looks up a product for the florist's website by the product id and returns information about that product.

Request

__token
Your valid API token string
productId
The ID of the product. This ID can be found on incoming orders if the orders from the florist's website.

Example:

__token=mytokenstring&productId=va6809

Response

product
An object containing information about the product, or null if the product cannot be found
id
(string) The product id
recipe
(string) A plain text description of the arrangement recipe that may contain line breaks and carriage returns
name
(string) The product name
description
(string) Product description as it appears on the florist's FSN website.
imageUrl
(string) A live URL pointing to the image of the product. You may use your software to download this image and display it inside your system for the florist to see when filling an order
prices
(object) The prices, up to 3, shown on the florist's website at which this product is listed
1
(string) Price 1
2
(string, optional) Price 2
3
(string, optional) Price 3

Example:

{ "product": { "id": "va6809", "recipe": "6 1\/4\" ginger vase\r\nfoliage: variegated pittosporum\r\n2 stems yellow Asiatic lilies\r\n4 orange 'Cherry Brandy' roses\r\n3 yellow snapdragons\r\n3 stems solidago\r\n3 fuchsia gerberas\r\n7 orange bi-colored tulips", "name": "SUN-DRENCHED COLOR Arrangement", "description": "SEND SUMMER'S COLOR-IFIC BLOOMS FROM BOB'S FLOWERS & GIFTS! Bursting with vibrant summer flowers, our Sun-Drenched Color Bouquet is a beautiful way to say Thank You... Happy Birthday... Congrats... or Thinking of You. Call direct or order summer flowers right now from our website!", "imageUrl": "https://cdn.atwilltech.com/flowerdatabase/v/VA6809LG.jpg", "prices": { "1": "80", "2": "90", "3": "100" } } }

Exception message:

"Invalid product id"
The given id is not an active product on the florist's website

RelayUtil.apiSearchFlorists

Search the Flower Shop Network directory of florists for a potential filler for an order. Please provide city, state, and zip if possible for best results, but zip can be omitted if city and state are provided, and city and state can be omitted if zip is provided

Request

__token
(string) Your API token
city
(string)
state
(string) Two-character postal abbreviation
zip
(string) 5-character US zip codes are supported. The first three characters, such as "A0A", of Canadian postal code is supported.
orderAmount
(float, optional) The value of the order to be placed with this filling florist. This parameter excludes florists from search results if they do not meet this minimum value.

Response

searchResult
(array) An array, possibly empty, of search result objects in this format
id
(int) The FSN id number of the filling florist. This value can be used as the filling florist when sending an order
phoneNumber
(string) The 10 digit phone number of the florist
name
(string) The florist's name
contact
(string) The florist's contact person
address
(string) Street address
city
(string)
state
(string) Two-character postal abbreviation
zip
(string) 5 character US zip code, or 6 character Canadian postal code
preferred
(boolean) Whether this florist is flagged by the API client as a preferred florist
blocked
(boolean) Whether this florist is flagged by the API client as blocked. The API client has previously decided not to send to this florist. You may want to omit this florist from results presented to the client. This result should always be at the end.

RelayOrder.apiGetOrder

Get the details of an individual order, either sent or received. Note that there are certain fields present only when an order is a web order, or when an order is sent, or when it is received.

Request

__token
(string) Your API token
orderId
(string) The order id to look up. Only the numeric order id is needed, such as "1234567"

Response

order
(object)
id
(string) the numeric FSN order id
type
(string) The order type. F = Florist to Florist, R = FSN Relay order, W = Consumer web order
status
(string) The order status. One of "Pending", "Processing", "Cancelled", "Problem", or "Complete"
orderValue
(string) The total value of the order formatted to 2 decimal places. This is intended to be the fill value of the order and not the pay out. For example, an 80/20 florist-to-florist order may be for a $100 arrangement where the pay out is $80. This includes delivery
currency
(string) The currency for this total amount, such as USD or CAD.
charge
(string, only present on an order sent) The amount FSN will charge the sender, formatted to 2 decimal places
payOut
(string, only present on an order received) The amount FSN will pay out to the filler, formatted to 2 decimal places
orderSplit
(string) Numeric value representing the percentage of the total order value split between the filling florist and the sending florist. i.e. an 80 represents that the filling florist would receive 80% of the total order as pay out
sender
(object) Information about the sending florist. On a consumer order, this will not be set.
id
(int) The FSN id number of the sending florist
phoneNumber
(string) The phone number of the sender
name
(string)
address
(string) Street address
city
(string)
state
(string) 2-character state/province abbrevation
zip
(string) Sender postal code
email
(string, option) The sending shop's email, if available
consumer
(object) Information about the consumer. This is only set on FSN website consumer orders, and if this is set, then sender will not be set.
name
(string)
address
(string) Street address
city
(string)
state
(string) 2-character state/province abbrevation
zip
(string) Consumer postal code
email
(string) The email address provided by the consumer at checkout
phone
(string) The phone number provided by the consumer at checkout
dayPhone
(string) An alternate phone number provided by the consumer at checkout
recipient
firstName
(string)
lastName
(string)
attention
An attention line, or "in care of" line, for the recipient
address
(string) Street address
city
(string)
state
(string) 2-character state/province abbrevation
zip
(string) Sender postal code
phone
(string) 10-digit contact phone number for recipient
email
(string, optional) The recipient email address, if available
products
(array) An array of objects describing the arrangement and any addons, such as chocolates or balloons
name
(string) The short name of the product. This may be blank for the floral arrangement. Example: "Balloons"
description
(string) The description of the product, such as a detailed description of the arrangement or the addon. Example: "One dozen red roses in a square vase", or "2 Mylar"
price
(string) The price of the product formatted to two decimal placed. This is the advertised price of the product, and does not reflect any applied discounts
fsnProductData
(object, optional) If this is an FSN website product, this is the full detail of the product on the florist's FSN website as returned by the MyfsnProduct.apiLoadProductData function. This will contain more information, such as a URL to the web site image of the product, up to three advertised price points for the product, and a detailed floral recipe.
cardMessage
(string) Card message. May contain line breaks and special characters
deliveryCharge
(string, only present if set) Primarily applies to consumer web orders. Formatted to 2 decimal places
taxes
(array) An array of these objects:
label
(string) Descriptor of the tax
amount
(string) Tax amount shown to consumer
discount
(object) An object that describes the discount applied at checkout, such as a coupon code used by a consumer on the florist's FSN website. This is meant to be informational and help the florist recognize a difference between the fill value of the arrangement and the actual price. For example, the price of an arrangement may be $90.00, but after a 50% discount, added taxes and delivery, the pay out to the florist may be $61.13.
type
(string) Either "flat", indicating a flat amount discount, or "percentage" for a percentage of the product value
value
(string) The value of the discount, such as 50 for 50%, or 5.00 for a $5 discount
amount
(string) The discount amount formatted to two decimal places. If "type" is "flat" then "value" and "amount" will be the same amount.
addInfo
(string) Additional instructions for filling the order
occasion
(string) Order occasion, such as "Funeral", "Birthday"
datePlaced
(string) Date of the order in YYYY-MM-DD format
dateCompleted
(string, or null) Date the order was marked completed in YYYY-MM-DD format
dateDelivery
(string) Delivery date in YYYY-MM-DD format
filler
(object) If set, the phone number and name of the filling florist
local
(string) Local phone number of the filling florist
contact
(string) Contact name of the filling florist
creditCard
(object, optional) This is only included on web orders where the credit card charge was NOT captured by the FSN website, due to the users options. This only affects Canadian website users. If this is omitted, then it is assumed that FSN captured the payment and will pay the florist for the order. If this is included, it is assumed that the florist is responsible for charging the consumer for the order.
ccType
(string) Credit card type, such as "Visa"
ccNumber
(string) Credit card number
ccExpDate
(string) Credit card expiration date in MM-YYYY format, such as "06-2013"
billingName
(string) Cardholder's name
billingAddress
(string) Cardholder's street address
billingCity
(string) Cardholder's city
billingState
(string) Cardholder's 2-letter state abbreviation
billingZip
(string) Cardholder's zip code
billingPhone
(string) Cardholder's phone number, may be null or omitted, formatted as 10-digit phone number only digit characters
vCode
(string) The CVV2 code or "vCode" provided at checkout. This field is only available for about 48 hours after the order is placed. After that, this field will be null or omitted
resendMessage
(string, only present if set by calling RelayOrder.apiReceiveOrders) A message may entered if this the second time an order was placed in the queue. This message may be in response to the reason an order was previously rejected, such as fill value or product details
contactMessage
(string, only set by calling RelayOrder.apiReceiveOrders) A message containing information to contact Flower Shop Network

RelayOrder.apiReceiveOrders

Get any incoming orders waiting to be accepted or refused

Request

__token
(string) Your API token

Response

orders
(array) An array, possibly empty, of incoming orders. Each item in the array is in the same format as the RelayOrder.apiGetOrder function, except the resendMessage and contactMessage fields may be added

RelayOrder.apiAcceptOrder

Accept an incoming order. An exception will be thrown if the order id is not in the incoming queue.

Request

__token
(string) Your API token
orderId
(string) The numeric order id
acceptName
(string) The name of the person accepting this order. This is required and will throw an exception if it is missing

Response

orderId
(string) The numeric order id

RelayOrder.apiRefuseOrder

Refuse an incoming order. An exception will be thrown if the order id is not in the incoming queue.

Request

__token
(string) Your API token
orderId
(string) The numeric order id
refuseName
(string) The name of the person refusing the order. This is required and will throw an exception if it is missing
refuseReason
(string) The reason the order is being refused. This is required and will throw an exception if it is missing

Response

orderId
(string) The numeric order id

RelayOrder.apiSendOrder

Send a florist-to-florist order. If a required field is omitted or if a field is incorrect an exception will be returned with specific error messages. The totalOrderValue must match the product price(s) plus taxes.

Request

__token
(string) Your API token
sendingFloristContact
(string) The name of the person entering the order
deliveryDate
(string) The delivery date in YYYY-MM-DD format
recipientFirstName
(string)
recipientLastName
(string)
deliveryAddress1
(string) Street address of recipient
deliveryCity
(string)
deliveryState
(string) 2-character state abbreviation of the recipient's US state or Canadian province. For orders outside the US and Canada, use the special value "IT"
deliveryCountry
(string) Only include this field if the country is outside the US and Canada. Name of the country. If this is set, the order will be charged an international order fee.
deliveryZipCode
(string) The postal code of the recipient
attention
(string) An attention line, or in care of line, for the recipient
recipientPhone
(string) 10-digit phone number for recipient
deliverySpecialInstruction
(string) Special delivery instructions, such as "Leave with neighbor"
cardMessage
(string) Recipient card message
totalOrderValue
(string) Total order value formatted to 2 decimal places
priority
(string) A short string about the priority of the order, such as "Funeral at 4pm"
occasionCode
(int) An integer corresponding to an enumerator of occasion codes described below
receivingFloristId
(string, optional) An id number for the intended filling florist. The id number can be obtained from the RelayUtil.apiSearchFlorists. Allows for a special 10-digit number of all zeros (0000000000), which will enable FSN to attempt to automatically find a filling florist.
taxes
The following fields describe sales taxes added to an orders. Taxes are only allowed on orders where the recipient is in Canada. HST and GST are only allowed on orders where the recipient is Canadian. PST and QST are only allowed on orders sent by a Canadian florist to a Canadian recipient. Tax information is optional. If provided, taxes plus the product prices should equal the totalOrderValue. It will not affect the productTotalOrderValue field or the amount the sending florist is charged for the order.
taxes[0][label]
(string, optional) The label of the first tax amount on the order. Taxes are optional, but this field must be included for the tax to be respectred. Allowed values are "GST", "HST", "PST", and "QST"
taxes[0][amount]
(string, optional) The amount of the tax formatted to two decimal places, required if the tax label is provided.
taxes[1][label]
(string, optional) The label of the second tax amount on the order. Allowed values are "GST", "HST", "PST", and "QST"
taxes[1][amount]
(string, optional) The amount of the second tax formatted to two decimal places, required if the tax label is provided. Please note that only two tax taxes are supported at this time.
products
The following fields describe an array of products, usually describing the floral arrangement and additional optional addons. The first product is required. Every product with a price must include a description.
products[0][name]
(null or string, optional) You may omit this or leave it blank. The first product is the primary floral arrangement.
products[0][description]
(string, required) Description of the floral arrangement (required)
products[0][price]
(string, required) Advertised price of the floral arrangement, formatted to two decimal places, such as "60.00"
products[n][name]
(string, optional) Name of the next addon product, such as "Balloons" or "Chocolates" (optional)
products[n][description]
(string, required) Description of the next addon product, such as "2 Mylar" or "1 Box Assorted".
products[n][price]
(string, optional) Advertised price of the next addon product, formatted to two decimal places, such as "10.00"

Response

id
(string) The numeric order id
order
(object) The complete order information in the same format as the response from RelayOrder.apiGetOrder

RelayOrder.apiConfirmDelivery

Confirm an order was delivered.

Request

__token
(string) Your API token
orderId
(string) The numeric order id
signature
(string, optional) Who accepted the flowers?
send_email
(string) Whether to send a confirmation email. 1 = true, 0 = false
deliveryDate
(string, optional) "YYYYMMDD" or blank will default to today's date.
startTime
(string, optional) "HHMM" (eg, "16:30" military time = 4:30pm) Time arrangement was delivered, or blank will default to the current time.
endTime
(string, optional) "HHMM" (eg, "1615" military time = 4:15pm) Leave blank, unless you want to enter a time range for delivery.
comment
(string, optional) Comment about the delivery. ** This will not be seen by the sending shop **
commentToFlorist
(string, optional) Comment to the sending florist, which will be on the email sent.

Response

(array) ["Deliver Confirmed"]

Example:

["Deliver Confirmed"]

RelayOrder.apiGetDeliveryConfirmation

Retrieve the delivery confirmation information provided by filling florist.

Request

__token
(string) Your API token
orderId
(string) The numeric order id

Response

A response will be provided if the order has been confirmed, otherwise an exception message will be provided.

orderId
(string) The numeric order id
status
(string) two possible values: delivered or unconfirmed
deliveryTime
(string) Date and time of delivery in the following format yyyy-mm-dd hh:mm:ss (central/Chicago time)
confirmationTime
(string) Date and time the delivery confirmation occurred in our system in the following format yyyy-mm-dd hh:mm:ss (central/Chicago time)
signature
(string, optional) information provided by filling florist
floristMessage
(string, optional) message from filling florist
imageUrl
(string, optional) url of image filling florist uploaded as confirmation
imageThumbnailUrl
(string, optional) url of thumbnail created from filling florist's uploaded image

Occasion code list

This is the list of occasion codes to use when sending an order

1 Other
2 Anniversary
3 Birthday
4 Hospital
5 Funeral