Add shipping option

post https://app.ecwid.com/api/v3/{storeId}/profile/shippingOptions

Add a new shipping option.

Headers

Name	Type	Description
Authorization	string	oAuth token with mandatory `Bearer` before it. Example: `Bearer e*s0`, where `e*s0` should be replaced with your oAuth token.

Add Shipping (manually calculated rates), Self Pickup or Delivery shipping option

Add a new manually calculated shipping rates, self pickup or delivery shipping option.

Request

Field	Type	Description
title	string	Title of shipping option.
enabled	boolean	`true` if shipping option is used at checkout to calculate shipping. `false` otherwise.
orderby	number	Sort position or shipping option at checkout and in store settings. The smaller the number, the higher the position.
fulfilmentType	string	Fulfillment type. `pickup` for in-store pickup methods, `delivery` for local delivery methods, `shipping` for manually calculated shipping rates.
ratesCalculationType	string	Rates calculation type (for `delivery` and `shipping` only). One of:`table` or `flat`.
destinationZone	<Zone>	Destination zone set for shipping option (for `delivery` and `shipping` only). Empty for public token.
businessHours	<BusinessHours>	Business hours info.
businessHoursLimitationType	string	One of: `ALLOW_ORDERS_AND_INFORM_CUSTOMERS` - makes it possible to place an order using this delivery method at any time, but if delivery doesn't work at the moment when the order is being placed, a warning will be shown to a customer. `DISALLOW_ORDERS_AND_INFORM_CUSTOMERS` - makes it possible to place an order using this delivery method only during the operational hours. If delivery doesn't work when an order is placed, this delivery method will be shown at the checkout as a disabled one and will contain a note about when delivery will start working again. `ALLOW_ORDERS_AND_DONT_INFORM_CUSTOMERS` - makes it possible to place an order using this delivery method at any time. Works only for delivery methods with a schedule.
blackoutDates	array <BlackoutDates>	Dates when the store doesn’t work, so customers can't choose these dates. Each period of dates is a JSON object. For `delivery` and `pickup` only.
scheduled	boolean	`true` if "Allow to select delivery date or time at checkout" or "Ask for Pickup Date and Time at Checkout" setting is enabled. `false` otherwise. For `delivery` and `pickup` only.
scheduledPickup	boolean	`true` if pickup time is scheduled, `false` otherwise. (Ask for Pickup Date and Time at Checkout option in pickup settings).
fulfillmentTimeInMinutes	number	Amount of time (in minutes) required for store to prepare pickup or to deliver an order (Order Fulfillment Time setting). For `delivery` and `pickup` only.
scheduledTimePrecisionType	string	Format of how delivery date is chosen at the checkout - date or date and time. One of: `DATE`, `DATE_AND_TIME_SLOT`. For `delivery` only.
deliveryTimeDays	string	Estimated delivery time in days. Currently, it is equal to the `description` value.
timeSlotLengthInMinutes	number	Length of the delivery time slot in minutes. For `delivery` only.
allowSameDayDelivery	boolean	`true` if same-day delivery is allowed. `false` otherwise.
cutoffTimeForSameDayDelivery	string	Orders placed after this time (in a 24-hour format) will be scheduled for delivery the next business day.
availabilityPeriod	string	Maximum possible delivery date for local delivery and pickup shipping options ("Allow choosing pickup date within"). Values: `THREE_DAYS`, `SEVEN_DAYS`, `ONE_MONTH`, `THREE_MONTHS`, `SIX_MONTHS`, `ONE_YEAR`, `UNLIMITED`. For `delivery` and `pickup` only.
pickupInstruction	string	String of HTML code of instructions on in-store pickup.
description	string	Shipping method description. Is also shown in the fields `deliveryTimeDays` (for GET shipping options requests) and `estimatedTransitTime` (for GET orders requests). For `delivery` and `shipping` only.
pickupPreparationTimeHours	number	[Deprecated] Amount of time required for store to prepare pickup (Order Fulfillment Time setting).
pickupBusinessHours	string	[Deprecated] Available and scheduled times to pickup orders (duplicates 'businessHours' field).
minimumOrderSubtotal	number	Order subtotal before discounts. The delivery method won’t be available at checkout for orders below that amount. The field is displayed if the value is not 0. For `delivery` and `shipping` only.
flatRate	<FlatRate>	Flat rate details.
ratesTable	<TableRatesDetails>	Custom table rates details.
estimatedShippingTimeAtCheckoutSettings	<estimatedShippingTimeAtCheckoutSettings>	Information about estimated shipping time shown at checkout

Zone

Field	Type	Description
name	string	Zone displayed name.
countryCodes	Array<string>	Country codes this zone includes .
stateOrProvinceCodes	Array<string>	State or province codes the zone includes. Format: [country code]-[state code] Example: shipping zone for Alabama, Arizona, Alaska in United states looks like: `["US-AL","US-AK","US-AZ"]`. Please refer to Dictionaries to get right country and state codes, as it's getting validated upon creating/updating shipping option
postCodes	Array<string>	Postcode (or zip code) templates this zone includes. More details: Destination zones in Ecwid.
geoPolygons	Array <GeoPolygons>	Dot coordinates of the polygon (if destination zone is created using Zone on Map).

GeoPolygons

Field	Type	Description
<COORDINATES>	Array of arrays	Each array contains coordinates of a single dot of the polygon. Minimum 4 dots. Each geoPolygon vertex must have no more than 7 digits after the decimal point, the rest digits will be cut. The polygon's first vertex must be equal the last one by coordinates. See an example below:

"geoPolygons": [
  [
   [
     37.0365395,
     -95.66864041664617
   ],
   [
     37.0754801,
     -95.6404782452158
   ],
   ...
   [
     37.0365395,
     -95.66864041664617
   ] 
  ]
]

BusinessHours

Field	Type	Description
MON	Array of arrays	Array of time ranges in format `[[FROM TIME], [TO TIME]]`. Ex: `[["08:30", "13:30"], ["13:30", "19:00"]]`
TUE	Array of arrays	Array of time ranges in format `[[FROM TIME], [TO TIME]]`. Ex: `[["08:30", "13:30"], ["13:30", "19:00"]]`
WED	Array of arrays	Array of time ranges in format `[[FROM TIME], [TO TIME]]`. Ex: `[["08:30", "13:30"], ["13:30", "19:00"]]`
THU	Array of arrays	Array of time ranges in format `[[FROM TIME], [TO TIME]]`. Ex: `[["08:30", "13:30"], ["13:30", "19:00"]]`
FRI	Array of arrays	Array of time ranges in format `[[FROM TIME], [TO TIME]]`. Ex: `[["08:30", "13:30"], ["13:30", "19:00"]]`
SAT	Array of arrays	Array of time ranges in format `[[FROM TIME], [TO TIME]]`. Ex: `[["08:30", "13:30"], ["13:30", "19:00"]]`
SUN	Array of arrays	Array of time ranges in format `[[FROM TIME], [TO TIME]]`. Ex: `[["08:30", "13:30"], ["13:30", "19:00"]]`

BlackoutDates

Field	Type	Description
fromDate	string	Starting date of the period, e.g. `2022-04-28`.
toDate	string	The end date of the period, e.g. `2022-04-30`.
repeatedAnnually	boolean	Specifies whether the period repeats in the following years or not.

FlatRate

Field	Type	Description
rateType	string	For `delivery` and `shipping`: `ABSOLUTE` or `PERCENT`. For pickup: `ABSOLUTE`.
rate	number	Shipping rate.

TableRatesDetails

Field	Type	Description
tableBasedOn	string	What is this table rate based on. Possible values: `"subtotal"`, `"discountedSubtotal"`, `"weight"`.
rates	Array <TableRate>	Details of table rate.

TableRate

Field	Type	Description
conditions	<TableRateConditions>	Conditions for this shipping rate in custom table.
rate	<TableRateDetails>	Table rate details.

TableRateConditions

Field	Type	Description
weightFrom	number	"Weight from" condition value.
weightTo	number	"Weight to" condition value.
subtotalFrom	number	"Subtotal from" condition value.
subtotalTo	number	"Subtotal to" condition value.
discountedSubtotalFrom	number	"Discounted subtotal from" condition value.
discountedSubtotalTo	number	"Discounted subtotal from" condition value.

TableRateDetails

Field	Type	Description
perOrder	number	Absolute per order rate.
percent	number	Percent per order rate.
perItem	number	Absolute per item rate.
perWeight	number	Absolute per weight rate.

estimatedShippingTimeAtCheckoutSettings

Field	Type	Description
estimatedDeliveryDateAtCheckoutEnabled	boolean	`true` if the estimated delivery time is shown at checkout, otherwise `false`.
estimatedTransitTimeInDays	Array<number>	estimated transit time in days. For accurate time, the same numbers for both values of the minimum and maximum estimated transit time in days are used. Example: `[2, 2]`. For an approximate time, the values of minimum and maximum numbers of days are used, example: `[2, 6]`.
fulfillmentTimeInDays	Array<number>	order preparation time. For accurate time, the same numbers for both values of the minimum and maximum order preparation time are used. Example: `[2, 2]`. For an approximate time, the values of minimum and maximum numbers of days are used, example: `[2, 6]`.
shippingBusinessDays	Array<string>	number of days of packing the orders.
cutoffTimeForSameDayPacking	string	orders placed after this time (in a 24-hour format, example: `"13:00"`) will be scheduled for packing and shipping the next business day.

Add carrier-calculated automatic shipping rates by U.S.P.S., UPS, Canada Post or FedEx

Add a new carrier-calculated shipping option with default account settings. Change details to another account in the Ecwid Control Panel.

Request

Field	Type	Description
title	string	Shipping option title
type	string	Must be always `"carrier"`
carrier	string	Must be one of the following: `"USPS"`, `UPS`, `CP`, `FEDEX`
enabled	boolean	If `true`, enables shipping method for customers at checkout. `false` otherwise. If not passed, default is `true`

{
   "title": "USPS",
   "type": "carrier",
   "carrier": "USPS",
   "enabled": true
}

Response

A JSON object of type 'CreateStatus' with the following fields:

CreateStatus

Field	Type	Description
id	string	ID of the created shipping option

Errors

HTTP/1.1 409 Conflict
Content-Type application/json; charset=utf-8

{
 errorMessage: "A shipping option with this name already exists",
 errorCode: "SHIPPING_OPTION_ALREADY_EXISTS"
}

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP Status	Description	Code (optional)
400	Request parameters are malformed
400	Only USPS can be added via API at this time
400	Shipping option title cannot be empty	`SHIPPING_OPTION_TITLE_REQUIRED`
400	Shipping carrier cannot be empty	`SHIPPING_CARRIER_NAME_REQUIRED`
400	One of the passed geoPolygons is not closed
400	One of the passed geoPolygons has fewer vertexes than 4
402	The functionality/method is not available on the merchant plan
403	Access token doesn't have `update_store_profile` scope
409	A shipping option with this name already exists	`SHIPPING_OPTION_ALREADY_EXISTS`
415	Unsupported content-type: expected `application/json` or `text/json`

Error response body (optional)

Field	Type	Description
errorMessage	string	Error message
errorCode	string	Error code, optional