Order API 19.2

This version captures additional fields that will be added to v1.0 Order API Schema in Q2 2019. Revised 05/30/2019

Base URL

https://ws-st01.narvar.qa/api/v1

Lists the available operations to be used against the Order API

The API only supports the sending and receiving of UTF-8 encoded data.

POST - Create/Update Orders

POST /orders

PUT - Create/Update Shipments

PUT /orders/{order_number}/shipments

GET - Retrieve Order

GET /orders/{order_number}

POST /orders

Authentication

basicAuth

This will create a new order or send new information about an existing order

Request body

application/json

Order details

Object

order_info

Object required

order_number

string required

A unique identifier for the order

Example:

34252345

order_date

string required

Timestamp of when the order was created. See data formats for accepted formats for timestamp. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-24T13:25:31Z

order_items

Array required

Object

categories

Array

The categories the product falls under

string

Example:

Clothing

is_backordered

boolean

Whether or not the item is backordered

Example:

false

vendors

Array

The vendor for the item. Narvar uses this to power business logic when items need to be shipped back to variable locations. If this functionality is being used then the address where the item should be returned can be sent in this object. For example, if the item should be shipped back to a store location or a drop ship vendor then this should be passed

Object

phone

string required

The vendor’s phone number

Example:

1-888-555-4433

name

string required

Vendor name

Example:

Stevensen Fabrics

string

Vendor email

Example:

johndoe@example.com

type

string

Describes the type of vendor

Example:

Drop Ship

address

Object required

street_1

string required

Example:

633 Folsom Street

street_2

string

Example:

Floor 2

city

string required

Example:

San Francisco

state

string required

Example:

zip

string required

This can be a US zip code, or any international postal code

Example:

94107

country

string required

Country code should match ISO Alpha-2

Example:

description

string

The description of the item

Example:

Red Shoe made by designer

discount_amount

number

Example:

discount_percent

number

The percentage that the item was discounted

Example:

final_sale_date

string

The date when the order item went on final sale. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-25T13:25:31Z

fulfillment_status

string required

Used to determine what fulfillment state the item is in when the order is created or updated. NOT_SHIPPED should persist until all of the quantity of the line item has been shipped

Enumeration:

NOT_SHIPPED

The item has yet to be shipped

SHIPPED

The item has shipped

CANCELLED

The item has been cancelled

RETURNED

The item has been returned

PROCESSING

The item is still processing

READY_FOR_PICKUP

The item is ready to be picked up from a location

DELAYED

The item has been delayed

PICKED_UP

The item has been picked up

NOT_PICKED_UP

The item did not get picked up

Example:

NOT_SHIPPED

is_final_sale

boolean

True is the item is not returnable. False if it is returnable

Example:

false

is_gift

boolean

True if the item was purchased as a gift

Example:

false

item_id

string

Required if the same SKU is sent in two different item object and is used as the unique identifier of the record

Example:

43582

item_image

string required

The image that should be used for the item

Example:

https://itemimageurl.png

item_promise_date

string

The promise date associated with the item

Example:

2018-02-25T13:25:31Z

item_url

string required

The URL that will direct back to the product page

Example:

https://item123.html

line_number

number

The line number of the item from the OMS system

Example:

name

string required

A title or name of the order item

Example:

Red Shoe

quantity

number required

The number of the item that has been purchased

Example:

sku

string required

A unique sku for this product item

Example:

D2343122

unit_price

number required

This is the price that will be shown to the end user as what they paid for the product

Example:

fulfillment_type

string

Enumeration:

Home delivery

BOPIS

Buy online pick up in store

BOSS

Buy online ship to store

Example:

dimensions

Object

Describes the dimensions of an item

uom

string

Example:

length

number

Example:

width

number

Example:

height

number

Example:

weight

number

Example:

weight_uom

string

Example:

lbs

attributes

Object

string

Example:

{ "promotion": "bogo" }

events

Array

Object

event

string required

Enumeration:

PRESHIPMENT

The item has not yet shipped. Customer can define up to 10 distinct preshipment statuses to represent the different steps before shipment. Is “sequence’ is not passed then “sequence” = 0 will be assumed

CANCELLED

The item has been cancelLed

RETURNED_BY_MAIL

The item has been returned by mail without using the Narvar platform

RETURNED_TO_STORE

The item has been returned to the store without using the Narvar platform

NON_RETURNABLE

The item should not be allowed to be returned because of something that occurred after delivery

DELIVERY_EXCEPTION

The item did not make it to the end user because of an issue that occurred while in-transit

RETURNED_NARVAR

It is not required to send an update to the Narvar system when an item is returned through the Narvar application. However, if an update is needed or desired based on other communications then this status can be used to show items already returned by Narvar

CURRENT_RETURNABLE_QTY

Represents the total returnable quantity that Narvar should allow to be returned through the platform. If this is passed it will override all other quantity calculations and show this exact quantity to the end user

MODIFIED

The item has been modified on this date/time

Example:

CANCELLED

quantity

integer required

The number of the items that are in the event state

Example:

sequence

integer

This can be used to show the order of events. Mainly used to show the order of preshipment statuses on the Narvar tracking pages

Example:

date

string

Date/time of the event. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-25T13:25:31Z

anticipated_ship_date

string

The date when the order item should be shipped. This field is used to capture the anticipated date of shipping, the actual ship date when the item is shipped is captured in the shipments object

original_unit_price

number

The original price for the unit without discounts and/or promotions applied, otherwise known as the strikethrough price.

Example:

original_line_price

number

The total original price for the order line, without discounts and/or promotions applied, otherwise known as the strikethrough line price.

Example:

238

line_price

number

The total price for the order line with discounts and/or promotions applied.

Example:

224

narvar_convert_id

string

ID of the request to Narvar Convert that was displayed to the end user. This is used for analytics and monitoring of Narvar Convert product

item_type

string

Used to describe the item type.

Enumeration:

PHYSICAL

Physical item - Default

DIGITAL

Digital item

is_hazmat

boolean

Indicates whether it is a hazmat item or not.

Examples:

truefalse

hazmat_codes

Array of string

List of hazmat codes

Example:

[
    "UN3480", "GHS02"
]

string

shipments

Array

Object

items_info

Array required

Contains the items within the shipment. Must match items passed under order_items

Object

item_id

string

Example:

ID123

sku

string

Example:

DS234

quantity

integer

Example:

ship_method

string

Example:

Standard

carrier

string required

Example:

UPS

carrier_service

string

Example:

promise_date

string

Retailer’s promise date for items in the shipment. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2021-02-25T13:25:31Z

ship_source

string

Example:

DCWest

ship_date

string required

The date the items were shipped. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2021-02-25T13:25:31Z

ship_discount

number

Example:

ship_tax

number

Example:

ship_total

number

Example:

100

tracking_number

string required

Example:

1Z517757671802283

shipped_from

Object

company_name

string

Example:

Acme International

string

Example:

john.doe@narvar.com

first_name

string

Example:

John

last_name

string

Example:

Doe

phone

string

Example:

6501234567

address

Object

street_1

string required

Example:

633 Folsom Street

street_2

string

Example:

Floor 2

city

string required

Example:

San Francisco

state

string required

Example:

zip

string required

This can be a US zip code, or any international postal code

Example:

94107

country

string required

Country code should match ISO Alpha-2

Example:

location_id

string

Reference to a pre-configured location id in Narvar

shipped_to

Object required

string

Example:

john.doe@narvar.com

first_name

string required

Example:

John

last_name

string required

Example:

Doe

phone

string

Example:

6501234567

address

Object required

street_1

string required

Example:

633 Folsom Street

street_2

string

Example:

Floor 2

city

string required

Example:

San Francisco

state

string required

Example:

zip

string required

This can be a US zip code, or any international postal code

Example:

94107

country

string required

Country code should match ISO Alpha-2

Example:

location_id

string

Reference ID to a pre-configured location in Narvar

attribute

Object

string

Example:

{ "promotion": "bogo" }

billing

Object

amount

number

Total amount paid for the order

Example:

payments

Array

Contains the payment information about the order

Object

is_gift_card

string

Example:

true

merchant

string

Example:

VISA

method

string

Example:

swipe

expiration_date

string

Example:

02/19

billed_to

Object required

string

Example:

john.doe@narvar.com

first_name

string required

Example:

John

last_name

string required

Example:

Doe

phone

string

Example:

6501234567

address

Object required

street_1

string required

Example:

633 Folsom Street

street_2

string

Example:

Floor 2

city

string required

Example:

San Francisco

state

string required

Example:

zip

string required

This can be a US zip code, or any international postal code

Example:

94107

country

string required

Country code should match ISO Alpha-2

Example:

location_id

string

Reference ID to a pre-configured location in Narvar

tax_amount

number

Example:

12.5

tax_rate

number

Example:

9.8

shipping_handling

number

Example:

4.3

pickups

Array

Object

string required

Example:

1234

items_info

Array required

Object

item_id

string

Example:

ID123

sku

string required

Example:

DS234

quantity

integer required

Example:

status

Object required

code

string required

This will trigger different actions on the Narvar platform. Must follow the enums

Enumeration:

PROCESSING

The items are still processing

READY_FOR_CARRIER

The items are ready to be shipped through carrier

READY_FOR_PICKUP

The items are ready to be picked up from a location

PICKED_UP

The items have been picked up

DELAYED

The items have been delayed

NOT_PICKED_UP

The items did not get picked up

CANCELLED

The item has been cancelled

Example:

READY_FOR_PICKUP

message

string

A custom message can be passed and will be used with some Narvar products

Example:

Your order is ready to be picked up!

date

string required

The date the status changed. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-24T13:25:31Z

eta

string

The date when the order is expected to be ready to pickup. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-25T13:25:31Z

pickup_by_date

string

The by which the customer is required to pickup their order. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-03-01T13:25:31Z

attributes

Object

string

Example:

{ "promotion": "bogo" }

store

Object required

The store information where the items will be picked up

name

string

Example:

Peninsula Trading

string

Example:

2342

store_area

string

Example:

Side Door

address

Object required

street_1

string required

Example:

633 Folsom Street

street_2

string

Example:

Floor 2

city

string required

Example:

San Francisco

state

string required

Example:

zip

string required

This can be a US zip code, or any international postal code

Example:

94107

country

string required

Country code should match ISO Alpha-2

Example:

url

string

Example:

peninsulatrading.co

phone_number

string

Example:

(415) 486-8611

hours

Array

Example:

[
  {
    "open" : "0800",
    "close" : "2000"
  },
  {
    "open" : "0800",
    "close" : "2000"
  },
  {
    "open" : "0800",
    "close" : "2000"
  },
  {
    "open" : "0800",
    "close" : "2000"
  },
  {
    "open" : "0800",
    "close" : "2000"
  },
  {
    "open" : "0800",
    "close" : "2000"
  },
  {
    "open" : "0800",
    "close" : "2000"
  }
]

Object

open

string

carrier

string

If a carrier is used to deliver the package to a store then this can be passed to Narvar. Required if pickup type is BOSS, or carrier-based CONCIERGE

Example:

ups

tracking_number

string

Tracking number for the package being shipped to the store. Required if pickup type is BOSS, or carrier-based CONCIERGE

Example:

1Z4398734978453

ship_date

string

The date when the package was shipped to the store. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-23T13:25:31Z

type

string required

Type of this pickup

Enumeration:

CONCIERGE

If this is a concierge pickup

BOSS

If items need to be shipped from warehouse though carrier (Please make sure to include carrier and tracking_number in pickup object)

BOPIS

If items are already in store, and do not need to be shipped from warehouse

collection_token

string

The code or passphrase that may or may not be needed to pickup item(s) from a pickup point.

Example:

DRTQ42

customer

Object required

customer_id

string required

A unique identifier for the customer

Example:

"78997234200222"

address

Object

street_1

string required

Example:

633 Folsom Street

street_2

string

Example:

Floor 2

city

string required

Example:

San Francisco

state

string required

Example:

zip

string required

This can be a US zip code, or any international postal code

Example:

94107

country

string required

Country code should match ISO Alpha-2

Example:

string

Example:

john.doe@narvar.com

first_name

string

Example:

John

last_name

string

Example:

Doe

phone

string

Example:

6501234567

customer_type

string

Example:

premium

customer_tier

string

Example:

bronze

notification_preferences

Array of string

Example:

["SMS","FACEBOOK_MESSENGER","HIPAA_SMS","FB","VOICE","WHATSAPP","HIPAA_EMAIL","EMAIL","LINE","WEBHOOK"]

attributes

Object

string

Example:

{ "promotion": "bogo" }

events

Array

Object

event

string

Enumeration:

MODIFIED

The order has been modified on this date/time

CANCELLED

The order has been CANCELLED

Example:

MODIFIED

date

string

Date/time of the event. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-25T13:25:31Z

currency_code

string

The currency code for the item price/cost in the order

Example:

USD

selected_ship_method

string

Shipment method selected at order checkout

Example:

Expedited

notification_preferences

Object

Used to set an opt-into order-level notifications.

optins

Array

An array of maps describing the order level opt-in. Currently, we only support one channel and contact.

Example:

[
  {
    "channel": "sms",
    "contact": "+11234567890"
  }
]

Object

channel

string

the channel that the customer has opted-into for this order. Currently, we only support sms

contact

string

the contact information for the customer for that channel for this order. Phone numbers have to be given in E.164 format with country code.

promotions

Array

An array containing 0 or more order promotion names and their associated values. Promotions that were applied as percentages should be passed as “Applied”. Promotions will be displayed in the order they are received in the array.

Example:

[
  {
    "promotion": "New Customer Special",
    "value": "-$3.5"
  },
  {
    "promotion": "Valentine's Day",
    "value": "Applied"
  }
]

Object

promotion

string

The name of the promotion

value

string

The value of the promotion

checkout_locale

string

Responses

200 200

ITEM CREATED

Body

application/json

Object

status

string

Example:

SUCCESS

messages

Array

Object

code

string

Example:

response.status.success

message

string

Example:

Order information saved for order number 34252345

304 304

NOT MODIFIED

application/json

400 400

BAD REQUEST

Body

application/json

Object

status

string

Example:

FAILURE

messages

Array

Object

level

string

Example:

ERROR

code

string

Example:

order_info.order_items.is_backordered

message

string

Example:

Can not deserialize value of type java.lang.boolean from String

401 401

UNAUTHORIZED

application/json

403 403

FORBIDDEN

application/json

404 404

NOT FOUND

application/json

405 405

METHOD NOT ALLOWED

application/json

409 409

ITEM ALREADY EXISTS

application/json

500 500

INTERNAL SERVER ERROR

application/json

503 503

SERVICE UNAVAILABLE

application/json

Full Order

Before Shipment

Pickup In Store

POST https://ws-st01.narvar.qa/api/v1/orders HTTP/1.1 

Content-Type: application/json

{
  "order_info": {
    "order_number": "34252345",
    "order_date": "2018-02-24T13:25:31Z",
    "checkout_locale": "en_US",
    "currency_code": "USD",
    "status": "SHIPPED",
    "order_items": [
     {
      "categories": [
        "Clothing",
        "Shoes"
      ],
      "fulfillment_status": "SHIPPED",
      "is_final_sale": false,
      "item_promise_date": "2018-03-30T13:25:31Z",
      "item_image": "https://itemimageurl.png",
      "item_url": "https://item123.html",
      "name": "Red Shoes",
      "description": "Red Shoes - Size 10",
      "item_type": "PHYSICAL",
      "quantity": 2,
      "sku": "D2343122",
      "item_id": null,
      "unit_price": 32.99,
      "original_unit_price": 55.99,
      "line_price": 65.98,
      "original_line_price": 111.98,
      "narvar_convert_id": "8db7e368-43f8-4654-8b33-18729986e580",
      "color": "red",
      "size": "10",
      "style": "low-tops",
      "is_hazmat": false,
      "attributes": {
        "pattern": "zebra"
      }
     },
     {
      "categories": [
        "Clothing",
        "Tops"
      ],
      "fulfillment_status": "SHIPPED",
      "is_final_sale": false,
      "item_promise_date": "2018-03-30T13:25:31Z",
      "item_image": "https://itemimageurl.png",
      "item_url": "https://item123.html",
      "name": "Blue shirt",
      "description": "Blue striped shirt",
      "item_type": "PHYSICAL",
      "quantity": 1,
      "sku": "F432423",
      "item_id": null,
      "unit_price": 59.99,
      "original_unit_price": 75.99,
      "line_price": 59.99,
      "original_line_price": 76.99,
      "narvar_convert_id": "2d342a92-f487-4a82-9cde-83bf1402feca",
      "color": "blue",
      "size": "medium",
      "style": "retro",
      "is_hazmat": true,
      "hazmat_codes": [
        "UN3480",
        "UN3481",
      ],
      "attributes": {
        "pattern": "striped"
      }
     }
    ],
    "billing": {
      "amount": 30.00,
      "payments": [
        {
          "is_gift_card": true,
          "merchant": "VISA",
          "method": "swipe",
          "expiration_date": "02/19"
        }
      ],
      "billed_to": {
        "email": "john.doe@narvar.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "6501234567",
        "address": {
          "street_1": "633 Folsom Street",
          "street_2": "Floor 2",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94107",
          "country": "US"
        }
      },
      "tax_amount": 12.50,
      "tax_rate": 9.8,
      "shipping_handling": 4.30
    },
    "customer": {
      "customer_id": "78997234200222",
      "address": {
        "street_1": "633 Folsom Street",
        "street_2": "Floor 2",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94107",
        "country": "US"
      },
      "email": "john.doe@narvar.com",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "6501234567",
      "customer_type": "premium"
    },
    "attributes": {
      "promotion": "bogo",
      "checkout_brand": "peninsula",
      "checkout_language": "en",
      "checkout_country": "US"
    },
    "shipments": [
      {
        "items_info": [
          {
            "sku": "D2343122",
            "quantity": 2
          },
          {
            "sku": "F432423",
            "quantity": 1
          }
        ],
        "ship_method": "Standard",
        "carrier": "UPS",
        "carrier_service": "GR",
        "ship_source": "DCWest",
        "ship_date": "2018-02-25T13:25:31Z",
        "ship_discount": 5.00,
        "ship_tax": 10.00,
        "ship_total": 100.00,
        "tracking_number": "1Z517757671802283",
        "shipped_from": {
          "company_name": "Acme International",
          "email": "john.doe@narvar.com",
          "first_name": "John",
          "last_name": "Doe",
          "phone": "6501234567",
          "address": {
            "street_1": "633 Folsom Street",
            "street_2": "Floor 2",
            "city": "San Francisco",
            "state": "CA",
            "zip": "94107",
            "country": "US"
          }
        },
        "shipped_to": {
          "email": "john.doe@narvar.com",
          "first_name": "John",
          "last_name": "Doe",
          "phone": "6501234567",
          "address": {
            "street_1": "633 Folsom Street",
            "street_2": "Floor 2",
            "city": "San Francisco",
            "state": "CA",
            "zip": "94107",
            "country": "US"
          }
        }
      }
    ],
    "promotions": [
  {
    "promotion": "New Customer Special",
    "value": "-$3.5"
  },
  {
    "promotion": "Valentine's Day",
    "value": "Applied"
  }
],
    "notification_preferences": {
      "optins": [
        {
          "channel": "sms",
          "contact": "+11234567890"
        },
        {
          "channel": "whatsapp",
          "contact": "somewhatsappid"
        }
      ]
    }
  }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "status": "SUCCESS",
    "messages": [
        {
            "code": "response.status.success",
            "message": "Order information saved for order number 34252345"
        }
    ]
}

POST https://ws-st01.narvar.qa/api/v1/orders HTTP/1.1 

Content-Type: application/json

{
  "order_info": {
    "order_number": "34252345",
    "order_date": "2018-02-24T13:25:31Z",
    "checkout_locale": "en_US",
    "currency_code": "USD",
    "status": "NOT_SHIPPED",
    "order_items": [{
      "categories": [
        "Clothing",
        "Shoes"
      ],
      "fulfillment_status": "NOT_SHIPPED",
      "is_final_sale": false,
      "item_promise_date": "2018-03-30T13:25:31Z",
      "item_image": "https://itemimageurl.png",
      "item_url": "https://item123.html",
      "name": "Red Shoes",
      "description": "Red Shoes - Size 10",
      "item_type": "PHYSICAL",
      "quantity": 2,
      "sku": "D2343122",
      "item_id": null,
      "unit_price": 32.99,
      "original_unit_price": 55.99,
      "line_price": 65.98,
      "original_line_price": 111.98,
      "narvar_convert_id": "8db7e368-43f8-4654-8b33-18729986e580",
      "color": "red",
      "size": "10",
      "style": "low-tops",
      "is_hazmat": false,
      "attributes": {
        "pattern": "zebra"
      }
    },
    {
      "categories": [
        "Clothing",
        "Tops"
      ],
      "fulfillment_status": "NOT_SHIPPED",
      "is_final_sale": false,
      "item_promise_date": "2018-03-30T13:25:31Z",
      "item_image": "https://itemimageurl.png",
      "item_url": "https://item123.html",
      "name": "Blue shirt",
      "description": "Blue striped shirt",
      "item_type": "PHYSICAL",
      "quantity": 1,
      "sku": "F432423",
      "item_id": null,
      "unit_price": 59.99,
      "original_unit_price": 75.99,
      "line_price": 59.99,
      "original_line_price": 76.99,
      "narvar_convert_id": "2d342a92-f487-4a82-9cde-83bf1402feca",
      "color": "blue",
      "size": "medium",
      "style": "retro",
      "is_hazmat": true,
      "hazmat_codes": [
        "UN3480"
        ]
      "attributes": {
        "pattern": "striped"
      }
    }],
    "billing": {
      "amount": 30.00,
      "payments": [{
        "is_gift_card": true,
        "merchant": "VISA",
        "method": "swipe",
        "expiration_date": "02/19"
      }],
      "billed_to": {
        "email": "john.doe@narvar.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "6501234567",
        "address": {
          "street_1": "633 Folsom Street",
          "street_2": "Floor 2",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94107",
          "country": "US"
        }
      },
      "tax_amount": 12.50,
      "tax_rate": 9.8,
      "shipping_handling": 4.30
    },
    "customer": {
      "customer_id": "78997234200222",
      "address": {
        "street_1": "633 Folsom Street",
        "street_2": "Floor 2",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94107",
        "country": "US"
      },
      "email": "john.doe@narvar.com",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "6501234567",
      "customer_type": "premium"
    },
    "attributes": {
      "promotion": "bogo"
    }  
 }
}


HTTP/1.1 200 OK 

Content-Type: application/json

{
    "status": "SUCCESS",
    "messages": [
        {
            "code": "response.status.success",
            "message": "Order information saved for order number 34252345"
        }
    ]
}

POST https://ws-st01.narvar.qa/api/v1/orders HTTP/1.1 

Content-Type: application/json

{
  "order_info": {
    "order_number": "34252345",
    "order_date": "2018-02-24T13:25:31Z",
    "checkout_locale": "en_US",
    "currency_code": "USD",
    "status": "PROCESSED",
    "order_items": [{
      "categories": [
        "Clothing",
        "Shoes"
      ],
      "is_backordered": true,
      "description": "Red Shoes - Size 10",
      "discount_amount": 10.00,
      "discount_percent": 5.00,
      "final_sale_date": "2018-02-25T13:25:31Z",
      "fulfillment_status": "READY_FOR_PICKUP",
      "is_final_sale": true,
      "item_promise_date": "2018-02-30T13:25:31Z",
      "is_gift": true,
      "item_image": "https://itemimageurl.png",
      "item_promise_date": "2018-02-25T13:25:31Z",
      "item_url": "https://item123.html",
      "line_number": 1,
      "name": "Red Shoes",
      "quantity": 2,
      "sku": "D2343122",
      "item_id": null,
      "color": "red",
      "size": "10",
      "style": "low-tops",
      "attributes": {
        "pattern": "zebra"
      },
      "unit_price": 32.99,
      "original_unit_price": 55.99,
      "line_price": 65.98,
      "original_line_price": 111.98,
      "narvar_convert_id": "8db7e368-43f8-4654-8b33-18729986e580",
      "fulfillment_type": "HD",
      "dimension": {
        "uom": "in",
        "length": 10.00,
        "width": 5.00,
        "height": 7.00,
        "weight": 25.00,
        "weight_uom": "lbs"
      }
    }],
    "billing": {
      "amount": 30.00,
      "payments": [{
        "is_gift_card": true,
        "merchant": "VISA",
        "method": "swipe",
        "expiration_date": "02/19"
      }],
      "billed_to": {
        "email": "john.doe@narvar.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "6501234567",
        "address": {
          "street_1": "633 Folsom Street",
          "street_2": "Floor 2",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94107",
          "country": "US"
        }
      },
      "tax_amount": 12.50,
      "tax_rate": 9.8,
      "shipping_handling": 4.30
    },
    "pickups": [{
      "id": "1234",
      "items_info": [{
        "sku": "D2343122",
        "quantity": 1
      }],
      "status": {
        "code": "READY_FOR_PICKUP",
        "message": "Your order is ready to be picked up!",
        "date": "2018-02-25T13:25:31Z"
      },
      "eta": "2018-02-25T13:25:31Z",
      "pickup_by_date": "2018-03-01T13:25:31Z",
      "attributes": {
        "additionalProperties": null
      },
      "store": {
        "name": "Peninsula Trading",
        "id": "2342",
        "store_area": "Side Door",
        "address": {
          "street_1": "633 Folsom Street",
          "street_2": "Floor 2",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94107",
          "country": "US"
        },
        "url": "peninsulatrading.co",
        "phone_number": "(415) 486-8611",
        "hours": [{
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          }
        ]
      }
    }],
    "customer": {
      "customer_id": "78997234200222",
      "address": {
        "street_1": "633 Folsom Street",
        "street_2": "Floor 2",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94107",
        "country": "US"
      },
      "email": "john.doe@narvar.com",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "6501234567",
      "customer_type": "premium"
    }
  }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "status": "SUCCESS",
    "messages": [
        {
            "code": "response.status.success",
            "message": "Order information saved for order number 34252345"
        }
    ]
}

PUT /orders/{order_number}/shipments

Authentication

basicAuth

This will update an order with a shipment record or change

Path variables

order_number

string required

pass the order number

Request body

application/json

The shipment updates

Object

order_info

Object required

order_number

string

A unique identifier for the order

Example:

34252345

order_date

string

Timestamp of when the order was created. See data formats for accepted formats for timestamp. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-24T13:25:31Z

order_items

Array

Object

categories

Array

The categories the product falls under

string

Example:

Clothing

is_backordered

boolean

Whether or not the item is backordered

Example:

false

vendors

Array

Object

phone

string required

The vendor’s phone number

Example:

1-888-555-4433

name

string required

Vendor name

Example:

Stevensen Fabrics

string

Vendor email

Example:

johndoe@example.com

type

string

Describes the type of vendor

Example:

Drop Ship

address

Object required

street_1

string required

Example:

633 Folsom Street

street_2

string

Example:

Floor 2

city

string required

Example:

San Francisco

state

string required

Example:

zip

string required

This can be a US zip code, or any international postal code

Example:

94107

country

string required

Country code should match ISO Alpha-2

Example:

description

string

The description of the item

Example:

Red Shoe made by designer

discount_amount

number

Example:

discount_percent

number

The percentage that the item was discounted

Example:

final_sale_date

string

The date when the order item went on final sale. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-25T13:25:31Z

fulfillment_status

string required

Used to determine what fulfillment state the item is in when the order is created or updated. NOT_SHIPPED should persist until all of the quantity of the line item has been shipped

Enumeration:

NOT_SHIPPED

The item has yet to be shipped

SHIPPED

The item has shipped

CANCELLED

The item has been cancelled

RETURNED

The item has been returned

PROCESSING

The item is still processing

READY_FOR_PICKUP

The item is ready to be picked up from a location

DELAYED

The item has been delayed

PICKED_UP

The item has been picked up

NOT_PICKED_UP

The item did not get picked up

Example:

NOT_SHIPPED

is_final_sale

boolean

True is the item is not returnable. False if it is returnable

Example:

false

is_gift

boolean

True if the item was purchased as a gift

Example:

false

item_id

string

Required if the same SKU is sent in two different item object and is used as the unique identifier of the record

Example:

43582

item_image

string required

The image that should be used for the item

Example:

https://itemimageurl.png

item_promise_date

string

The promise date associated with the item

Example:

2018-02-25T13:25:31Z

item_url

string required

The URL that will direct back to the product page

Example:

https://item123.html

line_number

number

The line number of the item from the OMS system

Example:

name

string required

A title or name of the order item

Example:

Red Shoe

quantity

number required

The number of the item that has been purchased

Example:

sku

string required

A unique sku for this product item

Example:

D2343122

unit_price

number required

This is the price that will be shown to the end user as what they paid for the product

Example:

fulfillment_type

string

Enumeration:

Home delivery

BOPIS

Buy online pick up in store

BOSS

Buy online ship to store

Example:

dimensions

Object

Describes the dimensions of an item

uom

string

Example:

length

number

Example:

width

number

Example:

height

number

Example:

weight

number

Example:

weight_uom

string

Example:

lbs

attributes

Object

string

Example:

{ "promotion": "bogo" }

events

Array

Object

event

string required

Enumeration:

PRESHIPMENT

CANCELLED

The item has been cancelLed

RETURNED_BY_MAIL

The item has been returned by mail without using the Narvar platform

RETURNED_TO_STORE

The item has been returned to the store without using the Narvar platform

NON_RETURNABLE

The item should not be allowed to be returned because of something that occurred after delivery

DELIVERY_EXCEPTION

The item did not make it to the end user because of an issue that occurred while in-transit

RETURNED_NARVAR

CURRENT_RETURNABLE_QTY

MODIFIED

The item has been modified on this date/time

Example:

CANCELLED

quantity

integer required

The number of the items that are in the event state

Example:

sequence

integer

This can be used to show the order of events. Mainly used to show the order of preshipment statuses on the Narvar tracking pages

Example:

date

string

Date/time of the event. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-25T13:25:31Z

anticipated_ship_date

string

The date when the order item should be shipped. This field is used to capture the anticipated date of shipping, the actual ship date when the item is shipped is captured in the shipments object

original_unit_price

number

The original price for the unit without discounts and/or promotions applied, otherwise known as the strikethrough price.

Example:

original_line_price

number

The total original price for the order line, without discounts and/or promotions applied, otherwise known as the strikethrough line price.

Example:

238

line_price

number

The total price for the order line with discounts and/or promotions applied.

Example:

224

narvar_convert_id

string

ID of the request to Narvar Convert that was displayed to the end user. This is used for analytics and monitoring of Narvar Convert product

item_type

string

Used to describe the item type.

Enumeration:

PHYSICAL

Physical item - Default

DIGITAL

Digital item

is_hazmat

boolean

Indicates whether it is a hazmat item or not.

Examples:

truefalse

hazmat_codes

Array of string

List of hazmat codes

Example:

[
    "UN3480", "GHS02"
]

string

shipments

Array required

Object

items_info

Array required

Contains the items within the shipment. Must match items passed under order_items

Object

item_id

string

Example:

ID123

sku

string

Example:

DS234

quantity

integer

Example:

ship_method

string

Example:

Standard

carrier

string required

Example:

UPS

carrier_service

string

Example:

promise_date

string

Retailer’s promise date for items in the shipment. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2021-02-25T13:25:31Z

ship_source

string

Example:

DCWest

ship_date

string required

The date the items were shipped. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2021-02-25T13:25:31Z

ship_discount

number

Example:

ship_tax

number

Example:

ship_total

number

Example:

100

tracking_number

string required

Example:

1Z517757671802283

shipped_from

Object

company_name

string

Example:

Acme International

string

Example:

john.doe@narvar.com

first_name

string

Example:

John

last_name

string

Example:

Doe

phone

string

Example:

6501234567

address

Object

street_1

string required

Example:

633 Folsom Street

street_2

string

Example:

Floor 2

city

string required

Example:

San Francisco

state

string required

Example:

zip

string required

This can be a US zip code, or any international postal code

Example:

94107

country

string required

Country code should match ISO Alpha-2

Example:

location_id

string

Reference to a pre-configured location id in Narvar

shipped_to

Object required

string

Example:

john.doe@narvar.com

first_name

string required

Example:

John

last_name

string required

Example:

Doe

phone

string

Example:

6501234567

address

Object required

street_1

string required

Example:

633 Folsom Street

street_2

string

Example:

Floor 2

city

string required

Example:

San Francisco

state

string required

Example:

zip

string required

This can be a US zip code, or any international postal code

Example:

94107

country

string required

Country code should match ISO Alpha-2

Example:

location_id

string

Reference ID to a pre-configured location in Narvar

attribute

Object

string

Example:

{ "promotion": "bogo" }

billing

Object

amount

number

Total amount paid for the order

Example:

payments

Array

Contains the payment information about the order

Object

is_gift_card

string

Example:

true

merchant

string

Example:

VISA

method

string

Example:

swipe

expiration_date

string

Example:

02/19

billed_to

Object required

string

Example:

john.doe@narvar.com

first_name

string required

Example:

John

last_name

string required

Example:

Doe

phone

string

Example:

6501234567

address

Object required

street_1

string required

Example:

633 Folsom Street

street_2

string

Example:

Floor 2

city

string required

Example:

San Francisco

state

string required

Example:

zip

string required

This can be a US zip code, or any international postal code

Example:

94107

country

string required

Country code should match ISO Alpha-2

Example:

location_id

string

Reference ID to a pre-configured location in Narvar

tax_amount

number

Example:

12.5

tax_rate

number

Example:

9.8

shipping_handling

number

Example:

4.3

pickups

Array

Object

string required

Example:

1234

items_info

Array required

Object

item_id

string

Example:

ID123

sku

string required

Example:

DS234

quantity

integer required

Example:

status

Object required

code

string required

This will trigger different actions on the Narvar platform. Must follow the enums

Enumeration:

PROCESSING

The items are still processing

READY_FOR_CARRIER

The items are ready to be shipped through carrier

READY_FOR_PICKUP

The items are ready to be picked up from a location

PICKED_UP

The items have been picked up

DELAYED

The items have been delayed

NOT_PICKED_UP

The items did not get picked up

CANCELLED

The item has been cancelled

Example:

READY_FOR_PICKUP

message

string

A custom message can be passed and will be used with some Narvar products

Example:

Your order is ready to be picked up!

date

string required

The date the status changed. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-24T13:25:31Z

eta

string

The date when the order is expected to be ready to pickup. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-25T13:25:31Z

pickup_by_date

string

The by which the customer is required to pickup their order. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-03-01T13:25:31Z

attributes

Object

string

Example:

{ "promotion": "bogo" }

store

Object required

The store information where the items will be picked up

name

string

Example:

Peninsula Trading

string

Example:

2342

store_area

string

Example:

Side Door

address

Object required

street_1

string required

Example:

633 Folsom Street

street_2

string

Example:

Floor 2

city

string required

Example:

San Francisco

state

string required

Example:

zip

string required

This can be a US zip code, or any international postal code

Example:

94107

country

string required

Country code should match ISO Alpha-2

Example:

url

string

Example:

peninsulatrading.co

phone_number

string

Example:

(415) 486-8611

hours

Array

Example:

[
  {
    "open" : "0800",
    "close" : "2000"
  },
  {
    "open" : "0800",
    "close" : "2000"
  },
  {
    "open" : "0800",
    "close" : "2000"
  },
  {
    "open" : "0800",
    "close" : "2000"
  },
  {
    "open" : "0800",
    "close" : "2000"
  },
  {
    "open" : "0800",
    "close" : "2000"
  },
  {
    "open" : "0800",
    "close" : "2000"
  }
]

Object

open

string

carrier

string

If a carrier is used to deliver the package to a store then this can be passed to Narvar. Required if pickup type is BOSS, or carrier-based CONCIERGE

Example:

ups

tracking_number

string

Tracking number for the package being shipped to the store. Required if pickup type is BOSS, or carrier-based CONCIERGE

Example:

1Z4398734978453

ship_date

string

The date when the package was shipped to the store. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-23T13:25:31Z

type

string required

Type of this pickup

Enumeration:

CONCIERGE

If this is a concierge pickup

BOSS

If items need to be shipped from warehouse though carrier (Please make sure to include carrier and tracking_number in pickup object)

BOPIS

If items are already in store, and do not need to be shipped from warehouse

collection_token

string

The code or passphrase that may or may not be needed to pickup item(s) from a pickup point.

Example:

DRTQ42

customer

Object

customer_id

string required

A unique identifier for the customer

Example:

"78997234200222"

address

Object

street_1

string required

Example:

633 Folsom Street

street_2

string

Example:

Floor 2

city

string required

Example:

San Francisco

state

string required

Example:

zip

string required

This can be a US zip code, or any international postal code

Example:

94107

country

string required

Country code should match ISO Alpha-2

Example:

string

Example:

john.doe@narvar.com

first_name

string

Example:

John

last_name

string

Example:

Doe

phone

string

Example:

6501234567

customer_type

string

Example:

premium

customer_tier

string

Example:

bronze

notification_preferences

Array of string

Example:

["SMS","FACEBOOK_MESSENGER","HIPAA_SMS","FB","VOICE","WHATSAPP","HIPAA_EMAIL","EMAIL","LINE","WEBHOOK"]

attributes

Object

string

Example:

{ "promotion": "bogo" }

events

Array

Object

event

string

Enumeration:

MODIFIED

The order has been modified on this date/time

CANCELLED

The order has been CANCELLED

Example:

MODIFIED

date

string

Date/time of the event. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-25T13:25:31Z

currency_code

string

The currency code for the item price/cost in the order

Example:

USD

order_promise_date

string

If there was a deliver by date provided to the customer as it relates to the order. This information is typically passed at the item level. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-25T13:25:31Z

selected_ship_method

string

Shipment method selected at order checkout

Example:

Expedited

Responses

200 201

ITEM CREATED

Body

application/json

Object

status

string

Example:

SUCCESS

messages

Array

Object

code

string

Example:

response.status.success

message

string

Example:

Shipment information saved for order number 34252345

304 304

NOT MODIFIED

application/json

400 400

BAD REQUEST

Body

application/json

Object

status

string

Example:

FAILURE

messages

Array

Object

level

string

Example:

ERROR

code

string

Example:

order_info.order_items.is_backordered

message

string

Example:

Can not deserialize value of type java.lang.boolean from String

401 401

UNAUTHORIZED

application/json

403 403

FORBIDDEN

application/json

404 404

NOT FOUND

application/json

405 405

METHOD NOT ALLOWED

application/json

409 409

ITEM ALREADY EXISTS

application/json

500 500

INTERNAL SERVER ERROR

application/json

503 503

SERVICE UNAVAILABLE

application/json

Add Shipment

PUT https://ws-st01.narvar.qa/api/v1/orders/{order_number}/shipments HTTP/1.1 

Content-Type: application/json

{
  "order_info": {
    "order_number": "34252345",
    "order_date": "2021-02-24T13:25:31Z",
    "checkout_locale": "en_US",
    "currency_code": "USD",
    "status": "SHIPPED",
    "order_items": [{
      "categories": [
        "Clothing",
        "Shoes"
      ],
      "fulfillment_status": "SHIPPED",
      "is_final_sale": false,
      "item_image": "https://itemimageurl.png",
      "item_url": "https://item123.html",
      "name": "Red Shoes",
      "description": "Red Shoes - Size 10",
      "quantity": 2,
      "sku": "D2343122",
      "item_id": null,
      "unit_price": 32.99,
      "original_unit_price": 55.99,
      "line_price": 65.98,
      "original_line_price": 111.98,
      "color": "red",
      "size": "10",
      "style": "low-tops",
      "attributes": {
        "pattern": "zebra"
      }
    },
    {
      "categories": [
        "Clothing",
        "Tops"
      ],
      "fulfillment_status": "SHIPPED",
      "is_final_sale": false,
      "item_image": "https://itemimageurl.png",
      "item_url": "https://item123.html",
      "name": "Blue shirt",
      "description": "Blue striped shirt",
      "quantity": 1,
      "sku": "F432423",
      "item_id": null,
      "unit_price": 59.99,
      "original_unit_price": 75.99,
      "line_price": 59.99,
      "original_line_price": 76.99,
      "color": "blue",
      "size": "medium",
      "style": "retro",
      "attributes": {
        "pattern": "striped"
      }
    }],
    "shipments": [{
      "items_info": [{
        "sku": "D2343122",
        "quantity": 2
      },
      {
        "sku": "F432423",
        "quantity": 1
      }],
      "ship_method": "Standard",
      "carrier": "UPS",
      "carrier_service": "GR",
      "ship_source": "DCWest",
      "ship_date": "2021-02-25T13:25:31Z",
      "ship_discount": 5.00,
      "ship_tax": 10.00,
      "ship_total": 15.00,
      "promise_date": "2021-03-01T09:00:00Z",
      "tracking_number": "1Z517757671802283",
      "shipped_from": {
        "company_name": "Acme International",
        "email": "john.doe@narvar.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "6501234567",
        "address": {
          "street_1": "633 Folsom Street",
          "street_2": "Floor 2",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94107",
          "country": "US"
        }
      },
      "shipped_to": {
        "email": "john.doe@narvar.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "6501234567",
        "address": {
          "street_1": "633 Folsom Street",
          "street_2": "Floor 2",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94107",
          "country": "US"
        }
      }
    }]
  }
}

HTTP/1.1 200 Created 

Content-Type: application/json

{
    "status": "SUCCESS",
    "messages": [
        {
            "code": "response.status.success",
            "message": "Shipment information saved for order number 34252345"
        }
    ]
}

GET /orders/{order_number}

Authentication

basicAuth

This operation is used to retrieve order details

Path variables

order_number

string required

pass the order number

Responses

200 200

Returns details about the order specified

Body

application/json

Object

order_info

Object

order_number

string

Example:

34252345

order_date

string

Example:

2018-02-24T13:25:31Z

order_items

Array

Object

categories

Array

The categories the product falls under

string

Example:

Clothing

is_backordered

boolean

Whether or not the item is backordered

Example:

false

vendors

Array

Object

phone

string required

The vendor’s phone number

Example:

1-888-555-4433

name

string required

Vendor name

Example:

Stevensen Fabrics

string

Vendor email

Example:

johndoe@example.com

type

string

Describes the type of vendor

Example:

Drop Ship

address

Object required

street_1

string required

Example:

633 Folsom Street

street_2

string

Example:

Floor 2

city

string required

Example:

San Francisco

state

string required

Example:

zip

string required

This can be a US zip code, or any international postal code

Example:

94107

country

string required

Country code should match ISO Alpha-2

Example:

description

string

The description of the item

Example:

Red Shoe made by designer

discount_amount

number

Example:

discount_percent

number

The percentage that the item was discounted

Example:

final_sale_date

string

The date when the order item went on final sale. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-25T13:25:31Z

fulfillment_status

string required

Used to determine what fulfillment state the item is in when the order is created or updated. NOT_SHIPPED should persist until all of the quantity of the line item has been shipped

Enumeration:

NOT_SHIPPED

The item has yet to be shipped

SHIPPED

The item has shipped

CANCELLED

The item has been cancelled

RETURNED

The item has been returned

PROCESSING

The item is still processing

READY_FOR_PICKUP

The item is ready to be picked up from a location

DELAYED

The item has been delayed

PICKED_UP

The item has been picked up

NOT_PICKED_UP

The item did not get picked up

Example:

NOT_SHIPPED

is_final_sale

boolean

True is the item is not returnable. False if it is returnable

Example:

false

is_gift

boolean

True if the item was purchased as a gift

Example:

false

item_id

string

Required if the same SKU is sent in two different item object and is used as the unique identifier of the record

Example:

43582

item_image

string required

The image that should be used for the item

Example:

https://itemimageurl.png

item_promise_date

string

The promise date associated with the item

Example:

2018-02-25T13:25:31Z

item_url

string required

The URL that will direct back to the product page

Example:

https://item123.html

line_number

number

The line number of the item from the OMS system

Example:

name

string required

A title or name of the order item

Example:

Red Shoe

quantity

number required

The number of the item that has been purchased

Example:

sku

string required

A unique sku for this product item

Example:

D2343122

unit_price

number required

This is the price that will be shown to the end user as what they paid for the product

Example:

fulfillment_type

string

Enumeration:

Home delivery

BOPIS

Buy online pick up in store

BOSS

Buy online ship to store

Example:

dimensions

Object

Describes the dimensions of an item

uom

string

Example:

length

number

Example:

width

number

Example:

height

number

Example:

weight

number

Example:

weight_uom

string

Example:

lbs

attributes

Object

string

Example:

{ "promotion": "bogo" }

events

Array

Object

event

string required

Enumeration:

PRESHIPMENT

CANCELLED

The item has been cancelLed

RETURNED_BY_MAIL

The item has been returned by mail without using the Narvar platform

RETURNED_TO_STORE

The item has been returned to the store without using the Narvar platform

NON_RETURNABLE

The item should not be allowed to be returned because of something that occurred after delivery

DELIVERY_EXCEPTION

The item did not make it to the end user because of an issue that occurred while in-transit

RETURNED_NARVAR

CURRENT_RETURNABLE_QTY

MODIFIED

The item has been modified on this date/time

Example:

CANCELLED

quantity

integer required

The number of the items that are in the event state

Example:

sequence

integer

This can be used to show the order of events. Mainly used to show the order of preshipment statuses on the Narvar tracking pages

Example:

date

string

Date/time of the event. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-25T13:25:31Z

anticipated_ship_date

string

The date when the order item should be shipped. This field is used to capture the anticipated date of shipping, the actual ship date when the item is shipped is captured in the shipments object

original_unit_price

number

The original price for the unit without discounts and/or promotions applied, otherwise known as the strikethrough price.

Example:

original_line_price

number

The total original price for the order line, without discounts and/or promotions applied, otherwise known as the strikethrough line price.

Example:

238

line_price

number

The total price for the order line with discounts and/or promotions applied.

Example:

224

narvar_convert_id

string

ID of the request to Narvar Convert that was displayed to the end user. This is used for analytics and monitoring of Narvar Convert product

item_type

string

Used to describe the item type.

Enumeration:

PHYSICAL

Physical item - Default

DIGITAL

Digital item

is_hazmat

boolean

Indicates whether it is a hazmat item or not.

Examples:

truefalse

hazmat_codes

Array of string

List of hazmat codes

Example:

[
    "UN3480", "GHS02"
]

string

shipments

Array

Object

items_info

Array required

Contains the items within the shipment. Must match items passed under order_items

Object

item_id

string

Example:

ID123

sku

string

Example:

DS234

quantity

integer

Example:

ship_method

string

Example:

Standard

carrier

string required

Example:

UPS

carrier_service

string

Example:

promise_date

string

Retailer’s promise date for items in the shipment. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2021-02-25T13:25:31Z

ship_source

string

Example:

DCWest

ship_date

string required

The date the items were shipped. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2021-02-25T13:25:31Z

ship_discount

number

Example:

ship_tax

number

Example:

ship_total

number

Example:

100

tracking_number

string required

Example:

1Z517757671802283

shipped_from

Object

company_name

string

Example:

Acme International

string

Example:

john.doe@narvar.com

first_name

string

Example:

John

last_name

string

Example:

Doe

phone

string

Example:

6501234567

address

Object

street_1

string required

Example:

633 Folsom Street

street_2

string

Example:

Floor 2

city

string required

Example:

San Francisco

state

string required

Example:

zip

string required

This can be a US zip code, or any international postal code

Example:

94107

country

string required

Country code should match ISO Alpha-2

Example:

location_id

string

Reference to a pre-configured location id in Narvar

shipped_to

Object required

string

Example:

john.doe@narvar.com

first_name

string required

Example:

John

last_name

string required

Example:

Doe

phone

string

Example:

6501234567

address

Object required

street_1

string required

Example:

633 Folsom Street

street_2

string

Example:

Floor 2

city

string required

Example:

San Francisco

state

string required

Example:

zip

string required

This can be a US zip code, or any international postal code

Example:

94107

country

string required

Country code should match ISO Alpha-2

Example:

location_id

string

Reference ID to a pre-configured location in Narvar

attribute

Object

string

Example:

{ "promotion": "bogo" }

billing

Object

amount

number

Total amount paid for the order

Example:

payments

Array

Contains the payment information about the order

Object

is_gift_card

string

Example:

true

merchant

string

Example:

VISA

method

string

Example:

swipe

expiration_date

string

Example:

02/19

billed_to

Object required

string

Example:

john.doe@narvar.com

first_name

string required

Example:

John

last_name

string required

Example:

Doe

phone

string

Example:

6501234567

address

Object required

street_1

string required

Example:

633 Folsom Street

street_2

string

Example:

Floor 2

city

string required

Example:

San Francisco

state

string required

Example:

zip

string required

This can be a US zip code, or any international postal code

Example:

94107

country

string required

Country code should match ISO Alpha-2

Example:

location_id

string

Reference ID to a pre-configured location in Narvar

tax_amount

number

Example:

12.5

tax_rate

number

Example:

9.8

shipping_handling

number

Example:

4.3

pickups

Array

Object

string required

Example:

1234

items_info

Array required

Object

item_id

string

Example:

ID123

sku

string required

Example:

DS234

quantity

integer required

Example:

status

Object required

code

string required

This will trigger different actions on the Narvar platform. Must follow the enums

Enumeration:

PROCESSING

The items are still processing

READY_FOR_CARRIER

The items are ready to be shipped through carrier

READY_FOR_PICKUP

The items are ready to be picked up from a location

PICKED_UP

The items have been picked up

DELAYED

The items have been delayed

NOT_PICKED_UP

The items did not get picked up

CANCELLED

The item has been cancelled

Example:

READY_FOR_PICKUP

message

string

A custom message can be passed and will be used with some Narvar products

Example:

Your order is ready to be picked up!

date

string required

The date the status changed. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-24T13:25:31Z

eta

string

The date when the order is expected to be ready to pickup. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-25T13:25:31Z

pickup_by_date

string

The by which the customer is required to pickup their order. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-03-01T13:25:31Z

attributes

Object

string

Example:

{ "promotion": "bogo" }

store

Object required

The store information where the items will be picked up

name

string

Example:

Peninsula Trading

string

Example:

2342

store_area

string

Example:

Side Door

address

Object required

street_1

string required

Example:

633 Folsom Street

street_2

string

Example:

Floor 2

city

string required

Example:

San Francisco

state

string required

Example:

zip

string required

This can be a US zip code, or any international postal code

Example:

94107

country

string required

Country code should match ISO Alpha-2

Example:

url

string

Example:

peninsulatrading.co

phone_number

string

Example:

(415) 486-8611

hours

Array

Example:

[
  {
    "open" : "0800",
    "close" : "2000"
  },
  {
    "open" : "0800",
    "close" : "2000"
  },
  {
    "open" : "0800",
    "close" : "2000"
  },
  {
    "open" : "0800",
    "close" : "2000"
  },
  {
    "open" : "0800",
    "close" : "2000"
  },
  {
    "open" : "0800",
    "close" : "2000"
  },
  {
    "open" : "0800",
    "close" : "2000"
  }
]

Object

open

string

carrier

string

If a carrier is used to deliver the package to a store then this can be passed to Narvar. Required if pickup type is BOSS, or carrier-based CONCIERGE

Example:

ups

tracking_number

string

Tracking number for the package being shipped to the store. Required if pickup type is BOSS, or carrier-based CONCIERGE

Example:

1Z4398734978453

ship_date

string

The date when the package was shipped to the store. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-23T13:25:31Z

type

string required

Type of this pickup

Enumeration:

CONCIERGE

If this is a concierge pickup

BOSS

If items need to be shipped from warehouse though carrier (Please make sure to include carrier and tracking_number in pickup object)

BOPIS

If items are already in store, and do not need to be shipped from warehouse

collection_token

string

The code or passphrase that may or may not be needed to pickup item(s) from a pickup point.

Example:

DRTQ42

customer

Object

customer_id

string required

A unique identifier for the customer

Example:

"78997234200222"

address

Object

street_1

string required

Example:

633 Folsom Street

street_2

string

Example:

Floor 2

city

string required

Example:

San Francisco

state

string required

Example:

zip

string required

This can be a US zip code, or any international postal code

Example:

94107

country

string required

Country code should match ISO Alpha-2

Example:

string

Example:

john.doe@narvar.com

first_name

string

Example:

John

last_name

string

Example:

Doe

phone

string

Example:

6501234567

customer_type

string

Example:

premium

customer_tier

string

Example:

bronze

notification_preferences

Array of string

Example:

["SMS","FACEBOOK_MESSENGER","HIPAA_SMS","FB","VOICE","WHATSAPP","HIPAA_EMAIL","EMAIL","LINE","WEBHOOK"]

attributes

Object

string

Example:

{ "promotion": "bogo" }

events

Array

Object

event

string

Enumeration:

MODIFIED

The order has been modified on this date/time

CANCELLED

The order has been CANCELLED

Example:

MODIFIED

date

string

Date/time of the event. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-25T13:25:31Z

currency_code

string

Example:

USD

order_promise_date

string

Example:

2018-02-25T13:25:31Z

selected_ship_method

string

Example:

Expedited

status

string

Example:

SUCCESS

messages

Array

Object

code

string

Example:

response.status.success

201 201

CREATED

application/json

304 304

NOT MODIFIED

application/json

400 400

BAD REQUEST

application/json

401 401

UNAUTHORIZED

application/json

403 403

FORBIDDEN

application/json

404 404

NOT FOUND

application/json

405 405

METHOD NOT ALLOWED

application/json

500 500

INTERNAL SERVER ERROR

application/json

503 503

SERVICE UNAVAILABLE

application/json

Example Response

GET https://ws-st01.narvar.qa/api/v1/orders/34252345 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "order_info": {
    "order_number": "34252345",
    "order_date": "2018-02-24T13:25:31Z",
    "checkout_locale": "en_US",
    "currency_code": "USD",
    "status": "SHIPPED",
    "order_items": [
     {
      "categories": [
        "Clothing",
        "Shoes"
      ],
      "fulfillment_status": "SHIPPED",
      "is_final_sale": false,
      "item_image": "https://itemimageurl.png",
      "item_url": "https://item123.html",
      "name": "Red Shoes",
      "description": "Red Shoes - Size 10",
      "quantity": 2,
      "sku": "D2343122",
      "item_id": null,
      "unit_price": 32.99,
      "original_unit_price": 55.99,
      "line_price": 65.98,
      "original_line_price": 111.98,
      "color": "red",
      "size": "10",
      "style": "low-tops",
      "attributes": {
        "pattern": "zebra"
      }
     },
     {
      "categories": [
        "Clothing",
        "Tops"
      ],
      "fulfillment_status": "SHIPPED",
      "is_final_sale": false,
      "item_image": "https://itemimageurl.png",
      "item_url": "https://item123.html",
      "name": "Blue shirt",
      "description": "Blue striped shirt",
      "quantity": 1,
      "sku": "F432423",
      "item_id": null,
      "unit_price": 59.99,
      "original_unit_price": 75.99,
      "line_price": 59.99,
      "original_line_price": 76.99,
      "color": "blue",
      "size": "medium",
      "style": "retro",
      "attributes": {
        "pattern": "striped"
      }
     }
    ],
    "billing": {
      "amount": 30.00,
      "payments": [
        {
          "is_gift_card": true,
          "merchant": "VISA",
          "method": "swipe",
          "expiration_date": "02/19"
        }
      ],
      "billed_to": {
        "email": "john.doe@narvar.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "6501234567",
        "address": {
          "street_1": "633 Folsom Street",
          "street_2": "Floor 2",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94107",
          "country": "US"
        }
      },
      "tax_amount": 12.50,
      "tax_rate": 9.8,
      "shipping_handling": 4.30
    },
    "customer": {
      "customer_id": "78997234200222",
      "address": {
        "street_1": "633 Folsom Street",
        "street_2": "Floor 2",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94107",
        "country": "US"
      },
      "email": "john.doe@narvar.com",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "6501234567",
      "customer_type": "premium"
    },
    "attributes": {
      "promotion": "bogo",
      "checkout_brand": "peninsula",
      "checkout_language": "en",
      "checkout_country": "US"
    },
    "shipments": [
      {
        "items_info": [
          {
            "sku": "D2343122",
            "quantity": 1
          }
        ],
        "ship_method": "Standard",
        "carrier": "UPS",
        "carrier_service": "GR",
        "ship_source": "DCWest",
        "ship_date": "2018-02-25T13:25:31Z",
        "ship_discount": 5.00,
        "ship_tax": 10.00,
        "ship_total": 100.00,
        "tracking_number": "1Z517757671802283",
        "shipped_from": {
          "company_name": "Acme International",
          "email": "john.doe@narvar.com",
          "first_name": "John",
          "last_name": "Doe",
          "phone": "6501234567",
          "address": {
            "street_1": "633 Folsom Street",
            "street_2": "Floor 2",
            "city": "San Francisco",
            "state": "CA",
            "zip": "94107",
            "country": "US"
          }
        },
        "shipped_to": {
          "email": "john.doe@narvar.com",
          "first_name": "John",
          "last_name": "Doe",
          "phone": "6501234567",
          "address": {
            "street_1": "633 Folsom Street",
            "street_2": "Floor 2",
            "city": "San Francisco",
            "state": "CA",
            "zip": "94107",
            "country": "US"
          }
        }
      }
    ],
    "promotions": [
  {
    "promotion": "New Customer Special",
    "value": "-$3.5"
  },
  {
    "promotion": "Valentine's Day",
    "value": "Applied"
  }
],
    "notification_preferences": {
      "optins": [
        {
          "channel": "sms",
          "contact": "+11234567890"
        },
        {
          "channel": "whatsapp",
          "contact": "somewhatsappid"
        }
      ]
    }
  }
},
  "status": "SUCCESS",
  "messages": [{
    "code": "response.status.success"
  }]
}

Descriptions of each object type of the API

Item specific information for the order

Array

Object

categories

Array

The categories the product falls under

string

Example:

Clothing

is_backordered

boolean

Whether or not the item is backordered

Example:

false

vendors

Array

Object

phone

string required

The vendor’s phone number

Example:

1-888-555-4433

name

string required

Vendor name

Example:

Stevensen Fabrics

string

Vendor email

Example:

johndoe@example.com

type

string

Describes the type of vendor

Example:

Drop Ship

address

Object required

street_1

string required

Example:

633 Folsom Street

street_2

string

Example:

Floor 2

city

string required

Example:

San Francisco

state

string required

Example:

zip

string required

This can be a US zip code, or any international postal code

Example:

94107

country

string required

Country code should match ISO Alpha-2

Example:

description

string

The description of the item

Example:

Red Shoe made by designer

discount_amount

number

Example:

discount_percent

number

The percentage that the item was discounted

Example:

final_sale_date

string

The date when the order item went on final sale. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-25T13:25:31Z

fulfillment_status

string required

Used to determine what fulfillment state the item is in when the order is created or updated. NOT_SHIPPED should persist until all of the quantity of the line item has been shipped

Enumeration:

NOT_SHIPPED

The item has yet to be shipped

SHIPPED

The item has shipped

CANCELLED

The item has been cancelled

RETURNED

The item has been returned

PROCESSING

The item is still processing

READY_FOR_PICKUP

The item is ready to be picked up from a location

DELAYED

The item has been delayed

PICKED_UP

The item has been picked up

NOT_PICKED_UP

The item did not get picked up

Example:

NOT_SHIPPED

is_final_sale

boolean

True is the item is not returnable. False if it is returnable

Example:

false

is_gift

boolean

True if the item was purchased as a gift

Example:

false

item_id

string

Required if the same SKU is sent in two different item object and is used as the unique identifier of the record

Example:

43582

item_image

string required

The image that should be used for the item

Example:

https://itemimageurl.png

item_promise_date

string

The promise date associated with the item

Example:

2018-02-25T13:25:31Z

item_url

string required

The URL that will direct back to the product page

Example:

https://item123.html

line_number

number

The line number of the item from the OMS system

Example:

name

string required

A title or name of the order item

Example:

Red Shoe

quantity

number required

The number of the item that has been purchased

Example:

sku

string required

A unique sku for this product item

Example:

D2343122

unit_price

number required

This is the price that will be shown to the end user as what they paid for the product

Example:

fulfillment_type

string

Enumeration:

Home delivery

BOPIS

Buy online pick up in store

BOSS

Buy online ship to store

Example:

dimensions

Object

Describes the dimensions of an item

uom

string

Example:

length

number

Example:

width

number

Example:

height

number

Example:

weight

number

Example:

weight_uom

string

Example:

lbs

attributes

Object

string

Example:

{ "promotion": "bogo" }

events

Array

Object

event

string required

Enumeration:

PRESHIPMENT

CANCELLED

The item has been cancelLed

RETURNED_BY_MAIL

The item has been returned by mail without using the Narvar platform

RETURNED_TO_STORE

The item has been returned to the store without using the Narvar platform

NON_RETURNABLE

The item should not be allowed to be returned because of something that occurred after delivery

DELIVERY_EXCEPTION

The item did not make it to the end user because of an issue that occurred while in-transit

RETURNED_NARVAR

CURRENT_RETURNABLE_QTY

MODIFIED

The item has been modified on this date/time

Example:

CANCELLED

quantity

integer required

The number of the items that are in the event state

Example:

sequence

integer

This can be used to show the order of events. Mainly used to show the order of preshipment statuses on the Narvar tracking pages

Example:

date

string

Date/time of the event. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-25T13:25:31Z

anticipated_ship_date

string

The date when the order item should be shipped. This field is used to capture the anticipated date of shipping, the actual ship date when the item is shipped is captured in the shipments object

original_unit_price

number

The original price for the unit without discounts and/or promotions applied, otherwise known as the strikethrough price.

Example:

original_line_price

number

The total original price for the order line, without discounts and/or promotions applied, otherwise known as the strikethrough line price.

Example:

238

line_price

number

The total price for the order line with discounts and/or promotions applied.

Example:

224

narvar_convert_id

string

ID of the request to Narvar Convert that was displayed to the end user. This is used for analytics and monitoring of Narvar Convert product

item_type

string

Used to describe the item type.

Enumeration:

PHYSICAL

Physical item - Default

DIGITAL

Digital item

is_hazmat

boolean

Indicates whether it is a hazmat item or not.

Examples:

truefalse

hazmat_codes

Array of string

List of hazmat codes

Example:

[
    "UN3480", "GHS02"
]

string

Methods: GET - Retrieve Order POST - Create/Update Orders PUT - Create/Update Shipments

Simple Item

Additional Info

[{
  "description": "Red Shoe made by designer",
  "fulfillment_status": "NOT_SHIPPED",
  "is_final_sale": false,
  "item_id": "43582",
  "item_image": "https://itemimageurl.png",
  "item_url": "https://item123.html",
  "name": "Red Shoe",
  "quantity": 7,
  "sku": "D2343122",
  "unit_price": 32
}]

[{
  "categories": [
    "Clothing"
  ],
  "is_backordered": true,
  "vendors": [{
    "phone": "1-888-555-4433",
    "name": "Stevensen Fabrics",
    "email": "johndoe@example.com",
    "type": "Drop Ship",
    "address": {
      "street_1": "633 Folsom Street",
      "street_2": "Floor 2",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94107",
      "country": "US"
    }
  }],
  "description": "Red Shoe made by designer",
  "discount_amount": 10.00,
  "discount_percent": 5.00,
  "final_sale_date": "2018-02-25T13:25:31Z",
  "fulfillment_status": "SHIPPED",
  "is_final_sale": true,
  "is_gift": true,
  "item_id": "43582",
  "item_image": "https://itemimageurl.png",
  "item_promise_date": "2018-02-25T13:25:31Z",
  "anticipated_ship_date": "2018-02-22T13:25:31Z",
  "item_url": "https://item123.html",
  "line_number": 1,
  "name": "Red Shoe",
  "quantity": 7,
  "sku": "D2343122",
  "unit_price": 32,
  "original_unit_price": 34,
  "original_line_price": 238,
  "line_price": 224,
  "fulfillment_type": "HD",
  "item_type": "PHYSICAL",
  "is_hazmat": true,
  "hazmat_codes": [
    "UN3480", "UN3481"
  ],
  "dimension": {
    "uom": "in",
    "length": 10.00,
    "width": 5.00,
    "height": 7.00,
    "weight": 25.00,
    "weight_uom": "lbs"
  },
  "attributes": {
    "color": "red",
    "size": "small"
  },
  "events": [{
    "event": "CANCELLED",
    "quantity": 4
  }]
}]

The list of shipments for the order containing which items are in each package

Array

Object

items_info

Array required

Contains the items within the shipment. Must match items passed under order_items

Object

item_id

string

Example:

ID123

sku

string

Example:

DS234

quantity

integer

Example:

ship_method

string

Example:

Standard

carrier

string required

Example:

UPS

carrier_service

string

Example:

promise_date

string

Retailer’s promise date for items in the shipment. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2021-02-25T13:25:31Z

ship_source

string

Example:

DCWest

ship_date

string required

The date the items were shipped. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2021-02-25T13:25:31Z

ship_discount

number

Example:

ship_tax

number

Example:

ship_total

number

Example:

100

tracking_number

string required

Example:

1Z517757671802283

shipped_from

Object

company_name

string

Example:

Acme International

string

Example:

john.doe@narvar.com

first_name

string

Example:

John

last_name

string

Example:

Doe

phone

string

Example:

6501234567

address

Object

street_1

string required

Example:

633 Folsom Street

street_2

string

Example:

Floor 2

city

string required

Example:

San Francisco

state

string required

Example:

zip

string required

This can be a US zip code, or any international postal code

Example:

94107

country

string required

Country code should match ISO Alpha-2

Example:

location_id

string

Reference to a pre-configured location id in Narvar

shipped_to

Object required

string

Example:

john.doe@narvar.com

first_name

string required

Example:

John

last_name

string required

Example:

Doe

phone

string

Example:

6501234567

address

Object required

street_1

string required

Example:

633 Folsom Street

street_2

string

Example:

Floor 2

city

string required

Example:

San Francisco

state

string required

Example:

zip

string required

This can be a US zip code, or any international postal code

Example:

94107

country

string required

Country code should match ISO Alpha-2

Example:

location_id

string

Reference ID to a pre-configured location in Narvar

attribute

Object

string

Example:

{ "promotion": "bogo" }

Methods: GET - Retrieve Order POST - Create/Update Orders PUT - Create/Update Shipments

Single Shipment

Multi Shipment

[{
  "items_info": [{
    "sku": "DS234",
    "quantity": 1
  }],
  "ship_method": "Standard",
  "carrier": "UPS",
  "carrier_service": "Gr",
  "ship_source": "DCWest",
  "ship_date": "2021-02-25T13:25:31Z",
  "ship_discount": 5.00,
  "ship_tax": 10.00,
  "ship_total": 15.00,
  "promise_date": "2021-03-01T15:00:00Z",
  "tracking_number": "1Z517757671802283",
  "shipped_from": {
    "company_name": "Acme International",
    "email": "john.doe@narvar.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "6501234567",
    "address": {
      "street_1": "633 Folsom Street",
      "street_2": "Floor 2",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94107",
      "country": "US"
    }
  },
  "shipped_to": {
    "email": "john.doe@narvar.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "6501234567",
    "address": {
      "street_1": "633 Folsom Street",
      "street_2": "Floor 2",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94107",
      "country": "US"
    }
  }
}]

[{
  "items_info": [{
    "sku": "DS234",
    "quantity": 1
  }],
  "ship_method": "Standard",
  "carrier": "UPS",
  "carrier_service": "UG",
  "ship_source": "DCWest",
  "ship_date": "2021-02-25T13:25:31Z",
  "ship_discount": 5.00,
  "ship_tax": 10.00,
  "ship_total": 100.00,
  "promise_date": "2021-03-01T15:00:00Z",
  "tracking_number": "1Z517757671802283",
  "shipped_from": {
    "company_name": "Acme International",
    "email": "john.doe@narvar.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "6501234567",
    "address": {
      "street_1": "633 Folsom Street",
      "street_2": "Floor 2",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94107",
      "country": "US"
    }
  },
  "shipped_to": {
    "email": "john.doe@narvar.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "6501234567",
    "address": {
      "street_1": "633 Folsom Street",
      "street_2": "Floor 2",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94107",
      "country": "US"
    }
  }
}, {
  "items_info": [{
    "sku": "DS2345",
    "quantity": 1
  }],
  "ship_method": "Standard",
  "carrier": "Fedex",
  "carrier_service": "UG",
  "ship_source": "DCWest",
  "ship_date": "2021-02-28T07:11:14Z",
  "ship_discount": 5.00,
  "ship_tax": 10.00,
  "ship_total": 100.00,
  "promise_date": "2021-03-05T18:00:00Z",
  "tracking_number": "94837661109933",
  "shipped_from": {
    "company_name": "Acme International",
    "email": "john.doe@narvar.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "6501234567",
    "address": {
      "street_1": "633 Folsom Street",
      "street_2": "Floor 2",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94107",
      "country": "US"
    }
  },
  "shipped_to": {
    "email": "john.doe@narvar.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "6501234567",
    "address": {
      "street_1": "633 Folsom Street",
      "street_2": "Floor 2",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94107",
      "country": "US"
    }
  }
}]

The billing object is used to send Narvar required information about how the order was paid for by the end user

Object

amount

number

Total amount paid for the order

Example:

payments

Array

Contains the payment information about the order

Object

is_gift_card

string

Example:

true

merchant

string

Example:

VISA

method

string

Example:

swipe

expiration_date

string

Example:

02/19

billed_to

Object required

string

Example:

john.doe@narvar.com

first_name

string required

Example:

John

last_name

string required

Example:

Doe

phone

string

Example:

6501234567

address

Object required

street_1

string required

Example:

633 Folsom Street

street_2

string

Example:

Floor 2

city

string required

Example:

San Francisco

state

string required

Example:

zip

string required

This can be a US zip code, or any international postal code

Example:

94107

country

string required

Country code should match ISO Alpha-2

Example:

location_id

string

Reference ID to a pre-configured location in Narvar

tax_amount

number

Example:

12.5

tax_rate

number

Example:

9.8

shipping_handling

number

Example:

4.3

Methods: GET - Retrieve Order POST - Create/Update Orders PUT - Create/Update Shipments

Example

{
  "amount": 30.00,
  "payments": [{
    "is_gift_card": true,
    "merchant": "VISA",
    "method": "swipe",
    "expiration_date": "02/19"
  }],
  "billed_to": {
    "email": "john.doe@narvar.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "6501234567",
    "address": {
      "street_1": "633 Folsom Street",
      "street_2": "Floor 2",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94107",
      "country": "US"
    }
  },
  "tax_amount": 12.50,
  "tax_rate": 9.8,
  "shipping_handling": 4.30
}

Information relating to the customer who placed the order

Object

customer_id

string required

A unique identifier for the customer

Example:

"78997234200222"

address

Object

street_1

string required

Example:

633 Folsom Street

street_2

string

Example:

Floor 2

city

string required

Example:

San Francisco

state

string required

Example:

zip

string required

This can be a US zip code, or any international postal code

Example:

94107

country

string required

Country code should match ISO Alpha-2

Example:

string

Example:

john.doe@narvar.com

first_name

string

Example:

John

last_name

string

Example:

Doe

phone

string

Example:

6501234567

customer_type

string

Example:

premium

customer_tier

string

Example:

bronze

notification_preferences

Array of string

Example:

["SMS","FACEBOOK_MESSENGER","HIPAA_SMS","FB","VOICE","WHATSAPP","HIPAA_EMAIL","EMAIL","LINE","WEBHOOK"]

Methods: GET - Retrieve Order POST - Create/Update Orders PUT - Create/Update Shipments

Example

{
  "customer_id": "78997234200222",
  "address": {
    "street_1": "633 Folsom Street",
    "street_2": "Floor 2",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94107",
    "country": "US"
  },
  "email": "john.doe@narvar.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "6501234567",
  "customer_type": "premium"
}

The pickups object associated with items to be picked up in store

Array

Object

string required

Example:

1234

items_info

Array required

Object

item_id

string

Example:

ID123

sku

string required

Example:

DS234

quantity

integer required

Example:

status

Object required

code

string required

This will trigger different actions on the Narvar platform. Must follow the enums

Enumeration:

PROCESSING

The items are still processing

READY_FOR_CARRIER

The items are ready to be shipped through carrier

READY_FOR_PICKUP

The items are ready to be picked up from a location

PICKED_UP

The items have been picked up

DELAYED

The items have been delayed

NOT_PICKED_UP

The items did not get picked up

CANCELLED

The item has been cancelled

Example:

READY_FOR_PICKUP

message

string

A custom message can be passed and will be used with some Narvar products

Example:

Your order is ready to be picked up!

date

string required

The date the status changed. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-24T13:25:31Z

eta

string

The date when the order is expected to be ready to pickup. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-25T13:25:31Z

pickup_by_date

string

The by which the customer is required to pickup their order. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-03-01T13:25:31Z

attributes

Object

string

Example:

{ "promotion": "bogo" }

store

Object required

The store information where the items will be picked up

name

string

Example:

Peninsula Trading

string

Example:

2342

store_area

string

Example:

Side Door

address

Object required

street_1

string required

Example:

633 Folsom Street

street_2

string

Example:

Floor 2

city

string required

Example:

San Francisco

state

string required

Example:

zip

string required

This can be a US zip code, or any international postal code

Example:

94107

country

string required

Country code should match ISO Alpha-2

Example:

url

string

Example:

peninsulatrading.co

phone_number

string

Example:

(415) 486-8611

hours

Array

Example:

[
  {
    "open" : "0800",
    "close" : "2000"
  },
  {
    "open" : "0800",
    "close" : "2000"
  },
  {
    "open" : "0800",
    "close" : "2000"
  },
  {
    "open" : "0800",
    "close" : "2000"
  },
  {
    "open" : "0800",
    "close" : "2000"
  },
  {
    "open" : "0800",
    "close" : "2000"
  },
  {
    "open" : "0800",
    "close" : "2000"
  }
]

Object

open

string

carrier

string

If a carrier is used to deliver the package to a store then this can be passed to Narvar. Required if pickup type is BOSS, or carrier-based CONCIERGE

Example:

ups

tracking_number

string

Tracking number for the package being shipped to the store. Required if pickup type is BOSS, or carrier-based CONCIERGE

Example:

1Z4398734978453

ship_date

string

The date when the package was shipped to the store. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-23T13:25:31Z

type

string required

Type of this pickup

Enumeration:

CONCIERGE

If this is a concierge pickup

BOSS

If items need to be shipped from warehouse though carrier (Please make sure to include carrier and tracking_number in pickup object)

BOPIS

If items are already in store, and do not need to be shipped from warehouse

collection_token

string

The code or passphrase that may or may not be needed to pickup item(s) from a pickup point.

Example:

DRTQ42

Methods: GET - Retrieve Order POST - Create/Update Orders PUT - Create/Update Shipments

Example

[
    {
        "id": "1234",
        "items_info": [
            {
                "sku": "DS234",
                "quantity": 1
            }
        ],
        "status": {
            "code": "READY_FOR_PICKUP",
            "message": "Your order is ready to be picked up!",
            "date": "2018-02-24T13:25:31Z"
        },
        "eta": "2018-02-25T13:25:31Z",
        "pickup_by_date": "2018-03-01T13:25:31Z",
        "store": {
            "name": "Peninsula Trading",
            "id": 2342,
            "store_area": "Side Door",
            "address": {
                "street_1": "633 Folsom Street",
                "street_2": "Floor 2",
                "city": "San Francisco",
                "state": "CA",
                "zip": "94107",
                "country": "US"
            },
            "url": "peninsulatrading.co",
            "phone_number": "(415) 486-8611",
            "hours": [
                {
                    "open": "",
                    "close": ""
                }
            ]
        },
        "carrier": "ups",
        "tracking_number": "1Z4398734978453",
        "ship_date": "2018-02-23T13:25:31Z",
        "type": "BOSS"
    }
]

Events that relate to an order. This can be used to send Narvar information about an order after it has been created

Array

Object

event

string

Enumeration:

MODIFIED

The order has been modified on this date/time

CANCELLED

The order has been CANCELLED

Example:

MODIFIED

date

string

Date/time of the event. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-25T13:25:31Z

Methods: GET - Retrieve Order POST - Create/Update Orders PUT - Create/Update Shipments

Example 1

[{
  "event": "MODIFIED",
  "date": "2018-02-25T13:25:31Z"
}]

Events that relate to an item. This can be used to send Narvar information about an item after it has been created

Array

Object

event

string required

Enumeration:

PRESHIPMENT

CANCELLED

The item has been cancelLed

RETURNED_BY_MAIL

The item has been returned by mail without using the Narvar platform

RETURNED_TO_STORE

The item has been returned to the store without using the Narvar platform

NON_RETURNABLE

The item should not be allowed to be returned because of something that occurred after delivery

DELIVERY_EXCEPTION

The item did not make it to the end user because of an issue that occurred while in-transit

RETURNED_NARVAR

CURRENT_RETURNABLE_QTY

MODIFIED

The item has been modified on this date/time

Example:

CANCELLED

quantity

integer required

The number of the items that are in the event state

Example:

sequence

integer

This can be used to show the order of events. Mainly used to show the order of preshipment statuses on the Narvar tracking pages

Example:

date

string

Date/time of the event. All dates and times are expressed in ISO 8601, with a UTC offset (denoted by the Z)

Example:

2018-02-25T13:25:31Z

Types: order_items

Example 1

[{
  "event": "PRESHIPMENT",
  "sequence": 0,
  "quantity": 1
}]

A list of attributes, key-value pairs

Object

string

Example:

{ "promotion": "bogo" }

Methods: GET - Retrieve Order POST - Create/Update Orders PUT - Create/Update Shipments

Types: order_items pickups shipments

Promotion

Multi Country

{
    "promotion": "bogo"
}

{
    "checkout_brand": "peninsula",
    "checkout_language": "fr",
    "checkout_country": "CA"
}

The shipment destination

Object

string

Example:

john.doe@narvar.com

first_name

string required

Example:

John

last_name

string required

Example:

Doe

phone

string

Example:

6501234567

address

Object required

street_1

string required

Example:

633 Folsom Street

street_2

string

Example:

Floor 2

city

string required

Example:

San Francisco

state

string required

Example:

zip

string required

This can be a US zip code, or any international postal code

Example:

94107

country

string required

Country code should match ISO Alpha-2

Example:

location_id

string

Reference ID to a pre-configured location in Narvar

Types: billing shipments

Example

{
  "email": "john.doe@narvar.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "6501234567",
  "address": {
    "street_1": "633 Folsom Street",
    "street_2": "Floor 2",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94107",
    "country": "US"
  }
}

The shipment origin

Object

company_name

string

Example:

Acme International

string

Example:

john.doe@narvar.com

first_name

string

Example:

John

last_name

string

Example:

Doe

phone

string

Example:

6501234567

address

Object

street_1

string required

Example:

633 Folsom Street

street_2

string

Example:

Floor 2

city

string required

Example:

San Francisco

state

string required

Example:

zip

string required

This can be a US zip code, or any international postal code

Example:

94107

country

string required

Country code should match ISO Alpha-2

Example:

location_id

string

Reference to a pre-configured location id in Narvar

Types: shipments

Example

{
  "company_name": "Acme International",
  "email": "john.doe@narvar.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "6501234567",
  "address": {
    "street_1": "633 Folsom Street",
    "street_2": "Floor 2",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94107",
    "country": "US"
  }
}

Address format to be sent to Narvar

Object

street_1

string required

Example:

633 Folsom Street

street_2

string

Example:

Floor 2

city

string required

Example:

San Francisco

state

string required

Example:

zip

string required

This can be a US zip code, or any international postal code

Example:

94107

country

string required

Country code should match ISO Alpha-2

Example:

Types: customer order_items pickups shipped_from shipped_to

Example

{
  "street_1": "633 Folsom Street",
  "street_2": "Floor 2",
  "city": "San Francisco",
  "state": "CA",
  "zip": "94107",
  "country": "US"
}

A group of API calls can be found below that demonstaits how to use certain Narvar products and features

Notifications can be sent by Narvar for a variety of purposes. The most common use cases involve carrier events such as delivery or damage.

Sample Notification integration:

POST when an order is created
POST/PUT when fulfillment occurs
POST with any order changes

Create Order

Shipment

Order update

{
  "order_info": {
    "order_number": "634252345",
    "order_date": "2018-02-24T13:25:31Z",
    "checkout_locale": "en_US",
    "currency_code": "USD",
    "order_items": [{
      "categories": [
        "Clothing",
        "Shoes"
      ],
      "fulfillment_status": "NOT_SHIPPED",
      "is_final_sale": false,
      "item_image": "https://itemimageurl.png",
      "item_url": "https://item123.html",
      "name": "Red Shoes",
      "description": "Red Shoes - Size 10",
      "quantity": 2,
      "sku": "D2343122",
      "unit_price": 32.99,
      "original_unit_price": 55.99,
      "line_price": 65.98,
      "original_line_price": 111.98,
      "color": "red",
      "size": "10",
      "style": "low-tops",
      "attributes": {
        "pattern": "zebra"
      }
    },
    {
      "categories": [
        "Clothing",
        "Tops"
      ],
      "fulfillment_status": "NOT_SHIPPED",
      "is_final_sale": false,
      "item_image": "https://itemimageurl.png",
      "item_url": "https://item123.html",
      "name": "Blue shirt",
      "description": "Blue striped shirt",
      "quantity": 1,
      "sku": "F432423",
      "unit_price": 59.99,
      "original_unit_price": 75.99,
      "line_price": 59.99,
      "original_line_price": 76.99,
      "color": "blue",
      "size": "medium",
      "style": "retro",
      "attributes": {
        "pattern": "striped"
      }
    }],
    "billing": {
      "amount": 30.00,
      "billed_to": {
        "email": "john.doe@narvar.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "6501234567",
        "address": {
          "street_1": "633 Folsom Street",
          "street_2": "Floor 2",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94107",
          "country": "US"
        }
      }
    },
    "customer": {
      "customer_id": "78997234200222",
      "address": {
        "street_1": "633 Folsom Street",
        "street_2": "Floor 2",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94107",
        "country": "US"
      },
      "email": "john.doe@narvar.com",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "6501234567"
    }
  }
}

{
  "order_info": {
    "order_number": "634252345",
    "order_date": "2018-02-24T13:25:31Z",
    "checkout_locale": "en_US",
    "currency_code": "USD",
    "order_items": [{
      "categories": [
        "Clothing",
        "Shoes"
      ],
      "fulfillment_status": "SHIPPED",
      "is_final_sale": false,
      "item_image": "https://itemimageurl.png",
      "item_url": "https://item123.html",
      "name": "Red Shoes",
      "description": "Red Shoes - Size 10",
      "quantity": 2,
      "sku": "D2343122",
      "unit_price": 32.99,
      "original_unit_price": 55.99,
      "line_price": 65.98,
      "original_line_price": 111.98,
      "color": "red",
      "size": "10",
      "style": "low-tops",
      "attributes": {
        "pattern": "zebra"
      },
      "events": []
    },
    {
      "categories": [
        "Clothing",
        "Tops"
      ],
      "fulfillment_status": "SHIPPED",
      "is_final_sale": false,
      "item_image": "https://itemimageurl.png",
      "item_url": "https://item123.html",
      "name": "Blue shirt",
      "description": "Blue striped shirt",
      "quantity": 1,
      "sku": "F432423",
      "unit_price": 59.99,
      "original_unit_price": 75.99,
      "line_price": 59.99,
      "original_line_price": 76.99,
      "color": "blue",
      "size": "medium",
      "style": "retro",
      "attributes": {
        "pattern": "striped"
      },
      "events": []
    }],
    "billing": {
      "amount": 30.00,
      "billed_to": {
        "email": "john.doe@narvar.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "6501234567",
        "address": {
          "street_1": "633 Folsom Street",
          "street_2": "Floor 2",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94107",
          "country": "US"
        }
      }
    },
    "shipments": [{
      "items_info": [{
        "sku": "D2343122",
        "quantity": 2
      },
      {
        "sku": "F432423",
        "quantity": 1
      }],
      "ship_method": "Standard",
      "carrier": "UPS",
      "carrier_service": "GR",
      "ship_source": "DCWest",
      "ship_date": "2018-02-25T13:25:31Z",
      "ship_discount": 5.00,
      "ship_tax": 10.00,
      "ship_total": 15.00,
      "tracking_number": "1Z517757671802283",
      "shipped_from": {
        "company_name": "Acme International",
        "email": "john.doe@narvar.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "6501234567",
        "address": {
          "street_1": "633 Folsom Street",
          "street_2": "Floor 2",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94107",
          "country": "US"
        }
      },
      "shipped_to": {
        "email": "john.doe@narvar.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "6501234567",
        "address": {
          "street_1": "633 Folsom Street",
          "street_2": "Floor 2",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94107",
          "country": "US"
        }
      }
    }]
  }
}

{
  "order_info": {
    "order_number": "634252345",
    "order_date": "2018-02-24T13:25:31Z",
    "checkout_locale": "en_US",
    "currency_code": "USD",
    "order_items": [{
      "categories": [
        "Clothing",
        "Shoes"
      ],
      "fulfillment_status": "SHIPPED",
      "is_final_sale": false,
      "item_image": "https://itemimageurl.png",
      "item_url": "https://item123.html",
      "name": "Red Shoe",
      "description": "Red Shoes - Size 10",
      "quantity": 2,
      "sku": "D2343122",
      "unit_price": 32.99,
      "original_unit_price": 55.99,
      "line_price": 65.98,
      "original_line_price": 111.98,
      "color": "red",
      "size": "10",
      "style": "low-tops",
      "attributes": {
        "pattern": "zebra"
      },
      "events": []
    },
    {
      "categories": [
        "Clothing",
        "Tops"
      ],
      "fulfillment_status": "SHIPPED",
      "is_final_sale": false,
      "item_image": "https://itemimageurl.png",
      "item_url": "https://item123.html",
      "name": "Blue shirt",
      "description": "Blue striped shirt",
      "quantity": 1,
      "sku": "F432423",
      "unit_price": 59.99,
      "original_unit_price": 75.99,
      "line_price": 59.99,
      "original_line_price": 76.99,
      "color": "blue",
      "size": "medium",
      "style": "retro",
      "attributes": {
        "pattern": "striped"
      },
      "events": []
    }],
    "billing": {
      "amount": 30.00,
      "billed_to": {
        "email": "john.doe@narvar.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "6501234567",
        "address": {
          "street_1": "633 Folsom Street",
          "street_2": "Floor 2",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94107",
          "country": "US"
        }
      }
    },
    "shipments": [{
      "items_info": [{
        "sku": "D2343122",
        "quantity": 2
      },
      {
        "sku": "F432423",
        "quantity": 1
      }],
      "ship_method": "Standard",
      "carrier": "UPS",
      "carrier_service": "GR",
      "ship_source": "DCWest",
      "ship_date": "2018-02-25T13:25:31Z",
      "ship_discount": 5.00,
      "ship_tax": 10.00,
      "ship_total": 15.00,
      "tracking_number": "1Z517757671802283",
      "shipped_from": {
        "company_name": "Acme International",
        "email": "john.doe@narvar.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "6501234567",
        "address": {
          "street_1": "633 Folsom Street",
          "street_2": "Floor 2",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94107",
          "country": "US"
        }
      },
      "shipped_to": {
        "email": "john.doe@narvar.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "6501234567",
        "address": {
          "street_1": "633 Folsom Street",
          "street_2": "Floor 2",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94107",
          "country": "US"
        }
      }
    }]
  }
}

Narvar can use order data to power return support for retailers.

Sample Returns integration:

POST when fulfillment occurs
POST with any order changes

Shipment

Order update

{
  "order_info": {
    "order_number": "634252345",
    "order_date": "2018-02-24T13:25:31Z",
    "checkout_locale": "en_US",
    "currency_code": "USD",
    "order_items": [{
      "categories": [
        "Clothing",
        "Shoes"
      ],
      "fulfillment_status": "SHIPPED",
      "is_final_sale": false,
      "item_image": "https://itemimageurl.png",
      "item_url": "https://item123.html",
      "name": "Red Shoes",
      "description": "Red Shoes - Size 10",
      "quantity": 2,
      "sku": "D2343122",
      "unit_price": 32.99,
      "original_unit_price": 55.99,
      "line_price": 65.98,
      "original_line_price": 111.98,
      "color": "red",
      "size": "10",
      "style": "low-tops",
      "attributes": {
        "pattern": "zebra"
      }
    },
    {
      "categories": [
        "Clothing",
        "Tops"
      ],
      "fulfillment_status": "SHIPPED",
      "is_final_sale": false,
      "item_image": "https://itemimageurl.png",
      "item_url": "https://item123.html",
      "name": "Blue shirt",
      "description": "Blue striped shirt",
      "quantity": 1,
      "sku": "F432423",
      "unit_price": 59.99,
      "original_unit_price": 75.99,
      "line_price": 59.99,
      "original_line_price": 76.99,
      "color": "blue",
      "size": "medium",
      "style": "retro",
      "attributes": {
        "pattern": "striped"
      }
    }],
    "billing": {
      "billed_to": {
        "email": "john.doe@narvar.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "6501234567",
        "address": {
          "street_1": "633 Folsom Street",
          "street_2": "Floor 2",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94107",
          "country": "US"
        }
      }
    },
    "customer": {
      "customer_id": "78997234200222"
    },
    "shipments": [{
      "items_info": [{
        "sku": "D2343122",
        "quantity": 2
      },
      {
        "sku": "F432423",
        "quantity": 1
      }],
      "ship_method": "Standard",
      "carrier": "UPS",
      "carrier_service": "GR",
      "ship_date": "2018-02-25T13:25:31Z",
      "tracking_number": "1Z517757671802283",
      "shipped_to": {
        "email": "john.doe@narvar.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "6501234567",
        "address": {
          "street_1": "633 Folsom Street",
          "street_2": "Floor 2",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94107",
          "country": "US"
        }
      }
    }]
  }
}

{
  "order_info": {
    "order_number": "634252345",
    "order_date": "2018-02-24T13:25:31Z",
    "checkout_locale": "en_US",
    "currency_code": "USD",
    "order_items": [{
      "categories": [
        "Clothing",
        "Shoes"
      ],
      "fulfillment_status": "SHIPPED",
      "is_final_sale": false,
      "item_image": "https://itemimageurl.png",
      "item_url": "https://item123.html",
      "name": "Red Shoes",
      "description": "Red Shoes - Size 10",
      "quantity": 2,
      "sku": "D2343122",
      "unit_price": 32.99,
      "original_unit_price": 55.99,
      "line_price": 65.98,
      "original_line_price": 111.98,
      "color": "red",
      "size": "10",
      "style": "low-tops",
      "attributes": {
        "pattern": "zebra"
      },
      "events": [{
        "event": "RETURNED_TO_STORE",
        "quantity": 1
      }]
    },
    {
      "categories": [
        "Clothing",
        "Tops"
      ],
      "fulfillment_status": "SHIPPED",
      "is_final_sale": false,
      "item_image": "https://itemimageurl.png",
      "item_url": "https://item123.html",
      "name": "Blue shirt",
      "description": "Blue striped shirt",
      "quantity": 1,
      "sku": "F432423",
      "unit_price": 59.99,
      "original_unit_price": 76.99,
      "line_price": 59.99,
      "original_line_price": 76.99,
      "attributes": {
        "color": "blue"
      },
      "events": []
    }],
    "billing": {
      "billed_to": {
        "email": "john.doe@narvar.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "6501234567",
        "address": {
          "street_1": "633 Folsom Street",
          "street_2": "Floor 2",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94107",
          "country": "US"
        }
      }
    },
    "customer": {
      "customer_id": "78997234200222"
    },
    "shipments": [{
      "items_info": [{
        "sku": "D2343122",
        "quantity": 2
      },
      {
        "sku": "F432423",
        "quantity": 1
      }],
      "ship_method": "Standard",
      "carrier": "UPS",
      "carrier_service": "GR",
      "ship_date": "2018-02-25T13:25:31Z",
      "tracking_number": "1Z517757671802283",
      "shipped_to": {
        "email": "john.doe@narvar.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "6501234567",
        "address": {
          "street_1": "633 Folsom Street",
          "street_2": "Floor 2",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94107",
          "country": "US"
        }
      }
    }]
  }
}

Preshipment statuses can be used for items that take a longer time to ship. During the period after sale and before shipment retailers can keep their customers engaged by updating the status of the order.

Sample Preshipment integration:

POST when an order is created
POST when an item changes status
POST when an item is shipped

Order Creation

Status Change

Item Shipped

{
  "order_info": {
    "order_number": "634252345",
    "order_date": "2018-02-24T13:25:31Z",
    "checkout_locale": "en_US",
    "currency_code": "USD",
    "order_items": [{
      "fulfillment_status": "NOT_SHIPPED",
      "is_final_sale": false,
      "item_image": "https://itemimageurl.png",
      "item_url": "https://item123.html",
      "name": "Red Shoes",
      "description": "Red Shoes - Size 10",
      "quantity": 1,
      "sku": "D2343122",
      "unit_price": 32.99,
      "original_unit_price": 55.99,
      "line_price": 65.98,
      "original_line_price": 111.98,
      "color": "red",
      "size": "10",
      "style": "low-tops",
      "attributes": {
        "pattern": "zebra"
      },
      "events": [{
        "event": "PRESHIPMENT",
        "sequence": 0,
        "quantity": 1
      }]
    }],
    "billing": {
      "amount": 30.00,
      "payments": [{
        "is_gift_card": true,
        "merchant": "VISA",
        "method": "swipe",
        "expiration_date": "02/19"
      }],
      "billed_to": {
        "email": "john.doe@narvar.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "6501234567",
        "address": {
          "street_1": "633 Folsom Street",
          "street_2": "Floor 2",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94107",
          "country": "US"
        }
      },
      "tax_amount": 12.50,
      "tax_rate": 9.8,
      "shipping_handling": 4.30
    },
    "customer": {
      "customer_id": "78997234200222",
      "address": {
        "street_1": "633 Folsom Street",
        "street_2": "Floor 2",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94107",
        "country": "US"
      },
      "email": "john.doe@narvar.com",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "6501234567",
      "customer_type": "premium"
    },
    "attributes": {
      "promotion": "bogo"
    }  
  }
}

{
  "order_info": {
    "order_number": "634252345",
    "order_date": "2018-02-24T13:25:31Z",
    "checkout_locale": "en_US",
    "currency_code": "USD",
    "order_items": [{
      "fulfillment_status": "NOT_SHIPPED",
      "is_final_sale": false,
      "item_image": "https://itemimageurl.png",
      "item_url": "https://item123.html",
      "name": "Red Shoes",
      "description": "Red Shoes - Size 10",
      "quantity": 1,
      "sku": "D2343122",
      "unit_price": 32.99,
      "original_unit_price": 55.99,
      "line_price": 65.98,
      "original_line_price": 111.98,
      "color": "red",
      "size": "10",
      "style": "low-tops",
      "attributes": {
        "pattern": "zebra"
      },
      "events": [{
        "event": "PRESHIPMENT",
        "sequence": 1,
        "quantity": 1
      }]
    }],
    "customer": {
      "customer_id": "78997234200222"
    }
  }
}

{
  "order_info": {
    "order_number": "634252345",
    "order_date": "2018-02-24T13:25:31Z",
    "checkout_locale": "en_US",
    "currency_code": "USD",
    "order_items": [{
      "fulfillment_status": "SHIPPED",
      "is_final_sale": false,
      "item_image": "https://itemimageurl.png",
      "item_url": "https://item123.html",
      "name": "Red Shoes",
      "description": "Red Shoes - Size 10",
      "quantity": 1,
      "sku": "D2343122",
      "unit_price": 32.99,
      "original_unit_price": 55.99,
      "line_price": 65.98,
      "original_line_price": 111.98,
      "color": "red",
      "size": "10",
      "style": "low-tops",
      "attributes": {
        "pattern": "zebra"
      },
      "events": []
    }],
    "customer": {
      "customer_id": "78997234200222"
    },
    "shipments": [{
      "items_info": [{
        "sku": "D2343122",
        "quantity": 1
      }],
      "ship_method": "Standard",
      "carrier": "UPS",
      "carrier_service": "GR",
      "ship_date": "2018-02-25T13:25:31Z",
      "tracking_number": "1Z517757671802283",
      "shipped_from": {
        "company_name": "Acme International",
        "email": "john.doe@narvar.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "6501234567",
        "address": {
          "street_1": "633 Folsom Street",
          "street_2": "Floor 2",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94107",
          "country": "US"
        }
      },
      "shipped_to": {
        "email": "john.doe@narvar.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "6501234567",
        "address": {
          "street_1": "633 Folsom Street",
          "street_2": "Floor 2",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94107",
          "country": "US"
        }
      }
    }]
  }
}

When orders are purchased online and picked up in a retail store, Narvar can power this experience through order data.

Sample BOPIS integration:

POST when an order is created
POST when an order is ready to be picked up
POST when an order is is no longer available to be picked up

Order Placed

Ready for Pickup

Not Picked Up

Picked Up

{
  "order_info": {
    "order_number": "34252345",
    "order_date": "2018-02-24T13:25:31Z",
    "checkout_locale": "en_US",
    "currency_code": "USD",
    "order_items": [{
      "fulfillment_status": "PROCESSING",
      "is_final_sale": false,
      "item_image": "https://itemimageurl.png",
      "item_url": "https://item123.html",
      "name": "Red Shoes",
      "description": "Red Shoes - Size 10",
      "quantity": 1,
      "sku": "D2343122",
      "color": "red",
      "size": "10",
      "style": "low-tops",
      "attributes": {
        "pattern": "zebra"
      },
      "unit_price": 32.99,
      "original_unit_price": 55.99,
      "line_price": 65.98,
      "original_line_price": 111.98
    }],
    "pickups": [{
      "id": "1234",
      "items_info": [{
        "item_id": "ID123",
        "sku": "D2343122",
        "quantity": 1
      }],
      "status": {
        "code": "PROCESSING",
        "message": "Your order is processing",
        "date": "2018-02-24T13:25:31Z"
      },
      "eta": "2018-02-25T13:25:31Z",
      "pickup_by_date": "2018-03-01T13:25:31Z",
      "store": {
        "name": "Peninsula Trading",
        "id": "2342",
        "store_area": "Side Door",
        "address": {
          "street_1": "633 Folsom Street",
          "street_2": "Floor 2",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94107",
          "country": "US"
        },
        "url": "peninsulatrading.co",
        "phone_number": "(415) 486-8611",
        "hours": [{
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          }
        ]
      }
    }],
    "customer": {
      "customer_id": "78997234200222",
      "address": {
        "street_1": "633 Folsom Street",
        "street_2": "Floor 2",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94107",
        "country": "US"
      },
      "email": "john.doe@narvar.com",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "6501234567",
      "customer_type": "premium"
    }
  }
}

{
  "order_info": {
    "order_number": "34252345",
    "order_date": "2018-02-24T13:25:31Z",
    "checkout_locale": "en_US",
    "currency_code": "USD",
    "order_items": [{
      "fulfillment_status": "READY_FOR_PICKUP",
      "is_final_sale": false,
      "item_image": "https://itemimageurl.png",
      "item_url": "https://item123.html",
      "name": "Red Shoes",
      "description": "Red Shoes - Size 10",
      "quantity": 1,
      "sku": "D2343122",
      "color": "red",
      "size": "10",
      "style": "low-tops",
      "attributes": {
        "pattern": "zebra"
      },
      "unit_price": 32.99,
      "original_unit_price": 55.99,
      "line_price": 65.98,
      "original_line_price": 111.98
    }],
    "pickups": [{
      "id": "1234",
      "items_info": [{
        "item_id": "ID123",
        "sku": "D2343122",
        "quantity": 1
      }],
      "status": {
        "code": "READY_FOR_PICKUP",
        "message": "Your order is ready to be picked up!",
        "date": "2018-02-25T13:25:31Z"
      },
      "eta": "2018-02-25T13:25:31Z",
      "pickup_by_date": "2018-03-01T13:25:31Z",
      "store": {
        "name": "Peninsula Trading",
        "id": "2342",
        "store_area": "Side Door",
        "address": {
          "street_1": "633 Folsom Street",
          "street_2": "Floor 2",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94107",
          "country": "US"
        },
        "url": "peninsulatrading.co",
        "phone_number": "(415) 486-8611",
        "hours": [{
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          }
        ]
      }
    }],
    "customer": {
      "customer_id": "78997234200222",
      "address": {
        "street_1": "633 Folsom Street",
        "street_2": "Floor 2",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94107",
        "country": "US"
      },
      "email": "john.doe@narvar.com",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "6501234567",
      "customer_type": "premium"
    }
  }
}

{
  "order_info": {
    "order_number": "34252345",
    "order_date": "2018-02-24T13:25:31Z",
    "checkout_locale": "en_US",
    "currency_code": "USD",
    "order_items": [{
      "fulfillment_status": "NOT_PICKED_UP",
      "is_final_sale": false,
      "item_image": "https://itemimageurl.png",
      "item_url": "https://item123.html",
      "name": "Red Shoes",
      "description": "Red Shoes - Size 10",
      "quantity": 1,
      "sku": "D2343122",
      "color": "red",
      "size": "10",
      "style": "low-tops",
      "attributes": {
        "pattern": "zebra"
      },
      "unit_price": 32.99,
      "original_unit_price": 55.99,
      "line_price": 65.98,
      "original_line_price": 111.98
    }],
    "pickups": [{
      "id": "1234",
      "items_info": [{
        "item_id": "ID123",
        "sku": "D2343122",
        "quantity": 1
      }],
      "status": {
        "code": "NOT_PICKED_UP",
        "message": "Your order is no longer available for pickup",
        "date": "2018-03-02T13:25:31Z"
      },
      "eta": "2018-02-25T13:25:31Z",
      "pickup_by_date": "2018-03-01T13:25:31Z",
      "store": {
        "name": "Peninsula Trading",
        "id": "2342",
        "store_area": "Side Door",
        "address": {
          "street_1": "633 Folsom Street",
          "street_2": "Floor 2",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94107",
          "country": "US"
        },
        "url": "peninsulatrading.co",
        "phone_number": "(415) 486-8611",
        "hours": [{
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          }
        ]
      }
    }],
    "customer": {
      "customer_id": "78997234200222",
      "address": {
        "street_1": "633 Folsom Street",
        "street_2": "Floor 2",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94107",
        "country": "US"
      },
      "email": "john.doe@narvar.com",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "6501234567",
      "customer_type": "premium"
    }
  }
}

{
  "order_info": {
    "order_number": "34252345",
    "order_date": "2018-02-24T13:25:31Z",
    "checkout_locale": "en_US",
    "currency_code": "USD",
    "order_items": [{
      "fulfillment_status": "PICKED_UP",
      "is_final_sale": false,
      "item_image": "https://itemimageurl.png",
      "item_url": "https://item123.html",
      "name": "Red Shoes",
      "description": "Red Shoes - Size 10",
      "quantity": 1,
      "sku": "D2343122",
      "color": "red",
      "size": "10",
      "style": "low-tops",
      "attributes": {
        "pattern": "zebra"
      },
      "unit_price": 32.99,
      "original_unit_price": 55.99,
      "line_price": 65.98,
      "original_line_price": 111.98
    }],
    "pickups": [{
      "id": "1234",
      "items_info": [{
        "item_id": "ID123",
        "sku": "D2343122",
        "quantity": 1
      }],
      "status": {
        "code": "PICKED_UP",
        "message": "Your order has been picked up.",
        "date": "2018-03-02T13:25:31Z"
      },
      "eta": "2018-02-25T13:25:31Z",
      "pickup_by_date": "2018-03-01T13:25:31Z",
      "store": {
        "name": "Peninsula Trading",
        "id": "2342",
        "store_area": "Side Door",
        "address": {
          "street_1": "633 Folsom Street",
          "street_2": "Floor 2",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94107",
          "country": "US"
        },
        "url": "peninsulatrading.co",
        "phone_number": "(415) 486-8611",
        "hours": [{
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          },
          {
            "open": "0800",
            "close": "2000"
          }
        ]
      }
    }],
    "customer": {
      "customer_id": "78997234200222",
      "address": {
        "street_1": "633 Folsom Street",
        "street_2": "Floor 2",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94107",
        "country": "US"
      },
      "email": "john.doe@narvar.com",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "6501234567",
      "customer_type": "premium"
    }
  }
}

Narvar tracking can use order data to enhance the user experience when tracking their packages. When order data is sent to Narvar then the items in each box can be shown and a holistic view of the order can be communicated to the end user.

Sample tracking integration:

POST when an order is shipped

Order Shipped

{
  "order_info": {
    "order_number": "34252345",
    "order_date": "2018-02-24T13:25:31Z",
    "checkout_locale": "en_US",
    "currency_code": "USD",
    "order_items": [{
      "final_sale_date": "2018-02-25T13:25:31Z",
      "fulfillment_status": "SHIPPED",
      "item_image": "https://itemimageurl.png",
      "item_promise_date": "2018-02-25T13:25:31Z",
      "item_url": "https://item123.html",
      "name": "Red Shoes",
      "description": "Red Shoes - Size 10",
      "quantity": 2,
      "sku": "D2343122",
      "color": "red",
      "size": "10",
      "style": "low-tops",
      "attributes": {
        "pattern": "zebra"
      },
      "unit_price": 32.99,
      "original_unit_price": 55.99,
      "line_price": 65.98,
      "original_line_price": 111.98
    }],
    "customer": {
      "customer_id": "78997234200222"
    },
    "shipments": [{
      "items_info": [{
        "sku": "D2343122",
        "quantity": 1
      }],
      "ship_method": "Standard",
      "carrier": "UPS",
      "carrier_service": "GR",
      "ship_date": "2018-02-25T13:25:31Z",
      "tracking_number": "1Z517757671802283",
      "shipped_from": {
        "company_name": "Acme International",
        "email": "john.doe@narvar.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "6501234567",
        "address": {
          "street_1": "633 Folsom Street",
          "street_2": "Floor 2",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94107",
          "country": "US"
        }
      },
      "shipped_to": {
        "email": "john.doe@narvar.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "6501234567",
        "address": {
          "street_1": "633 Folsom Street",
          "street_2": "Floor 2",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94107",
          "country": "US"
        }
      }
    }]
  }
}

Open API 2.0 YAML Specification

You can upload the API Swagger file to Swagger UI to output SDKs and work within the Swagger UI.