Order

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.

address1

{"address1": "Heinrich-Hertz-Str. 2"}
address2

{"address2": ""}
city

{"city": "Dortmund"}
company

{"company": ""}
country

{"country": "Germany"}
country_name

{"country_name": "Germany"}
country_code

{"country_code": "DE"}
default

{"default": true}
first_name

{"first_name": "John"}
id

{"id": 159501}
last_name

{"last_name": "Doe"}
name

{"name": "Test"}
phone {"phone": "0231-12345678"}
province

{"province": ""}
province_code

{"province_code": ""}
token

{"token": "TCMJEOTSBEVTDLFU"}
zip

{"zip": "44227"}

 
{"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.

address1

{"address1": "Heinrich-Hertz-Str. 2"}
address2

{"address2": ""}
city

{"city": "Dortmund"}
company

{"company": ""}
country

{"country": "Germany"}
country_name

{"country_name": "Germany"}
country_code

{"country_code": "DE"}
default

{"default": true}
first_name

{"first_name": "John"}
id

{"id": 159501}
last_name

{"last_name": "Doe"}
name

{"name": "Test"}
phone {"phone": "0231-12345678"}
province

{"province": ""}
province_code

{"province_code": ""}
token

{"token": "TCMJEOTSBEVTDLFU"}
zip {"zip": "44227"} 
{"email": "sample@someone.com"}

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)

id 
"id": 578130

Unique ID for this discount code usage.
amount 
"amount": 2799 cent

The amount (in cent) represented by this discount code.
code 
"code": "MUL-KUH-PTF-CCE-YUS"

The code string used
type 
"type": "percentage"

The type of the code used. Possible values are "percentage" and "fixed_amount"
email 
{"email": "sample@someone.com"}

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": []

id

"id" : 404815

Unique ID referencing this line item
quantity

"quantity" : 1

Number of items
line item

 "line_item" : []

Complete line item information (see line_item for details)

"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.

id 
id": 120879

Unique ID to reference this payment transdaction
order_id  
"order_id": 203764

Order ID of the order to which this refund belongs
gateway  
"gateway": "TeleCash"

Name of the gateway on which the refund was performed.
created_at  
"created_at": "2016-03-02T13:01:53"

GMT date and time the refund transaction was handed over to the payment gateway.
test  
"test": false

Is set to true if this is a test transaction which does not have a real monetary effect.
status  
"status": "success"

The status of the refund transaction.
amount  
"amount": 4900

The amount of the refund in cent.
currency  
"currency": "EUR"

Tthe currency in which the refund was processed
location_id  
"location_id": null

The location from which the refund transaction was triggered in case of a physical shop. 
customer_token  
"customer_token": "TCMJEOTSBEVTDLFU"

The customer_token referencing the customer for whom the transaction was made.
device_id  
"device_id": null

A device identifier for the original order (if available)
source_name  
"source_name": "web" 

The source from which the order for the transaction originated. Can be "web" or "api".

"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
  • paid - Show only paid orders
  • refunded - Show only refunded orders
  • partially_refunded - Show only partially refunded orders
fulfillment_status
  • fulfilled - Show orders that have been shipped
  • partial - Show partially shipped orders
  • null - Show orders that have not yet been shipped
  • any - Show orders with any fulfillment_status. (default)
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.json

View Response

Get only particular fields

GET /api/orders/210797.json?fields=created_at,id,name,total_price

View 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.json

View Response

Count orders which are paid.

GET /api/orders/count.json?financial_status=paid

View Response

Retrieve a list of Orders

GET /api/orders.json?updated_at_min=2016-02-05T15:57:11

View Response

Receive a single Order

GET /api/orders/#{id}.json

View Response

Receive a count of all Orders

GET /api/orders/count.json

View 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": "steve.lastnameson@fluxdvd.com",
          "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}.json

View Response