Skip to content

orders.md

Latest commit

 

History

History
315 lines (243 loc) · 7.21 KB

orders.md

File metadata and controls

315 lines (243 loc) · 7.21 KB

Fy! Marketplace API - Orders

Overview

The Fy! Marketplace API for Orders allows developers to programmatically retrieve order information.

URI scheme

  • Host: marketplace-api.iamfy.co
  • Scheme: HTTPS

Content type

  • Consumes: application/json
  • Returns: application/json

Operations

Paths

GET /v0/orders

Returns orders created between the specified from and to parameters.
Operation getOrders
Method GET
Endpoint /v0/orders

Parameters

Type Name Description Schema
Query from
required		 An ISO-8601 date from which to return orders. The from parameter is the exclusive, lower bound of the query range. Must not be in the future. string
Query to
required		 An ISO-8601 date to which to return orders. The to parameter is the inclusive, upper bound of the query range. string
Query acknowledged
optional		 Filter by acknowledged status. boolean

Responses

An example of a successful response from the getOrders operation:

{
	"data": [{
		"orderReference": "SO-1234",
		"contactDetails": {
			"phone": "+00 123456789",
			"email": "j.doe@example.com"
		},
		"address": {
			"recipient": "Jane Doe",
			"line1": "123 Main Street",
			"line2": "42nd Floor",
			"city": "London",
			"postcode": "E1 2BC",
			"state": null,
			"country": "United Kingdom",
			"company": "Acme Internet"
		},
		"orderLines": [{
			"id": 1234,
			"sku": "SKU-A",
			"quantity": 1,
			"price": {
				"wholesale": {
					"cents": 1000,
					"currency": "GBP"
				}, 
				"shipping": {
					"cents": 100,
					"currency": "GBP"
				}
			}
		}],
		"createdAt": "2021-01-01T00:00:00Z"
	}]
}
Status Description Schema
200 Success. GetOrdersResponse
400 Missing or invalid parameters. GetOrdersResponse
403 Access forbidden. GetOrdersResponse
500 Server error. GetOrdersResponse

POST /v0/orders/acknowledge

Marks orders as "acknowledged". This flag can be used to mark orders as retrieved by your system, and can be used as a filter for the getOrders endpoint.
Operation acknowledgeOrders
Method POST
Endpoint /v0/orders/acknowledge

Parameters

Type Name Description Schema
Body body
required		 The request schema for the acknowledgeOrders operation. AcknowledgeOrdersRequest

For example:

{
	"data": ["an-order-reference", "another-order-reference"]
}

Responses

Status Description
200 Success
400 Missing or invalid parameters
403 Access forbidden
500 Server error

Definitions

GetOrdersResponse

{"data": <Orders>} | <Errors>
View descriptions
Name Description Schema
payload
optional		 The payload for the getOrders operation. Orders
errors
optional		 One or more unexpected errors which occurred during the getOrders operation. -

Orders

[<Order>, ...]

An array containing one or more Order.

Order

{"orderReference" <string>
 "contactDetails" <ContactDetails>
 "address"        <Address>
 "orderLines"     <OrderLines>
 "createdAt"      <string>}
View descriptions
Name Description Schema
orderReference
required		 The reference for a specific Fy! order: an "SO-" prefix followed by a series of numbers. string
contactDetails
required		 The contact details of the recipient. ContactDetails
address
required		 The address of the recipient. Address
orderLines
required		 One or more orderlines associated with the order. OrderLines
createdAt
required		 The (ISO-8601) datetime when the order was created. string

OrderLines

[<OrderLine>, ...]

An array containing one or more OrderLine.

OrderLine

{"id"       <number>
 "sku"      <string>
 "quantity" <number>
 "price"    <Price>}
View descriptions
Name Description Schema
id
required		 The identification number of the orderline. number
sku
required		 The SKU (stock keeping unit) of the orderline item. string
quantity
required		 The quantity of items in the orderline. number
price.
required		 The price of the items in the orderline. Price

Price

{"wholesale" <Cost>
 "shipping"  <Cost>}
View descriptions
Name Description Schema
wholesale
required		 The total wholesale cost of the items in the orderline. Cost
shipping
optional		 The total pre-agreed shipping cost of the items in the orderline. Cost

Cost

{"cents"     <number> 
 "currency"  <string>}
View descriptions
Name Description Schema
cents
required		 The cost amount in the minor unit of the currency (e.g. cents, pence). number
currency
required		 The currency of the cost amount. string

ContactDetails

{"phone" <string>
 "email" <string>}
View descriptions
Name Description Schema
phone
optional		 The phone number of the recipient. string
email
optional		 The email address of the recipient. string

Address

{"recipient" <string>
 "line1"     <string>
 "line2"     <string>
 "city"      <string>
 "postcode"  <string>
 "state"     <string>
 "country"   <string>
 "company"   <string>}
View descriptions
Name Description Schema
recipient
required		 The combined first and last names of the recipient. string
line1
required		 The first line of the recipient's address. string
line2
optional		 The second line of the recipient's address. string
city
required		 The recipient's city. string
postcode
required		 The recipient's postcode. string
state
optional		 The recipient's state. string
country
required		 The recipient's country. string
company
optional		 The recipient's company. string

Acknowledge Orders Request

{"data": [<OrderReference>, ...]}
View descriptions
Name Description Schema
orderReference
optional		 The order reference to mark as acknowledged. Multiple order references can be passed as an array. string