Retailer Carrier Self Serve

Get Carriers

GET /carriers

Get Services And Configurations For Carrier

GET /carriers/{carrier-moniker}

Create Carrier Service And Configurations

POST /carriers/{carrier-moniker}

Delete Carrier Service

DELETE /carriers/{carrier-moniker}

Get Carrier Account By Alias

GET /carrier-accounts

Create Carrier Account

POST /carrier-accounts

Update Carrier Account

PUT /carrier-accounts

Delete Carrier Account

DELETE /carrier-accounts/{account-alias}

GET /carriers

Returns list of carriers for the given retailer. Retailer would be derived from authorization token

Request parameters

products

array of Products-Enum optional

Filters carriers based on the product. If not provided, carriers for all products would be returned in the response

capabilities

array of capabilities-Enum optional

Filters carriers on the capability. If not provided, carriers for all capabilities would be returned in the response

Request headers

Authorization

string required

Example:

Bearer token

Responses

200 200

Successful response

Body

application/json

Object

retailer_moniker

string required

Unique identifier for the retailer. List of retailers and corresponding monikers can be found in Hub. retailer_moniker is derived from the authorization token

carriers

Array

Object

carrier_moniker

string required

Unique identifier for the carrier. List of carriers and corresponding monikers can be found in Hub

status

string required

Indicates whether the carrier has any active account for the retailer and carrier and product (if provided in request)

Enumeration:

active

inactive

last_updated_by

string required

user who made the latest changes. To be derived from authorization token

last_update_datetime

string required

date and time of the latest update

capabilities

Array of capabilities-Enum required

superset of all capabilities set up for account-aliases of this carrier and retailer

products

Array of Products-Enum required

superset of all products set up for account-aliases of this carrier and retailer

carrier-services

Array of string

superset of all carrier-services set up for account-aliases of this carrier and retailer

400 400

Bad Request

Body

application/json

ErrorResponseWrapper

401 401

Unauthorized

Body

application/json

ErrorResponseWrapper

403 403

Forbidden

Body

application/json

ErrorResponseWrapper

GET /carriers/{carrier-moniker}

Retrieve carrier services, configurations and accounts for the carrier.

Path variables

carrier-moniker

string required

Example:

fedex

Request parameters

country

string optional

ISO 2 letter country code. If passed, api returns the carrier services servicing the country

Note - If a carrier service does not have any country restrictions, it will be returned for any country passed as param

Example:

US

products

array of Products-Enum optional

Filters accounts based on the products. If not provided, all accounts for the carrier and retailer would be returned in the response

capabilities

array of capabilities-Enum optional

Filters accounts based on the capabilities. If not provided, all accounts for the carrier and retailer would be returned in the response

Request headers

X-Narvar-Tracer-ID

string optional

Authorization

string optional

Example:

Bearer Token

Responses

200 200

OK

Body

application/json

CarrierServicesWrapper

400 400

Bad Request

Body

application/json

ErrorResponseWrapper

401 401

Unauthorized

Body

application/json

ErrorResponseWrapper

403 403

Forbidden

Body

application/json

ErrorResponseWrapper

POST /carriers/{carrier-moniker}

Adds carrier services and configurations for a carrier-moniker and retailer

Path variables

carrier-moniker

string required

Request headers

X-Narvar-Tracer-ID

string optional

Authorization

string optional

Example:

Bearer Token

Request body

application/json

CarrierServiceConfigurationRequest

Responses

200 200

OK

Headers

X-Narvar-Request-ID

string optional

Body

application/json

CarrierServiceCreationResponse

400 400

Bad Request

Body

application/json

CarrierAccountErrorResponseWrapper

401 401

Unauthorized

Body

application/json

CarrierAccountErrorResponseWrapper

403 403

Forbidden

Body

application/json

CarrierAccountErrorResponseWrapper

DELETE /carriers/{carrier-moniker}

Deletes the carrier-service for the carrier-moniker and the retailer

Path variables

carrier-moniker

string required

account-alias is unique per tenant

Request parameters

carrier-service

string required

service-name of the carrier-service to be deleted

Responses

200 200

OK

400 400

Bad Request

Body

application/json

CarrierAccountErrorResponseWrapper

401 401

Unauthorized

Body

application/json

CarrierAccountErrorResponseWrapper

403 403

Forbidden

Body

application/json

CarrierAccountErrorResponseWrapper

404 404

Not Found

Headers

X-Narvar-Request-ID

string optional

Body

application/json

CarrierAccountErrorResponseWrapper

GET /carrier-accounts

Retreive carrier account details for account_alias. Response varies with the carrier

Request parameters

account-alias

string required

account-alias is unique per tenant

Responses

200 200

OK

Body

application/json

RetailerCarrierAccountResponseWrapper

400 400

Bad Request

Body

application/json

CarrierAccountErrorResponseWrapper

401 401

Unauthorized

Body

application/json

CarrierAccountErrorResponseWrapper

403 403

Forbidden

Body

application/json

CarrierAccountErrorResponseWrapper

404 404

Not Found

Headers

X-Narvar-Request-ID

string optional

Body

application/json

CarrierAccountErrorResponseWrapper

POST /carrier-accounts

Creates a new carrier account. Payload is specific to the carrier

Request headers

X-Narvar-Tracer-ID

string optional

Authorization

string optional

Example:

Bearer Token

Request body

application/json

CarrierAccountRequest

Responses

200 200

OK

Headers

X-Narvar-Request-ID

string optional

Body

application/json

CarrierAccountCreateResponseWrapper

400 400

Bad Request

Body

application/json

CarrierAccountErrorResponseWrapper

401 401

Unauthorized

Body

application/json

CarrierAccountErrorResponseWrapper

403 403

Forbidden

Body

application/json

CarrierAccountErrorResponseWrapper

PUT /carrier-accounts

Creates a new carrier account. Payload is specific to the carrier

Request headers

X-Narvar-Tracer-ID

string optional

Authorization

string required

Example:

Bearer Token

Request body

application/json

CarrierAccountUpdateRequest

Responses

200 200

OK

Headers

X-Narvar-Request-ID

string optional

Body

application/json

CarrierAccountCreateResponseWrapper

400 400

Bad Request

Body

application/json

CarrierAccountErrorResponseWrapper

401 401

Unauthorized

Body

application/json

CarrierAccountErrorResponseWrapper

403 403

Forbidden

Body

application/json

CarrierAccountErrorResponseWrapper

DELETE /carrier-accounts/{account-alias}

Deletes the carrier-account for account-alias

Path variables

account-alias

string required

account-alias is unique per tenant

Responses

200 200

OK

400 400

Bad Request

Body

application/json

CarrierAccountErrorResponseWrapper

401 401

Unauthorized

Body

application/json

CarrierAccountErrorResponseWrapper

403 403

Forbidden

Body

application/json

CarrierAccountErrorResponseWrapper

404 404

Not Found

Headers

X-Narvar-Request-ID

string optional

Body

application/json

CarrierAccountErrorResponseWrapper

Object

source

string

error origin e.g. narvar_reported

Enumeration:

narvar_reported

Example:

narvar_reported

type

string

broad category of error.

Example:

Validation

code

string

Specific error code. Error codes defined in link - https://narvar-docs.readme.io/reference/carriers

Example:

15000

message

string

Readable error message

Example:

Incorrect data

Object

source

string

error origin e.g. narvar_reported

Enumeration:

narvar_reported

Example:

narvar_reported

code

string

Specific error code. Error codes defined in link - https://narvar-docs.readme.io/reference/carriers

Example:

15002

message

string

Readable error message

Example:

Resource not Found

string

Enumeration:

forward_label

returns_label

returns_mobile

returns_boxless

returns_pickup

local_delivery

international_shipment

shipment_tracking

multi_piece_shipment

string

Enumeration:

returns

tracking

delivery

Object

shipment_type

string

Indicates if the service supports domestic or international shipment

Enumeration:

domestic

international

label_specs

Array of LabelSpec

Describes the label type and label size

label_params

Array

Indicates the number of params that can be printed on the label.

string

Enumeration:

reference1

reference2

reference3

delivery_settings

DeliverySettings

Describes label type and label size

Object

label_size

string

Size of the label. Mandatory when the label_type is set to “PDF” or “PNG”.

Enumeration:

A6

A4

US_LETTER

label_type

string

The format of the label to generate

Enumeration:

PDF

PNG

Carrier Service

Object

service_name

string required

Name of the service

Example:

FEDEX_GROUND

configuration

Object

carrier service level configuration(restrictions). The schema would vary based on carrier

description

string

Description of the carrier service

Example:

Fedex Ground

is_active

boolean

Indicates whether the service is active

countries

Array of string

countries supported by the service

Object

status

string

Status of the request

carrier_moniker

string

The name of the carrier whose configuration you are requesting

carrier_services

Array of CarrierService

The name of the carrier service (e.g. FEDEX_GROUND)

configuration

Object

carrier level configuration(restrictions) of the carrier. The schema would vary based on carrier

accounts

Array of CarrierAccountDetail

Delivery Settings

Object

length

Measurement

width

Measurement

height

Measurement

weight

Weight

package_type

Array

carrier specific package types

string

Example:

FEDEX_10KG_BOX

supported_features

Array

Features supported by carrier. One of signature_required, proof_of_delivery_required, po_box, military_address, hazmat

signature_required - Signature required supported. Indicates whether the carrier supports collecting signature on delivery/pickup proof_of_delivery_required - Proof of delivery supported. Indicates whether the carrier supports collecting proof of delivery po_box - PO Box Address supported military_address - Military Address supported hazmat - Hazardous Material supported

string

Enumeration:

signature_required

proof_of_delivery_required

po_box

military_address

hazmat

Dimension properties

Object

min

number

max

number

unit

string

Enumeration:

in

ft

yd

mm

cm

m

Weight properties

Object

min

number

max

number

unit

string

Enumeration:

g

kg

oz

lb

Time window for an event. Should specify either start and end hours or start and end times. If both are specified, start and end times are preferred over hours as they are more specific.

In general specify time in local timezone rather than in UTC. If the date of the event needs to be extracted (e.g. where the required resolution is day), the day will be extracted in the local timezone rather than in UTC. So, delivery date for 2020-03-12 4:00 UTC is actually 2020-03-11 in PST.Weight properties

Object

start_hours

string

Start hours of the window (e.g. 14:00 ) in 24 hour time format.

Pattern: ^(0[0-9]|^1[0-9]|2[0-3]):[0-5][0-9]$

Example:

09:00

end_hours

string

End hours of the window (e.g. 14:30) in 24 hour time format.

Pattern: ^(0[0-9]|^1[0-9]|2[0-3]):[0-5][0-9]$

Example:

16:00

start_time

string date-time

Start time in local timezone with timezone

Example:

2022-08-05T23:52:18.521212+05:30

end_time

string date-time

End time in local timezone with timezone

Object

carrier_closures

Array of CarrierClosure

Object

name

string

closure name

Example:

Independence Day

countries

Array

string

Enumeration:

US

UK

date

string date

The date of the closure - Format yyyy-mm-dd

Object

account_alias

string

unique identifier for the account

capabilities

Array of capabilities-Enum

list of capabilities setup for the account

product

Array of Products-Enum

list of products setup for the account

carrier_services

Array of string

set of carrier_services enabled for the account_alias

Carrier Account Details

Object

carrier_moniker

string required

Example:

auspost

capabilities

Array of capabilities-Enum required

products

Array of Products-Enum required

account_identifier

string required

Unique Id generated by Samoa

Example:

123e4567-e89b-12d3-a456-426614174000

is_active

boolean required

Indicates whether the account is active. Mandatory field for creating new account. Optional for updating existing account

Example:

true

account_alias

string required

unique identifier for an account. Example : nike-auspost-label

credentials

One of

Carrier Specific Credentials

postnord

gls

Carrier Account Details

Object

carrier_moniker

string required

carrier for which this account is set

Example:

auspost

capabilities

Array of capabilities-Enum required

list of capabilities setup for the account

products

Array of Products-Enum required

list of products setup for the account

account_identifier

string required

Unique Id generated by Samoa

Example:

123e4567-e89b-12d3-a456-426614174000

is_active

boolean required

Indicates whether the account is active. Mandatory field for creating new account. Optional for updating existing account

Example:

true

account_alias

string required

unique identifier for an account. Example : nike-auspost-label

retailer_moniker

string

retailer for which this account is set. retailer_moniker is derived from authorization token

Carrier Account Details

Object

retailer_moniker

string required

Unique identifier for the retailer. List of retailers and corresponding monikers can be found in Hub. retailer_moniker is derived from the authorization token

carrier_moniker

string required

The name of the carrier whose account you are requesting

Example:

auspost

capabilities

Array of capabilities-Enum required

list of capabilities setup for the account

products

Array of Products-Enum required

list of products setup for the account

account_identifier

string required

Unique Id generated by Samoa

Example:

123e4567-e89b-12d3-a456-426614174000

is_active

boolean required

Indicates whether the account is active. Mandatory field for creating new account. Optional for updating existing account

Example:

true

account_alias

string required

unique identifier for an account. Example : nike-auspost-label

credentials

One of

Carrier Specific Credentials

postnord

gls

Credential details for carrier. This will vary with carrier

Object

username

string

Example:

11111111-e89b-12d3-a456-426614174000

password

string

Example:

****

account_number

string

Example:

1****7****

Postnord Carrier Account

Object

api_key

string required

Example:

apikey

party_id

string required

Example:

277000941

party_id_type

string required

Example:

160

issuer_code

string required

Example:

Z11

gls Carrier Account

Object

username

string required

Example:

username

password

string required

Example:

******

shipper_contact_id

string required

Example:

160

hostname

string

Object

status

string

Status of the request

carrierAccount

Carrier-Account-Response

Object

status

string

Status of the request

carrierAccount

Retailer-Carrier-Account-Response

Object

status

string

errors

Array of Error

Object

status

string

carrierAccounts

Array of Carrier-Account

Carrier Account Details

Object

carrier_moniker

string required

carrier for which this account is created

Example:

auspost

capabilities

Array of capabilities-Enum required

list of capabilities setup for the account

products

Array of Products-Enum required

list of products setup for the account

is_active

boolean

Indicates whether the account is active

Example:

true

account_alias

string required

unique identifier for an account. Example : nike-auspost-label. Note - account_alias cannot be updated

credentials

Any of required

credentials depend on the carrier-moniker. Any of the below should be used

postnord

gls

carrier_services

Array of string required

carrier_services enabled for the account

Carrier Account Details

Object

carrier_moniker

string required

carrier for which this account is set

Example:

auspost

capabilities

Array of capabilities-Enum

list of capabilities setup for the account. In case not passed, will be defaulted to existing capabilities for the account

products

Array of Products-Enum

list of products setup for the account. In case not passed, will be defaulted to existing products, for the account

is_active

boolean

Indicates whether the account is active

Example:

true

account_alias

string required

unique identifier for an account. Example : nike-auspost-label. Note - account_alias cannot be updated

credentials

Any of

credentials depend on the carrier-moniker. Any of the below should be used

postnord

gls

Credential details for carrier. This will vary with carrier

Object

username

string

Example:

11111111-e89b-12d3-a456-426614174000

password

string

Example:

****

Credential details for carrier. This will vary with carrier

Object

username

string

Example:

11111111-e89b-12d3-a456-426614174000

password

string

Example:

****

contract_id

string

Example:

123

customer_number

string

Example:

123

Object

status

string

errors

Array of Error

Object

capabilities

Array of capabilities-Enum required

list of capabilities setup for the account

products

Array of Products-Enum required

list of products setup for the account

carrier_service_configurations

Array of CarrierServiceRequest

Retailer configuration overrides for carrier_services and their respective configurations

carrier_configuration

Object

carrier level configuration to be overridden by the retailer. The schema would vary based on carrier

Carrier Service

Object

service_name

string required

Name of the service

Example:

FEDEX_GROUND

configuration

Object

carrier service level configuration(restrictions). The schema would vary based on carrier. Only properties updated by the retailer(i.e.delta) should be sent in the request

is_active

boolean

Indicates whether the service is active

countries

Array of string

countries supported by the service

Object

status

string

Status of the request

carrier_moniker

string

The name of the carrier whose configuration you are requesting

carrier_services

Array of CarrierService

The name of the carrier service (e.g. FEDEX_GROUND)

configuration

CarrierConfiguration