Order Management Notification Service¶

The Order Management Notification Service provides support for notifications, to be sent from the Flipkart system to the seller system, for any event in a shipment lifecycle, such as shipment creation, label creation, shipment cancellation, and so on. You can use this feature to improve the performance of your application by eliminating additional network and computation costs in polling resources to determine if they have changed.

Format: JSON

Notification	Description / Use Case
Shipment Created	Sent when an order is placed
Hold	Sent when an order item is flagged as “Hold”
UnHold	Sent when an order item flagged as “Hold” is released for further processing
Packed	Sent when an order item state is changed to “Packed”
Ready To Dispatch	Sent when an order item is marked as “Ready to Dispatch”
Pickup Complete	Sent when the shipment is picked up by the logistics team
Shipped	Sent when an order item is shipped
Delivered	Sent when an order item is delivered
Dispatch Dates Changed	Sent when the dispatch date is changed
Shipment Cancelled	Sent when an approved order is cancelled
Shipment Form Failed	Sent when a form generation fails
Return Created	Sent when a new return request is created
Return Tracking Id Update	Sent when an when tracking details for a customer return is updated
Return Expected Date Changed	Sent when the expected date of return of an orderItem changes
Return PickedUp	Sent when a return is picked up
Return Completed	Sent when a return is completed
Return Cancelled	Sent when a return request is revoked

Subscribing to Notifications¶

To use notifications:

You must be a registered seller on https://seller.flipkart.com.
Setup a notification receiver in your system. This is an HTTPS server that handles the API notifications triggered when a resource changes. For example: https://www.[your-website].com/notifications-receiver.
You should have a VAPT certificate for the notification receiver in your system.

Notification Subscription Prerequisites:

When raising a ticket to subscribe to notifications, please provide the following details:

Seller id / Seller registered email address
Notification receiver URL
VAPT & NDA certificate for the URL
If return notifications are needed (Yes / NO)
If Yes then Notification receiver URL for return notification (This could be same as order notification URL)
If return notification URL is different then provide VAPT certificate for the URL
Location ids for which you want to listen order and return notifications
App ID *
App Secret ID *

Single Seller:

Raise a ticket using the Seller Dashboard: Seller Dashboard

Steps: Seller Dashboard > Login > Help > Browse Categories > API > Common Topics > How to enable Order Management Notification using API > Raise Ticket

3rd Party Aggregator:

Raise a ticket using the Partner Dashboard: Partner Dashboard

Steps: Partner Dashboard > Login > API > Help & Support > Create Ticket

If a 3rd Party Aggregator is subscribing multiple sellers or if different sellers have different Notification Receiver URLs, then a 3rd Party Aggregator must upload an Excel sheet containing all the required information (as listed in the “Common Requirements”) for each seller separately.

Note

Even if you are a 3rd party aggregator you need to provide seller id / seller registered email address for which you will consume the events.

The proposed event structure for these notifications contain the following parameters:

Parameter Name	Description
`eventType`	The notification type. Possible values: `shipment_created`, `shipment_packed`, `shipment_ready_to_dispatch`, `shipment_shipped`, `shipment_delivered`, and so on
`source`	Point of origin of the notification - “flipkart”
`timestamp`	ISO time string
`attributes`	Custom parameters for the event

Note

If you are an API Partner and onboarding multiple sellers on notification service with same url & need a mechanism to verify the corresponding seller for the notification, then you can maintain locationId <-> seller_id mapping at your end. In the shipment_created event you can use the keys locationId to identify the seller and shipmentId to track the order in subsequent events.

Enable/Disable Notification¶

API Endpoint: PUT /v3/notification/subscription

Description - This API helps in self-serving the process of enabling/disabling the returns and order notification provided the seller-subscription exists for the given seller and location id. Users can control notification settings for both order and returns notifications independently or together.

Purpose: Enable or disable order and returns notifications for a specific seller and location.

Note

Key Features:

If disable_order is set to true, order notifications will be disabled; if set to false, order notifications will be enabled.
If disable_returns is set to true, returns notifications will be disabled; if set to false, returns notifications will be enabled.
User can specify either disable_order, disable_returns, or both parameters.
Failing to specify both parameters will make no changes in the subscription and will return a 200 response.

Request and Response Parameters¶

URL: https://api.flipkart.net/sellers/v3/notification/subscription

Request Header Parameters

Parameter	Type	Requirement	Description
`Content-Type`	String	Mandatory	Must be `application/json`
`Authorization`	String	Mandatory	Bearer token for authentication

Request Body Parameters

Parameter	Type	Requirement	Description
`seller_id`	String	Mandatory	Seller identifier
`location_id`	String	Mandatory	Location identifier
`disable_order`	Boolean	Optional	Set to true to disable order notifications, false to enable
`disable_returns`	Boolean	Optional	Set to true to disable returns notifications, false to enable

Sample Request

curl --location 'https://api.flipkart.net/sellers/v3/notification/subscription' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 39179d4e-5754-48dd-9b20-3b4b9d1a32bd' \
--data '{
  "seller_id": "<seller_id>",
  "location_id": "<location_id>",
  "disable_order": true,
  "disable_returns": false
}'

Response Body Parameters

Parameter	Type	Description
`message`	String	Success message

Sample Response (200 OK)

{
    "message": "Push notification settings updated successfully"
}

Sample Error Response (403 Forbidden)

{
    "error": "No Status Found",
    "message": "Operation forbidden! The subscription with sellerId: <seller_id> and locationId: <location_id> doesn't belong to the caller of the API!"
}

Possible Error Response Codes

Error Codes	Reason for Error
`400 Bad Request`	Token does not belong to the seller
`401 Unauthorized`	Invalid or missing authorization token
`403 Forbidden`	Subscription doesn’t belong to API caller
`404 Not Found`	Seller subscription not found
`500 Internal Server Error`	Server error occurred

Notifications Authentication¶

All Flipkart Notifications are RESTful notifications that send event payloads to the seller system endpoint.

Sellers authenticate to Flipkart API using OAuth credentials (Application ID and Application Secret). Those who wish to listen to notifications must register their notification endpoints with Flipkart. Sellers need a mechanism to validate whether the request originated from Flipkart and not by untrusted sources. Flipkart REST APIs authenticate to seller notification endpoints using a signature-based authentication by using Authorization headers.

Every notification includes headers in the following format:

X_Date : <date_timestamp>
X_Authorization : FKLOGIN  Base64 (OAuth-appid : <fk_signature>)

Here,

date_timestamp is the timestamp at which the notification is generated and is in “HTTP-Date” format.
fk_signature is generated per request using SHA1 based message digest algorithm with values derived from request as:
```
SHA-1 (date_timestamp + notification_http_url + notification_http_method + OAuth-secret)
```

REST endpoints that receive these notifications need to authenticate the request by regenerating the Signature (fk_signature) using the logic above and verifying it with the Authorization (X_Authorization) header. Consider the following example.

Authentication Sample¶

Seller: PilotSeller

OAuth Appication ID: 6113ca4a-fe05-11e4-a322-1697f925ec7b

OAuth Application Secret: 669a57f4-fe05-11e4-a322-1697f925ec7b

Notification URL: http://seller.api.pilotseller.com/notify/fki POST

Timestamp: 1432026135

Signature:

SHA1(1432026135http://seller.api.pilotseller.com/notify/fkiPOST669a57f4-fe05-11e4-a322-1697f925ec7b) 83762abd87b41e66ddd58320a4e803251e72b776

Authorization Information:

Base64(6113ca4a-fe05-11e4-a322-1697f925ec7b:83762abd87b41e66ddd58320a4e803251e72b776)NjExM2NhNGEtZmUwNS0xMWU0LWEzMjItMTY5N2Y5MjVlYzdiOjgzNzYyYWJkODdiNDFlNjZkZGQ1ODMyMGE0ZTgwMzI1MWU3MmI3NzY=

Headers

X_Date: Tue, 19 May 2015 09:02:15 GMT

X_Authorization:

FKLOGIN NjExM2NhNGEtZmUwNS0xMWU0LWEzMjItMTY5N2Y5MjVlYzdiOjgzNzYyYWJkODdiNDFlNjZkZGQ1ODMyMGE0ZTgwMzI1MWU3MmI3NzY=

Notifications Response¶

For a notification, the seller application needs to respond with a standard HTTP success status 200, or should throw an error response in the following scenarios only:

When the seller system is down
If the payload is incorrect

The notification system ensures that the message is sent at least once, but not only once. Hence, it is recommended to add an idempotency check in the client to avoid processing of duplicate notifications.