Add shipping option

Add a new shipping option.


AuthorizationstringoAuth 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.


titlestringTitle of shipping option.
enabledbooleantrue if shipping option is used at checkout to calculate shipping. false otherwise.
orderbynumberSort position or shipping option at checkout and in store settings. The smaller the number, the higher the position.
fulfilmentTypestringFulfillment type. pickup for in-store pickup methods, delivery for local delivery methods, shipping for manually calculated shipping rates.
ratesCalculationTypestringRates 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.
businessHoursLimitationTypestringOne 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.
blackoutDatesarray <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.
scheduledbooleantrue 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.
scheduledPickupbooleantrue if pickup time is scheduled, false otherwise. (Ask for Pickup Date and Time at Checkout option in pickup settings).
fulfillmentTimeInMinutesnumberAmount of time (in minutes) required for store to prepare pickup or to deliver an order (Order Fulfillment Time setting). For delivery and pickup only.
scheduledTimePrecisionTypestringFormat of how delivery date is chosen at the checkout - date or date and time. One of: DATE, DATE_AND_TIME_SLOT. For delivery only.
deliveryTimeDaysstringEstimated delivery time in days. Currently, it is equal to the description value.
timeSlotLengthInMinutesnumberLength of the delivery time slot in minutes. For delivery only.
allowSameDayDeliverybooleantrue if same-day delivery is allowed. false otherwise.
cutoffTimeForSameDayDeliverystringOrders placed after this time (in a 24-hour format) will be scheduled for delivery the next business day.
availabilityPeriodstringMaximum 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.
pickupInstructionstringString of HTML code of instructions on in-store pickup.
descriptionstringShipping 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.
pickupPreparationTimeHoursnumber[Deprecated] Amount of time required for store to prepare pickup (Order Fulfillment Time setting).
pickupBusinessHoursstring [Deprecated] Available and scheduled times to pickup orders (duplicates 'businessHours' field).
minimumOrderSubtotalnumberOrder 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


namestringZone displayed name.
countryCodesArray<string>Country codes this zone includes .
stateOrProvinceCodesArray<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
postCodesArray<string>Postcode (or zip code) templates this zone includes. More details: Destination zones in Ecwid.
geoPolygonsArray <GeoPolygons>Dot coordinates of the polygon (if destination zone is created using Zone on Map).


<COORDINATES>Array of arraysEach 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": [


MONArray of arraysArray of time ranges in format [[FROM TIME], [TO TIME]]. Ex: [["08:30", "13:30"], ["13:30", "19:00"]]
TUEArray of arraysArray of time ranges in format [[FROM TIME], [TO TIME]]. Ex: [["08:30", "13:30"], ["13:30", "19:00"]]
WEDArray of arraysArray of time ranges in format [[FROM TIME], [TO TIME]]. Ex: [["08:30", "13:30"], ["13:30", "19:00"]]
THUArray of arraysArray of time ranges in format [[FROM TIME], [TO TIME]]. Ex: [["08:30", "13:30"], ["13:30", "19:00"]]
FRIArray of arraysArray of time ranges in format [[FROM TIME], [TO TIME]]. Ex: [["08:30", "13:30"], ["13:30", "19:00"]]
SATArray of arraysArray of time ranges in format [[FROM TIME], [TO TIME]]. Ex: [["08:30", "13:30"], ["13:30", "19:00"]]
SUNArray of arraysArray of time ranges in format [[FROM TIME], [TO TIME]]. Ex: [["08:30", "13:30"], ["13:30", "19:00"]]


fromDatestringStarting date of the period, e.g. 2022-04-28.
toDatestringThe end date of the period, e.g. 2022-04-30.
repeatedAnnuallybooleanSpecifies whether the period repeats in the following years or not.


rateTypestringFor delivery and shipping: ABSOLUTE or PERCENT. For pickup: ABSOLUTE.
ratenumberShipping rate.


tableBasedOnstringWhat is this table rate based on. Possible values: "subtotal", "discountedSubtotal", "weight".
ratesArray <TableRate>Details of table rate.


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


weightFromnumber"Weight from" condition value.
weightTonumber"Weight to" condition value.
subtotalFromnumber"Subtotal from" condition value.
subtotalTonumber"Subtotal to" condition value.
discountedSubtotalFromnumber"Discounted subtotal from" condition value.
discountedSubtotalTonumber"Discounted subtotal from" condition value.


perOrdernumberAbsolute per order rate.
percentnumberPercent per order rate.
perItemnumberAbsolute per item rate.
perWeightnumberAbsolute per weight rate.


estimatedDeliveryDateAtCheckoutEnabledbooleantrue if the estimated delivery time is shown at checkout, otherwise false.
estimatedTransitTimeInDaysArray<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].
fulfillmentTimeInDaysArray<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].
cutoffTimeForSameDayPackingstringLocal 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).
shippingBusinessDaysArray<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.
[ "MON", "TUE", "WED", "THU", "FRI", "SUN", "SAT" ]
deliveryDaysArray<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.
[ "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.


titlestringShipping option title
typestringMust be always "carrier"
carrierstringMust be one of the following: "USPS", UPS, CP, FEDEX
enabledbooleanIf true, enables shipping method for customers at checkout. false otherwise. If not passed, default is true
   "title": "USPS",
   "type": "carrier",
   "carrier": "USPS",
   "enabled": true


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


idstringID of the created shipping option


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

 errorMessage: "A shipping option with this name 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 StatusDescriptionCode (optional)
400Request parameters are malformed
400Only USPS can be added via API at this time
400Shipping option title cannot be emptySHIPPING_OPTION_TITLE_REQUIRED
400Shipping carrier cannot be emptySHIPPING_CARRIER_NAME_REQUIRED
400One of the passed geoPolygons is not closed
400One of the passed geoPolygons has fewer vertexes than 4
402The functionality/method is not available on the merchant plan
403Access token doesn't have update_store_profile scope
409A shipping option with this name already existsSHIPPING_OPTION_ALREADY_EXISTS
415Unsupported content-type: expected application/json or text/json

Error response body (optional)

errorMessagestringError message
errorCodestringError code, optional