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: `TWO_DAYS`, `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>	How long it usually takes for the package to be delivered at the shipping address after being handed in to the shipping company. Field uses`[from, to]` format. The same number can be used, e.g.: `[2, 2]`. For an approximate time, use different values, e.g.: `[2, 6]`.
fulfillmentTimeInDays	Array<number>	How many days it usually takes you to prepare an order for shipment. That time will be taken into account when calculating the delivery date for customers. Field uses `[from, to]` format. The same number can be used, e.g.: `[2, 2]`. For an approximate time, use different values, e.g.: `[2, 6]`.
cutoffTimeForSameDayPacking	string	Local time to pack orders received past this time on the next day in a 24-hour format, e.g.: `"13:00"`(in this case, orders placed after 13:00 will be scheduled for packing and shipping the next business day).
shippingBusinessDays	Array<string>	Days of the week when your orders can be delivered. These days will be taken into account when calculating and displaying the approximate delivery date for customers at checkout. Format: `[ "MON", "TUE", "WED", "THU", "FRI", "SUN", "SAT" ]`
deliveryDays	Array<string>	Days of the week when you pack orders for shipment. Your schedule will be taken into account when calculating the delivery date for customers. Format: `[ "MON", "TUE", "WED", "THU", "FRI", "SUN", "SAT" ]`

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