Menu

Shipping Options API Routes

A shipping option is a way of shipping an item to or from the customer.

Shipping options are associated with the fulfillment provider used to handle their fulfillment.

Shipping options can be restricted geographically by service zones, and by custom rules, such as an item's weight or the customer's group.

These API routes allow admins to manage shipping options.

GET /admin/shipping-options#

List Shipping Options

Retrieve a list of shipping options. The shipping options can be filtered by fields such as id. The shipping options can also be sorted or paginated.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.
offsetnumberOptional
The number of items to skip when retrieving a list.
limitnumberOptional
Limit the number of items returned in the list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
idstring | string[]Optional
Filter by a shipping option ID.
qstringOptional
Search term to filter the shipping option's searchable properties.
service_zone_idstring | string[]Optional
Filter by a service zone's ID to retrieve its associated shipping options.
shipping_profile_idstring | string[]Optional
Filter by a shipping profile's ID to retrieve its associated shipping options.
provider_idstring | string[]Optional
Filter by a fulfillment provider's ID to retrieve its associated shipping options.
shipping_option_type_idstring | string[]Optional
Filter by a shipping option type's ID to retrieve its associated shipping options.
created_atobjectOptional
Filter by a shipping option's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by a shipping option's update date. Accepts the filter operators.
deleted_atobjectOptional
Filter by a shipping option's deletion date. Accepts the filter operators.
stock_location_idstring | string[]Optional
Filter by a location ID to retrieve its associated shipping option.
is_returnbooleanOptional
Filter by whether the shipping option is used for returns.
admin_onlybooleanOptional
Filter by whether the shipping option is used by admin users only.
with_deletedbooleanOptional
Whether to include deleted records in the result.

Request examples

Responses

200 OK

limitnumber
The maximum number of items returned.
offsetnumber
The number of items skipped before retrieving the returned items.
countnumber
The total number of items.
shipping_optionsobject[]
The list of shipping options.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/shipping-options#

Create Shipping Option

Create a shipping option.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

namestring
The flat-rate shipping option's name.
service_zone_idstring
The ID of the associated service zone.
shipping_profile_idstring
The ID of the associated shipping profile.
dataobjectOptional
The flat-rate shipping option's data, useful for the fulfillment provider handling its processing.
price_type"flat" | "calculated"
The shipping option's price type. If flat, the shipping option has a fixed price set in prices. Otherwise, the shipping option's price is calculated by the fulfillment provider.
provider_idstring
The ID of the fulfillment provider handling this shipping option.
typeobjectOptional
The shipping option type's details.
pricesobject[]Optional
The shipping option's prices.
type_idstringOptional
The ID of the shipping option type that this shipping option belongs to.
rulesobject[]Optional
The shipping option's rules.
metadataobjectOptional
The shipping option's metadata.

Request examples

Responses

200 OK

shipping_optionobject
The shipping option's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • shipping-option.created: Emitted when shipping options are created.

GET /admin/shipping-options/{id}#

Get a Shipping Option

Retrieve a shipping option by its ID. You can expand the shipping option's relations or select the fields that should be returned.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The shipping option's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request examples

Responses

200 OK

shipping_optionobject
The shipping option's details.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/shipping-options/{id}#

Update a Shipping Option

Update a shipping option's details.

When you provide the prices array, it replaces the shipping option's existing flat-rate prices:

  • A price with a matching id is updated.
  • A price without an id is created
  • Any existing price whose id isn't included in the array is deleted.

The rules you provide for a price similarly replace that price's existing rules, so omit a rule to remove it.

Omitting the prices property entirely leaves the existing prices unchanged, whereas setting price_type to calculated removes all flat-rate prices.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The shipping option's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. If a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. Without prefix it will replace the entire default fields.

Request body (application/json)

namestringOptional
The shipping option's name.
dataobjectOptional
The shipping option's data.
price_type"flat" | "calculated"Optional
The shipping option's price type.
provider_idstringOptional
The shipping option's provider id.
shipping_profile_idstringOptional
The shipping option's shipping profile id.
typeobjectOptional
The shipping option type's details.
type_idstringOptional
The shipping option's type id.
pricesobject[]Optional
The shipping option's prices. This array replaces the shipping option's existing prices - a price with a matching id is updated, a price without an id is created, and any existing price whose id isn't included is deleted. Omit this property to leave the existing prices unchanged.
rulesobject[]Optional
The shipping option's rules.
metadataobjectOptional
The shipping option's metadata.

Request examples

Responses

200 OK

shipping_optionobject
The shipping option's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • shipping-option.updated: Emitted when shipping options are updated.

DELETE /admin/shipping-options/{id}#

Delete a Shipping Option

Delete a shipping option.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The shipping option's ID.

Request examples

Responses

200 OK

idstring
The shipping option's ID.
objectstring
The name of the deleted object.

Default: "shipping_option"

deletedboolean
Whether the shipping option was deleted.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • shipping-option.deleted: Emitted when shipping options are deleted.

POST /admin/shipping-options/{id}/rules/batch#

Manage the Rules of a Shipping Option

Manage the rules of a shipping option to create, update, or delete them.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The shipping option's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

createobject[]Optional
The shipping option rules to create.
updateobject[]Optional
The shipping option rules to update.
deletestring[]Optional
The shipping option rules to delete.

Request examples

Responses

200 OK

createdobject[]
The created shipping option rules.
updatedobject[]
The updated shipping option rules.
deletedobject
The details of the deleted shipping option rules.

400, 401, 404, 409, 422, 500: an error response is returned.

Found a problem with this page?Report Issue
Edited Nov 14·Edit this page