An order is a customer's completed request to purchase one or more products from a shop. An order is created when a customer completes the checkout process, during which time s/he provides an email address, billing address and payment information. Orders can also be created manually from the FlickRocket api.
You should note that orders can be created through the API, but no payment information will be collected, and no payment transaction performed.
You should also note that you can change only a few of an order's attributes using the API. For example, you cannot change the items or the quantities in an order.
Authentication for new orders
When a new order is created, it is important that the customer can later access the order. Accessing the order is done via email and password, and so it is very important that the email and the password of the customer is correct. for referencing the customer, there are the following two methods:
Email/Password | With this method, the email and clear text password of the customer is transmitted to FlickRocket. Flickrocket does not store the password but creates and stores a secure hash derived from the password. For new customers, using this method is the only way to create an order. For existing customers, the order fails if the transmitted password does not match the password hash stored by FlickRocket. Therefore it is required to check for the existance of a customer within FlickRocket before creating initial orders for a customer. |
customer_token | With this method, a customer is referenced by a customer_token. This customer token is returned when an order is placed or as part of orders and customer objects. Threrefore it can only be stored for subsequent orders of a customer. |
Keeping credentials in sync
To make sure that acustomer can always access his order, it is essential to ensure that the customers email and password data for the application using the API interface and the FlickRocket account data ultimately granting access to the order, is always synced and up to date. Since this needs to work even between multiple shops a true two way synchonization for all email/password changes is required.
Send email/password changes to Flickrocket | Use the customer object to send updates customer data such as email and password changes. |
Receive email/password changes from Flickrocket | Configure Flickrocket's Data Change Sync (part of the API app) to send email/password changes of your cosutomers to a certain URL. |
Validate a new customer
Before you can create an initial order for a customer, you need to check if the custoemr already exists in FlickRocket and if the password matches Flickrocket's data. This is done via the customer object.
What can you do with Order?
The FlickRocket API lets you do the following with the Order resource. More detailed versions of these general actions may be available:
GET /api/orders.json?updated_at_min=2005-07-31T15:57:11
Retrieve a list of Orders
GET /api/orders/#{id}.json
Receive a single Order
GET /api/orders/count.json
Receive a count of all Orders
POST /api/orders.json
Create a new Order
PUT /api/orders/#{id}.json
Modify an existing Order
DELETE /api/orders/#{id}.json
Invalidate an Order from the database
Order Properties
browser_ip |
{"browser_ip": "188.168.1.34"}
The customer's IP address when the order was placed. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
buyer_accepts_marketing |
{"buyer_accepts_marketing": true}
Set to true if the user has consigned to accept marketing information. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelled_at |
{"cancelled_at": null}
GMT date and time when the order was canceled. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
checkout_id |
{"checkout_id": null}
The checkout ID for the order. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
checkout_token |
{"checkout_token": "d0aefc55-f63b-4482-bb10-e6caea391749"}
Unique token for the checkout process for this order. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
closed_at |
{"closed_at": "2016-04-07T16:16:17"}
GMT date and time when the order was closed. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
confirmed |
{"confirmed": true}
Set to true when the order was confirmed. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
created_at |
{"created_at": "2016-04-07T16:16:17"}
GMT date and time when to order was placed. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currency |
{"currency": "USD"}
Currency under which the order was handled. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
customer |
"customer": The customer data for this order "addresses": [] One or more addresses of the customer.
{"created_at": "2016-04-07T16:12:24"}
GMT date and time when the customer was initially created. "default_address": The default address of the user unless a different address was selected.
{"email": "This email address is being protected from spambots. You need JavaScript enabled to view it."}
The customers email address. This email address must be used by the customer to log in to the shop and players. {"first_name": "John"}
The customer's first (given) name. {id": 159501}
Unique ID for this customer. {"language": "de"}
Two byte language code. {"last_name": "Doe"}
The customer's last (family) name. {"last_order_id": 206897}
The last order_id of the customer. {"last_order_name": "#206897"}
The name of the last order. {"note": ""}
Notes about this customer. {"orders_count": 3}
The number of times the cutomer has ordered. {"password": null}
The customer's password if customer is not identified via his token. {"password_confirmation": null}
Same as password (used for confirmation). {"state": "enabled"}
The status of the order. supported values are "enabled" and "disabled". Read-only. {"token": "TCMJEOTSBEVTDLFU"}
The customer's token from this order. {"total_spent": 0.0}
The total amount the customer has spent. {"updated_at": "2016-04-07T16:12:24"}
GMT date and time of the last update to the customer information. {"verified_email": false}
Is set to true when the email has been verified. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
shipping_address |
"shipping_address": { The shipping address for this order. {"address1": "Heinrich-Hertz-Str. 2"}
{"address2": ""}
{"city": "Dortmund"}
{"company": ""}
{"country": "Germany"}
{"country_name": "Germany"} {"country_code": "DE"} {"default": true}
Is set to true if this is the defauld shipping address {"first_name": "John"}
{"id": 0}
{"last_name": "Doe"}
{"name": "John Doe"}
{"province_code": ""}
{"province": ""} {"token": ""} {"zip": "44227"} |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
device_id |
{"device_id": null}
Device identifier of the device used for the order (if available) |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
discount_codes |
"discount_codes": [] Information about the discoutn codes used for this order (if any)
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
{"email": "This email address is being protected from spambots. You need JavaScript enabled to view it."}
Identical to customer_email. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
financial_status |
{"financial_status": "paid"}
The status of the financial transaction. The possible values are: oaid, partially_refunded, refunded |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
fulfillment_status |
{"fulfillment_status": "fulfilled"}
Indicates the fullfillment status. The possible values are: fulfilled / partial / null Digtal content orders are set to "fulfilled" directly after the completion of the order. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
fulfillments |
"fulfillments": []
Information about the fulfillment of the order. {"created_at": "2016-04-14T16:10:36.0568169+02:00"} GMT date and time the order was fulfilled. "id": 11500 Unique identifier for this fulfillment "line_items": [2] An array of the line items included in this fulfillment. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
id |
{"id": 206897}
Unique identifier for this order. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
gateway |
{"gateway": "Manual"}
The payment gateway used for this order. Set to "Manual" if order was entered manually and no payment gateway was used. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
landing_site |
{"landing_site": null}
The landing page on which the user arrived in the shop before the order (if available) |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
landing_site_ref |
{"landing_site_ref": null}
The site from which the customer reached the landing page (if available) |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
line_items |
"line_items": [{ A list on information about each item in the order. {"gift_card": false}
Is set to true, if a gift certificate was used for this item. {"grams": 0.0}
The weight of the order in grams. {"hd": false"}
The resolution of the prdered video content (if applies) {"id": 410996}
Unique identification of this line item. {"license_id": 16}
The license associated to this item order. Applies to digital products only. {"license_title": "Rental (48 hours)"}
The title of the license associated to this item order. Applies to digital products only. {"name": "The Adventures of Sherlock Holmes / Rental (48 hours)"}
The name of the this order item. {"price": 0.0}
The net price of this item. {"product_exists": true}
Is set to true for existing products and fals for pre-order products. {"product_id": "0000-2E74-D5D6-3CD7"}
The product_id of this item. {"quantity": 2}
The quantity of how many of this item is ordered. {"requires_shipping": false}
Set to true if this item requires physical shipment. {"sku": ""}
Optional SKU number assigned to this item. {"taxable": false}
Set to true if this item is taxable {"title": "The Adventures of Sherlock Holmes"}
The title of the product. {"total_discount": 0.0}
The total discount applied to item. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
location_id |
{"location_id": null}
Identifies the physical store if item is sold there. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
name |
{"name": "#206897"}
Name of the order. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
order_number |
{"order_number": ""}
The invoice number of this order as shown as reference of the invoice. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
po_number |
{"po_number": "PO123456"} The PO number for this order as entered by the customer during the purchase. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
payment_gateway_names |
{"payment_gateway_names": ["Manual"]}
The name of the payment gateway used for the payment for this order. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
processed_at |
{"processed_at": "2016-04-07T16:16:17"}
GMT date and time whne the order was processed. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
referring_site |
{"referring_site": null}
URL of the refferring site (if available). |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
refunds |
"refunds": [] Information about refunded items "created_at": "2016-03-02T17:13:38" GMT date and time the item was refunded "id": 120879 Unique Id referecing this item refund "note": null Notes in regards to this item refund "order_id": 203764 Order ID of the order from which this item refund originated "refund_line_items": []
"restock": false Is set to true if the refunded item is automatically restocked in the stock management "tracking_number": null The tracking number of the refunded item's shipping (if available) "transactions": [] Information about the transaction related to this refund.
"customer_token": "TCMJEOTSBEVTDLFU" The customer_token referencing the customer for whom the transaction was made. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
shipping_lines |
"shipping_lines": [] {"price": 0} The shipping price of the shipment. {"title": "Default"} The name of the shipment method {"tax_lines": [0]} The tax information of the shipping method. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
source_name |
{"source_name": "api"}
Where the order originated. Possible values are: "api", "webshop" and "in app". |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
subtotal_price |
{"subtotal_price": 0.0}
Total net price. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
tax_lines |
"tax_lines": []
The tax information for the individual items. {"price": 3495} The net price of this item. {"rate": 0} The tax rate for this item. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
taxes_included |
{"taxes_included": false}
Is set to true, if taxes are included. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
test |
{"test": false}
Set to true is this is a test purchase without actual payment. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
theme_setting_id |
{"theme_setting_id": 232} The ThemeSetting of the theme/shop in which this order was placed. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
total_discounts |
{"total_discounts": 0.0}
The total discount amount (incl. taxes) |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
total_line_items_price |
{"total_line_items_price": 0.0}
Total price of all line items incl. taxes (no discounts). |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
total_price |
{"total_price": 0.0}
Total price gross less discounts. The actual money charged. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
total_tax |
{"total_tax": 0.0}
Totl taxes in this order. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
total_weight |
{"total_weight": 0.0}
Total weight in grams. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
updated_at |
{"updated_at": "2016-04-07T16:16:17"}
GMT date and time of the last update to the order. |
Endpoints
GET/api/orders.json
Retrieve a list of Orders
ids | A comma-separated list of order ids |
since_id | Restrict results to after the specified ID |
created_at_min | Show orders created after date (format: 2008-12-31 03:00) |
created_at_max | Show orders created before date (format: 2008-12-31 03:00) |
financial_status |
|
fulfillment_status |
|
fields | comma-separated list of fields to include in the response |
List orders last updated after 2005-07-31T15:57:11
GET /api/orders.json?updated_at_min=2005-07-31 15:57:11 EDT -04:00
List all orders, showing only some attributes
GET /api/orders.json?fields=created_at,id,name,total_price
List of specific orders
GET /api/orders.json?ids=1073459970
List all orders after the specified ID
GET /api/orders.json?since_id=123
List all orders
GET /api/orders.json
List orders which are paid.
GET /api/orders.json?financial_status=paid
GET/api/orders/450789469.json
Retrieve a specific order
fields | comma-separated list of fields to include in the response |
Get a representation of a single order
GET /api/orders/210797.jsonView Response
Get only particular fields
GET /api/orders/210797.json?fields=created_at,id,name,total_priceView Response
GET/api/orders/count.json
Retrieve a count of all the orders
created_at_min | Count orders created after date (format: 2008-12-31 03:00) |
created_at_max | Count orders created before date (format: 2008-12-31 03:00) |
financial_status | paid - Only paid orders refunded - Show only refunded orders partially refunded - Show only partially refunded orders any - All paid, refunded, and partially refunded orders (default) |
fulfillment_status | fulfilled - Orders that have been shipped partial - Partially shipped orders null - Orders that have not yet been shipped any - Orders with any fulfillment_status. (default) |
Count all orders
GET /api/orders/count.jsonView Response
Count orders which are paid.
GET /api/orders/count.json?financial_status=paidView Response
Retrieve a list of Orders
GET /api/orders.json?updated_at_min=2016-02-05T15:57:11View Response
Receive a single Order
GET /api/orders/#{id}.jsonView Response
Receive a count of all Orders
GET /api/orders/count.jsonView Response
Create a new Order for an existing customer
POST /api/orders.json { "order": { "line_items": [{ "product_id": "0000-18E6-6DFE-B051", "license_id": 19, "quantity": 1, "hd": false }, { "product_id": "0000-B4CB-BC42-08CE", "license_id": 16, "quantity": 2, "hd": false }], "customer": { "token": "PWWTGAUVXXBFFSEN" } } }View Response
Create a new Order together with a new customer
POST /api/orders.json
{
"order": {
"line_items": [{
"product_id": "0000-18E6-6DFE-B051",
"license_id": 19,
"quantity": 1,
"hd": false
}, {
"product_id": "0000-B4CB-BC42-08CE",
"license_id": 16,
"quantity": 2,
"hd": false
}],
"customer": {
"first_name": "Steve",
"last_name": "Lastnameson",
"email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
"addresses": [{
"address1": "123 Oak St",
"city": "Ottawa",
"province": "ON",
"phone": "555-1212",
"zip": "123 ABC",
"last_name": "Lastnameson",
"first_name": "Mother",
"country": "CA"
}],
"password": "newpass",
"password_confirmation": "newpass"
}
}
}
View Response
Modify an existing Order
PUT /api/orders/#{id}.json { "order": { "confirmed": false, "buyer_accepts_marketing": false } }View Response
Invalidate an Order from the database
DELETE /api/orders/#{id}.jsonView Response