Handling Delivery Notifications

Vift videos are automatically sent to their recipients when their package arrives, so each order must have delivery information associated with it.

Delivery notifications are triggered in one of two ways:

a) by using the shipment's tracking number (Standard Carrier Shipping)

b) by a direct update of an order's delivery status (Custom Shipment Tracking)

Standard Carrier Shipping

When using Standard Carrier Shipping for an order, you must update an order object with carrier and tracking information. Vift obtains shipment notifications directly from the carrier, and the video is automatically sent once the carrier marks the package as delivered.

📘

Vift Standard Carrier Shipping works with the following carriers: UPS, FedEx, and USPS.

How it works

  1. Once you have tracking information available for an order, you update the Vift order object with the carrier name and the package's tracking number.
  2. We track the package using the provided carrier name and tracking number. When the package is marked as delivered by the carrier, Vift notifies the recipient about their video message.

Tracking Number Validation

Each tracking number submitted to Vift is automatically validated with its corresponding carrier. When a tracking number cannot be validated, the response from Vift will contain a warning message. Tracking numbers that are unable to be validated will still be stored in our system and will consequently still be used to track an Order's package.

Note that the appearance of a warning message in a Vift response does not necessarily mean that a tracking number is invalid. A warning will also appear if the tracking number is not yet in the corresponding carrier's system (i.e. tracking info has not yet been sent to or processed by the carrier).

Sample Request:

curl -i https://api.vift.com/orders/YOUR_ORDER_ID \
		 -u YOUR_APP_ID:YOUR_API_KEY \
     -H "Content-Type: application/json" \
     -X PUT \
     -d '{
           "carrier": "UPS",
           "tracking_number": "1Z999AA10123456784"
         }'

Sample Response:

{
  "id": "YOUR_ORDER_ID",
  "uuid": "d41dfd35-461f-4e04-816b-d6bcf5ed30a7",
  "name": "John Doe",
  "email": "[email protected]",
  "recipient_name": "Jane Doe",
  "recipient_email": "[email protected]",
  "recipient_phone": null,
  "record_url": "https://vift.com/record/d41dfd35-461f-4e04-816b-d6bcf5ed30a7",
  "playback_url": "https://vift.com/watch/d41dfd35-461f-4e04-816b-d6bcf5ed30a7",
  "send_method": "email",
  "send_trigger": "package",
  "send_on": null,
  "carrier": "UPS",
  "tracking_number": "1Z999AA10123456784",
  "delivered": "0",
  "video_title": "My Vift Video",
  "video_duration": "30072",
  "video_processed": "1",
  "price": null,
  "status": "recorded",
  "created_at": "2015-01-01T00:00:00Z",
  "updated_at": "2015-01-01T02:00:00Z",
  "recorded_at": "2015-01-01T01:00:00Z",
  "delivered_at": null,
  "sent_at": null,
  "viewed_at": null
}

Sample Response (with warning)

{
  "warning":
  {
    "type": "request",
    "message": "Tracking number could not be validated with UPS or is not yet in the UPS system."
  },
  "id": "YOUR_ORDER_ID",
  "uuid": "d41dfd35-461f-4e04-816b-d6bcf5ed30a7",
  "name": "John Doe",
  "email": "[email protected]",
  "recipient_name": "Jane Doe",
  "recipient_email": "[email protected]",
  "recipient_phone": null,
  "record_url": "https://vift.com/record/d41dfd35-461f-4e04-816b-d6bcf5ed30a7",
  "playback_url": "https://vift.com/watch/d41dfd35-461f-4e04-816b-d6bcf5ed30a7",
  "send_method": "email",
  "send_trigger": "package",
  "send_on": null,
  "carrier": "UPS",
  "tracking_number": "1Z999AA10123456784",
  "delivered": "0",
  "video_title": "My Vift Video",
  "video_duration": "30072",
  "video_processed": "1",
  "price": null,
  "status": "recorded",
  "created_at": "2015-01-01T00:00:00Z",
  "updated_at": "2015-01-01T02:00:00Z",
  "recorded_at": "2015-01-01T01:00:00Z",
  "delivered_at": null,
  "sent_at": null,
  "viewed_at": null
}

Custom Shipment Tracking

When using Custom Shipment Tracking for an order, you update the order object by marking it as delivered, which triggers the video message to be sent to the recipient.

📘

Use Custom Shipment Tracking when you use a carrier not supported by Vift or if you need more control over delivery notifications.

How it works

  1. Once a customer's package has been delivered, you update the Vift order object.
  2. Vift notifies the recipient about their video message.

Sample Request:

curl -i https://api.vift.com/orders/YOUR_ORDER_ID \
     -u YOUR_APP_ID:YOUR_API_KEY \
     -H "Content-Type: application/json" \
     -X PUT \
     -d '{
           "delivered": 1
         }'

Sample Response:

{
  "id": "YOUR_ORDER_ID",
  "uuid": "d41dfd35-461f-4e04-816b-d6bcf5ed30a7",
  "name": "John Doe",
  "email": "[email protected]",
  "recipient_name": "Jane Doe",
  "recipient_email": "[email protected]",
  "recipient_phone": null,
  "record_url": "https://vift.com/record/d41dfd35-461f-4e04-816b-d6bcf5ed30a7",
  "playback_url": "https://vift.com/watch/d41dfd35-461f-4e04-816b-d6bcf5ed30a7",
  "send_method": "email",
  "send_trigger": "package",
  "send_on": null,
  "carrier": null,
  "tracking_number": null,
  "delivered": "1",
  "video_title": "My Vift Video",
  "video_duration": "30072",
  "video_processed": "1",
  "price": null,
  "status": "delivered",
  "created_at": "2015-01-01T00:00:00Z",
  "updated_at": "2015-01-04T00:00:00Z",
  "recorded_at": "2015-01-01T01:00:00Z",
  "delivered_at": "2015-01-04T00:00:00Z",
  "sent_at": null,
  "viewed_at": null
}