Order and Fulfillment Inbound API (V1)

Owned by Sharath Chandra Parashara
Last updated: Aug 15, 2023
14 min read

Below are the headers required to trigger Fenix’s Order and Fulfillment API

Header Name

Description

Header Name

Description

store_name

Name of the retailer’s store (Shopify, BigCommerce, Enterprise, etc…) which configured in the Fenix System to enable fenix post purchase experience.

Note: Fenix Team provides it as part of intial Inbound Integration discussion.

x-api-key

Note: Fenix Team provides it as part of intial Inbound Integration discussion. And, it gets rotated every 6 months.

authToken

To authenticate the external system(_3PLs, Enterprise, etc…) which triggers the Fenix Inbound APIs

Note1: To get the authToken, external systems must trigger Authentication API using user_name and password provided by the Fenix Team. Collect authToken from API response payload, then use it in further order & fulfillment APIs.

Note2: External systems must refresh the authToken every 4 hours (UTC) as it get expired every 4 hours in the Fenix.

x-identity

To authorise the external system (_3PLs, Enterprise, etc…) to pump above mentioned retailer’s (Shopify, BigCommerce, Enterprise, etc…) orders and fulfillments into the Fenix system.

Note: It available as part of the Authention API response payload. And, it gets rotated every 3 months.

content-type

Request Payload(order & fulfillment) format.

Note: Fenix supported type application/json

username & password

These are used to get authToken & x-identity from Authentication API.

Note: These are belongs to external systems (_3PLs, Enterprise, etc…) which pumps retailer’s (Shopify, BigCommerce, Enterprise, etc…) order & fulfillment data into the Fenix.

Note: Fenix Team provides them as part of intial Inbound Integration discussion.

Authentication API

Resource Name

Authentication:

Authenticate external system against the Fenix Inbound data pipeline.

URL

/login

Method

POST

Headers

  • username

  • password

  • x-api-key

Response Body

{ "id": "", "firstName": "fenixname", "lastName": "Dev", "phone": null, "emailId": "fenixname", "type": "business_user", "status": "ACTIVE", "organizationId": "", "authToken": "MWI2MjcwMTMwhZjQzZDJkMmNmNTI", "x-identity": "dd77ab3404b93ecebnbhbhbdc04c87fda804c" }

Order Create/Update API

Resource Name

Rest Endpoint to send the order data information Fenix

Resource URL

/api/v1/orders/{order_id}/created

Method

POST

Headers

  • store_name

  • authToken

  • x-api-key

  • x-identity

  • content-type

Request Payload

{ "id": "18879048253891", "number": "#859731", "status": "NA", "fulfillment_status": "PARTIALLY_FILLED", "item_quantity": 2, "total_weight": { "value": 18, "units": "oz" }, "shipping_info": { "code": "FEDEX_2_DAY", "title": "Express (Est Delivery by Wednesday, Dec 4 , 2019)", "price": { "value": 14.99, "currency": "USD" }, "discount": { "value": 0, "currency": "USD" }, "source": "Fennix Commerce" }, "promised_delivery_date": "2020-01-27T00:00:00-05:00", "updated_at": "2020-01-23T10:14:15-05:00", "created_at": "2020-01-23T10:14:15-05:00", "cancelled_at": null, "cancel_reason": null, "closed_at": null, "currency": "USD", "shipping_address": { "first_name": "Srinivas", "last_name": "Aluri", "company": null, "address1": "1345 Serenity Street", "address2": "", "country": "United States", "country_code": "US", "province": "North Carolina", "province_code": "NC", "city": "Huntersville", "zip": "28078", "latitude": "35.4234431", "longitude": "-80.85062322" }, "billing_address": { "first_name": "Srinivas", "last_name": "Aluri", "company": null, "address1": "1345 Serenity Street", "address2": "", "country": "United States", "country_code": "US", "province": "North Carolina", "province_code": "NC", "city": "Huntersville", "zip": "28078", "latitude": "35.4234431", "longitude": "-80.85062322" }, "line_items": [ { "sku": "CAAD Optimo 3", "quantity": 1, "title": "Standard (Est Delivery by Monday, Dec 16)", "product_id": "43515734262211", "product_name": "CAAD Optimo", "variant_id": "43515734262211", "variant_name": "fenixcommerce", "vendor": "fenixcommerce", "taxable": true, "gift_card": false, "weight": { "value": 0, "units": "oz" }, "dimensions": { "length": 8, "width": 6, "height": 5, "girth": 3, "thickness": 0, "units": "IN" }, "price": { "value": 15, "currency": "USD" }, "image_url": "", "properties": [ { "name": "Property Name", "value": "Property Value" } ] } ], "financial_details": { "subtotal_price": { "value": 145, "currency": "USD" }, "total_tax": { "value": null, "currency": "USD" }, "total_discounts": { "value": null, "currency": "USD" }, "total_price": { "value": 159.99, "currency": "USD" }, "taxes_included": false, "financial_status": "paid", "gateway": "shopify_payments" }, "customer": { "first_name": "John", "last_name": "Corner", "email": "john1234@gmail.com", "phone": 9999000000, "tags": "", "address": { "province_code": "SC", "cou ntry_code": "US", "country_name": "United States", "zip": "29572", "address1": "704 40th St S", "address2": "", "city": "North Myrtle Beach", "province": "South Carolina", "country": "United States" } }, "checkout_token": "3513625886", "properties": [ { "name": "Property Name", "value": "Property Value" } ] }

Response Payload

NA

Response Status

201 - Success

400 – Failure

401 - Un-Authentication

Note: Date and time must be associated with zone (e.g., 2020-01-23T10:14:15-05:00)

Note1: Once data is successfully inserted into the Fenix system Post Purchase Data Pipeline, retailer can see the same data in Insights, summary & details screens. And, then Fenix will use the same data to enable complete Fenix Post Purchase Experiences to the retailers and as well as their Shoppers.

Note2: User can easily navigate from Insights to Summary screen by clicking on any part the KPIs(bar, pie, line , etc… charts).

Note3: User can easily navigate from Summary to Details screen by clicking on order number.

Order Cancelled API:

Ordered Item(s): Quantity

SKU1:3

Cancelled Item(s): Quantity

SKU1:3

Status

CANCELLED

Resource Name

Rest Endpoint to send the order data information Fenix

Resource URL

/api/v1/orders/{order_id}/created

Method

POST

Headers

  • store_name

  • authToken

  • x-api-key

  • x-identity

  • content-type

Request Payload

{ "id": "18879048253891", "status": "CANCELLED", "cancelled_at": "2020-01-23T10:14:15-05:00", "cancel_reason": "No longer need these items" }

Response Payload

NA

Response Status

201 - Success

400 – Failure

401 - Un-Authentication

 

Order Partially Cancelled API:

Usecase1: 

Ordered Item(s): Quantity

SKU1:3

Cancelled Item(s): Quantity

SKU1:1

Status

PARTIALLY_CANCELLED

Usecase2:

Ordered Item(s): Quantity

SKU1:3, SKU2:2, SKU3:1

Cancelled Item(s): Quantity

SKU1:1, SKU2:2

Status

PARTIALLY_CANCELLED

Resource Name

Rest Endpoint to send the order data information Fenix

Resource URL

/api/v1/orders/{order_id}/created

Method

POST

Headers

  • store_name

  • authToken

  • x-api-key

  • x-identity

  • content-type

Request Payload

Response Payload

NA

Response Status

201 - Success

400 – Failure

401 - Un-Authentication

Fulfillment API

Resource Name

Rest Endpoint to send the fulfilment data Information Fenix

Resource URL

/api/v1/order/{order_id}/fulfillment/{fulfillment_id}/created

Method

POST

Headers

  • store_name

  • authToken

  • x-api-key

  • x-identity

  • content-type

Request Payload

Response Payload

NA

Response Status

201 - Success

400 – Failure

401 - Un-Authentication

 Note: Date and time must be associated with zone (e.g., 2020-01-23T10:14:15-05:00)

Order API Request Payload Data Model:

Attribute Name

Data Type

Description

id (*)

String

A unique identifier in the entire data model which represent the order.

number

String

In SAAS based platforms order number would be unique idenfier as per merchants preferences.

Note: If it is blank, we consider order id as number

status (*)

String

Order Status

  • OPEN

  • CANCELLED (Complete order cancelled)

  • PARTIALLY_CANCELLED (Some of the items are cancelled)

fulfillment_status

String

The order's status in terms of fulfilled line items.

  • NOT_FILLED

  • PARTIALLY_FILLED (Some of items are shipped)

  • FULFILLED (All items are shipped)

Note: If it is blnk, we calculate based on the no of shipments and items

item_quantity (*)

String(integer)

Total no of items in the order

total_weight.value (*)

Integer

Total weight of the order

total_weight.units (*)

String

Units for the order weight (oz,grms)

shipping_info.title (*)

String

Shipping option selected by the shoppers in checkout.

shipping_info.code

String

Shipping service Name

shipping_info.price.value (*)

Integer

Shipcost paid by the customer.

shipping_info.price.currency

String

Currency (default: USD)

shipping_info.discount.value

Integer

Shipcost discount

shipping_info.discount.currency

String

Currency (default: USD)

shipping_info.source (*)

String

Source of shipping info

  • Fenix Commerce

  • Shopify

  • Other Shipping Providers

promised_delivery_date

String (offset datetime)

Promised delivery date on checkout page ("2020-01-27T00:00:00-05:00")


Note: It would be helpful to send delivery delay notifications based on what date shoppers saw in checkout page

created_at

String (offset datetime)

Order created dateTime ("2020-01-22T00:00:00-05:00")

updated_at

String (offset datetime)

Order updated dateTime ("2020-01-23T00:00:00-05:00")

cancelled_at

String (offset datetime)

Order Canclled dateTime ("2020-01-24T00:00:00-05:00")

cancel_reason

String

Cancelled reason

currency

String

Currency (default: USD)

shipping_address (*)

Object

Address to where items should be delivered

shipping_address.first_name

String

The first name of the person associated with the shipping address

shipping_address.last_name

String

The last name of the person associated with the shipping address

shipping_address.address1

String

The street address of the shipping address.

shipping_address.address1

String

optional additional field for the street address

shipping_address.city

String

The city, town, or village of the shipping address

shipping_address.company

String

The company of the person associated with the shipping address. optional

shipping_address.country

String

CountryName

shipping_address.zip

String

zipcode

shipping_address.latitude

String

Optional

shipping_address.longitude

String

Optional

line_items (*)

List

A list of line item objects, each containing information about an item in the order

line_item.sku (*)

String

The item's SKU

line_item.quantity (*)

Integer

Item quantity

line_item.title (*)

String

The title of the product.
Note: If SKU is empty, trcaking page use this title to display product info.

line_item.variant_id

String

The ID of the product variant.

line_item.variant_title

String

The title of the product variant.

line_item.vendor

String

The name of the item's supplier

line_item.name

 

The name of the product variant

line_item.gift_card

boolean

Whether the item is a gift card. If true, then the item is not taxed or considered for shipping charges

line_item.taxable

boolean

Whether the item is taxable or not.

line_item.weight.value

integer

weight of the particular item

line_item.weight.unit

String

oz/grms

line_item.dimensions

 

 

line_items.dimensions.length

integer

Length of the item

line_items.dimensions.width

integer

Width of the item

line_items.dimensions.height

integer

Height of the item.

line_items.dimensions.grith

integer

Grith of the item.

line_items.dimensions.thickness

integer

Thickness of the item.

line_items.dimensions.units

String

No. of units

price.value (*)

Integer

Price of the item

price.currency (*)

String

Currency (default: USD)

line_items.image_url (*)

String

Image Url.
Note: Fenix displays item images on the Tracking Page.

line_items.routing_url

String

URL where it route to the website product details page.

Note1: Route to website product details page when anyone clicked on images displayed on tracking page.

Note2: If it is null, there won’t be a route to websites PDP.

properties

ARRAY

An array to pass additional information about line item

properties.name

String

Name of the property

properties.value

String

Value of the property

financial_details.subtotal_price.value

Integer

The price of the order in the shop currency after discounts but before shipping, duties, taxes, and tips

financial_details.subtotal_price.currency

 

Currency (default: USD)

financial_details.total_tax

integer

The sum of all the taxes applied to the order in the shop currency. Must be positive.

financial_details.total_discounts

integer

The total discounts applied to the price of the order in the shop currency.

financial_details.total_price

integer

The total prices for that item

financial_details.taxes_included

boolean

wether taxes included or not

financial_details.financial_status

String

paid/notpaid

financial_details.gateway

String

payment gateway name.

 

 

 

customer (*)

Object

Customer details who placed an order.

Note: Fenix use this to send delivery status notifications via Email or SMS.

customer.first_name

String

customers firstname

customer.last_name

String

customers lastname

customer.email (*)

String

customers email

customer.phone (*)

String

customers.phone

customer.tags

String

customer tags

customer.address

String

 

customer.address.province_code

String

Province code of the customer address

customer.address.country_code

String

country code of customer address

customer.address.country_name

String

country name of customer address

customer.address.zip

String

zipcode of customer address

customer.address.address1

String

address1 of customer

customer.address.address2

String

Optional

customer.address.city

String

customer's city

customer.address.province

String

customer's province

customer.address.country

String

cusomers countryname

checkout_token

String

A unique value which refers the checkout page that associated with the order.

properties

ARRAY

An array to pass additional information about an order.

properties.name

String

Name of the property

properties.value

String

Value of the property

Fulfillment API Request Payload Data Model:

id (*)

String

A unique identifier in the entire data model which represent the fulfillment.

order_id (*)

String

Order Id

shipment_status

String

Current Shipment Status

  • READY_TO_SHIP

  • PICKED_BY_CARRIER

  • SHIPMENT_EXCEPTION

  • SHIPMENT_STALLED

  • OUT_FOR_DELIVERED

  • DELIVERY_EXCEPTION

  • RETURN_TO_SENDER

  • RETURNED_TO_SENDER

  • DELIVERED

Note: Fenix will update the status based on trackhistory event from carrier.

shipment_info (*)

Object

Shipment details through which packages has beed shipped.

shipment_info.tracking_number (*)

String

Tracking Number which is used to track the shipment track history

shipment_info.tracking_company (*)

String

Carrier name through which package shipped

shipment_info.shipping_service (*)

Integer

Carrie Service thugh which package shipped

shipment_info.shipcost.currency

String

Currency (default: USD)

shipment_info.shipcost.value (*)

Integer

Shipcost paid by the retailer to the carrier.

created_at

String (offset datetime)

Order created dateTime ("2020-01-22T00:00:00-05:00")

updated_at

String (offset datetime)

Order updated dateTime ("2020-01-23T00:00:00-05:00")

line_items (*)

List

A list of line item objects, each containing information about an item in the order

line_item.sku (*)

String

The item's SKU

line_item.quantity (*)

Integer

Item quantity

line_item.title (*)

String

The title of the product.
Note: If SKU is empty, trcaking page use this title to display product info.

line_item.variant_id

String

The ID of the product variant.

line_item.variant_title

String

The title of the product variant.

line_item.vendor

String

The name of the item's supplier

line_item.name

 

The name of the product variant

line_item.gift_card

boolean

Whether the item is a gift card. If true, then the item is not taxed or considered for shipping charges

line_item.taxable

boolean

Whether the item is taxable or not.

line_item.weight.value

integer

weight of the particular item

line_item.weight.unit

String

oz/grms

line_item.dimensions

 

 

line_items.dimensions.length

integer

Length of the item

line_items.dimensions.width

integer

Width of the item

line_items.dimensions.height

integer

Height of the item.

line_items.dimensions.grith

integer

Grith of the item.

line_items.dimensions.thickness

integer

Thickness of the item.

line_items.dimensions.units

String

No. of units

price.value (*)

Integer

Price of the item

price.currency (*)

String

Currency (default: USD)

line_items.image_url (*)

String

Image Url.
Note: Fenix displays item images on the Tracking Page.

line_items.routing_url

String

URL where it route to the website product details page.

Note1: Route to website product details page when anyone clicked on images displayed on tracking page.

Note2: If it is null, there won’t be a route to websites PDP.

properties

ARRAY

An array to pass additional information about line item

properties.name

String

Name of the property

properties.value

String

Value of the property