Create Shipping Term

Beta
POST/v1/operations/shipping-terms

Idempotent with Idempotency-Key header. Learn more

Creates a shipping term owned by your account.

The new term takes effect on freight quoting once it is assigned as a customer's default shipping term.

Permissions requiredValues:shipping_terms:create
The role behind your API key or agent must grant every one of these permissions.
include[]optional arrayenumValues:ownerowner.accountflat_rate.unit

Sub-objects to expand in the response. When omitted, sub-objects are returned as null.

namestring

Human-readable name for the shipping term, used to identify it when assigning shipping terms to customers and orders.

typestringenumValues:free_freightflat_rate_freightcarrier_rate_freight

Freight pricing model applied by this shipping term.

  • free_freight: the buyer is never charged for shipping.
  • flat_rate_freight: the buyer is charged the fixed amount in flat_rate, regardless of what the carrier would have charged.
  • carrier_rate_freight: the buyer is charged the rate the carrier quotes for the order's carrier and service level.
flat_rateoptional object

Fixed shipping charge applied to orders.

Used only when type is flat_rate_freight. A flat_rate_freight term created without a flat rate falls through to the carrier's quoted rate.

valuestring (decimal)

Decimal value, as a string to preserve precision.

unit_idstring

ID of the unit of measure for the value.

minimum_order_valueoptional object

Order total a buyer must exceed for this term's free-shipping rules to apply.

Above this total, freight is free for the service levels in free_shipping_service_level_ids.

valuestring (decimal)

Decimal value, as a string to preserve precision.

unit_idstring

ID of the unit of measure for the value.

free_shipping_service_level_idsoptional array of string

IDs of the service levels that ship for free once an order exceeds minimum_order_value.

Leave this empty to let every service level ship free above the threshold. The request is rejected if any ID is not a service level available to your account.

idstring

Shipping term ID.

objectstringenumValues:shipping_term

Resource type identifier.

namestring

Human-readable name for the shipping term, used to identify it when assigning shipping terms to customers and orders.

typestringenumValues:free_freightflat_rate_freightcarrier_rate_freight

Freight pricing model applied by this shipping term.

  • free_freight: the buyer is never charged for shipping.
  • flat_rate_freight: the buyer is charged the fixed amount in flat_rate, regardless of what the carrier would have charged.
  • carrier_rate_freight: the buyer is charged the rate the carrier quotes for the order's carrier and service level.
ownerownerExpandablenullable

Provenance of this shipping term.

System-owned shipping terms are platform-provided defaults shared across all accounts and cannot be updated or deleted; account-owned shipping terms are custom to your account.

objectstringenumValues:owner

Resource type identifier.

typestringenumValues:systemaccount

Where this resource came from.

  • system: a platform-provided default shared across all accounts; not editable.
  • account: created and owned by a specific account; the account field identifies which.
accountaccountExpandablenullable

The account that owns this resource.

Present only when type is account; system-owned resources have no owning account.

idstring

Account ID.

objectstringenumValues:account

Resource type identifier.

namestring

The account's display name.

default_billing_addressaddressnullable

The address billed by default on orders for this account.

Always returned as null in this endpoint.
default_shipping_addressaddressnullable

The address shipped to by default on orders for this account.

Always returned as null in this endpoint.
brandingaccount_brandingnullable

Customer-facing branding for the account, such as the logo, support contacts, and social links.

Always returned as null in this endpoint.
portalaccount_portalnullable

The account's customer portal settings, including the portal URL slug.

Always returned as null in this endpoint.
created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

flat_ratequantitynullable

Fixed shipping charge applied to the order.

Used only when type is flat_rate_freight; ignored for other freight pricing models. A flat_rate_freight term with no flat rate falls through to the carrier's quoted rate.

idstring

Quantity ID.

objectstringenumValues:quantity

Resource type identifier.

valuestring (decimal)

Raw decimal value of the quantity, as a string to preserve precision.

This is the unformatted machine value; see display_value for the human-readable rendering with unit and thousands separators.

display_valuestring

Formatted value with unit abbreviation (e.g. "$1,234.56" or "100 kg").

unitunitExpandablenullable

Unit of measure for this value (e.g. a currency, mass, or count unit).

idstring

Unit ID.

objectstringenumValues:unit

Resource type identifier.

namestring

Display name of the unit (e.g. "Gram", "Kilogram").

abbreviationstring

Short abbreviation for the unit (e.g. "g", "kg").

typestringenumValues:currencyquantitytime

The dimension this unit measures, such as mass, volume, or currency.

A unit can only be converted to another unit of the same dimension. The quantity dimension is for discrete countable items rather than a physical measure.

ratio_numeratorstring (decimal)

Numerator of the ratio that converts a quantity in this unit into the dimension's base unit.

A quantity is converted with value × (ratio_numerator / ratio_denominator) + (offset_numerator / offset_denominator), so a kilogram in a gram-based dimension has a numerator of 1000 and a denominator of 1.

ratio_denominatorstring (decimal)

Denominator of the ratio that converts a quantity in this unit into the dimension's base unit.

Cannot be zero.

offset_numeratorstring (decimal)

Numerator of the conversion offset, applied after the ratio for scales that do not share a zero point, such as temperature.

Zero for units that convert by ratio alone.

offset_denominatorstring (decimal)

Denominator of the conversion offset applied after the ratio.

Never zero; a unit with no offset carries a numerator of 0 over a denominator of 1.

is_base_unitboolean

Whether this is the base unit for its dimension.

Every other unit's conversion ratio is expressed relative to the base unit. Base units are platform-defined; units created through the API are never base units.

ownerownernullable

Owner of this resource.

Always returned as null in this endpoint.
created_atstring (date-time)

When this unit was created.

updated_atstring (date-time)

When this unit was last updated.

minimum_order_valuequantitynullable

Order total a buyer must exceed for this term's free-shipping rules to apply.

Above this total, freight is free for the service levels in free_shipping_service_levels.

idstring

Quantity ID.

objectstringenumValues:quantity

Resource type identifier.

valuestring (decimal)

Raw decimal value of the quantity, as a string to preserve precision.

This is the unformatted machine value; see display_value for the human-readable rendering with unit and thousands separators.

display_valuestring

Formatted value with unit abbreviation (e.g. "$1,234.56" or "100 kg").

unitunitExpandablenullable

Unit of measure for this value (e.g. a currency, mass, or count unit).

idstring

Unit ID.

objectstringenumValues:unit

Resource type identifier.

namestring

Display name of the unit (e.g. "Gram", "Kilogram").

abbreviationstring

Short abbreviation for the unit (e.g. "g", "kg").

typestringenumValues:currencyquantitytime

The dimension this unit measures, such as mass, volume, or currency.

A unit can only be converted to another unit of the same dimension. The quantity dimension is for discrete countable items rather than a physical measure.

ratio_numeratorstring (decimal)

Numerator of the ratio that converts a quantity in this unit into the dimension's base unit.

A quantity is converted with value × (ratio_numerator / ratio_denominator) + (offset_numerator / offset_denominator), so a kilogram in a gram-based dimension has a numerator of 1000 and a denominator of 1.

ratio_denominatorstring (decimal)

Denominator of the ratio that converts a quantity in this unit into the dimension's base unit.

Cannot be zero.

offset_numeratorstring (decimal)

Numerator of the conversion offset, applied after the ratio for scales that do not share a zero point, such as temperature.

Zero for units that convert by ratio alone.

offset_denominatorstring (decimal)

Denominator of the conversion offset applied after the ratio.

Never zero; a unit with no offset carries a numerator of 0 over a denominator of 1.

is_base_unitboolean

Whether this is the base unit for its dimension.

Every other unit's conversion ratio is expressed relative to the base unit. Base units are platform-defined; units created through the API are never base units.

ownerownernullable

Owner of this resource.

Always returned as null in this endpoint.
created_atstring (date-time)

When this unit was created.

updated_atstring (date-time)

When this unit was last updated.

free_shipping_service_levelslistExpandablenullable

Service levels that ship for free once an order exceeds minimum_order_value.

When this list is empty, every service level ships free above the threshold. When it is not empty, an order that picks a service level outside the list is not shipped free even above the threshold.

objectstringenumValues:list

Resource type identifier.

page_infoobject

Pagination metadata.

next_page_urlstringnullable

Relative URL that fetches the next page of results.

previous_page_urlstringnullable

Relative URL that fetches the previous page of results.

has_next_pageboolean

Whether more results exist after this page.

has_prev_pageboolean

Whether results exist before this page.

dataarray of service_level

Resources in this page.

idstring

Service level ID.

objectstringenumValues:service_level

Resource type identifier.

namestring

Human-readable name for the service level, shown to customers at checkout when the service level is visible.

service_level_tokenstring

Carrier-specific code identifying this service level (e.g. fedex_ground, ups_next_day_air).

For service levels synced from a connected carrier this is the carrier's own token, which is what rate shopping and label purchase are keyed on; for service levels you create yourself it is the code you supplied.

customer_portal_visibilitystringenumValues:visiblehidden

Whether customers can see and select this service level at checkout in the customer portal.

is_defaultboolean

Whether this is the carrier's default service level, pre-selected when the carrier is chosen.

Each carrier has at most one default; setting a new default clears the previous one. A default service level cannot be deleted until another service level takes its place or the flag is cleared.

default_transit_daysintegernullable

Business days this service typically takes in transit, used to work an order's ship-by date back from a promised delivery date.

A fallback for lanes the carrier has not quoted. Null means transit is unknown for this service rather than instant, so a ship-by date falls back to the promised delivery date itself.

ownerownernullable

Provenance of this service level.

System-owned service levels are platform-provided defaults that cannot be updated or deleted; account-owned service levels are custom to your account.

Always returned as null in this endpoint.
created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

created_atstring (date-time)

When this shipping term was created.

updated_atstring (date-time)

When this shipping term was last updated.

Responses

201

Successful response for Create Shipping Term