Shipping

The 19 tools of the Shipping toolset in the Orders area, with their permissions, approval rules and inputs.

Toolset shipping, 19 tools.

Every courier the store ships with or could add: the built-in manual delivery and each courier app, whether the app is installed, switched on and set up, the locations it is connected to, its services (parcel locker, home delivery) and whether a new shipping option can use it and checkout offers it. id is the provider_id a new shipping option takes; it is null until the app is installed.

Permission: settings.read
Tools: courier_list

Filters on the list:

Filter	Type	Required	Description
`stock_location_id`	string		Only report connections to this location, e.g. the location of a shipping zone

`fulfillment_provider`

A carrier app or the manual provider that ships orders. get adds the options it offers, which a shipping option names in its data.

Permission: settings.read
Tools: fulfillment_provider_list, fulfillment_provider_get

Filters on the list:

Filter	Type	Required	Description
`is_enabled`	boolean
`stock_location_id`	string

`shipping_option`

A delivery method customers pick at checkout, or a return method, as the admin shows it: its courier, pricing, prices, whether checkout shows it, its conditions, zone, location and shipping profile, plus the ids the write tools take. The courier of an existing option is fixed. With order_id, the options that order can use.

Permission: settings.read
Tools: shipping_option_list, shipping_option_get
Sorts: created_at, name

Filters on the list:

Filter	Type	Description
`order_id`	string	Only the options that can ship this order, e.g. for a return or an edit
`q`	string
`service_zone_id`	string
`shipping_profile_id`	string
`stock_location_id`	string
`is_return`	boolean	Return options only, or outbound only

`shipping_option_type`

A label shipping options are grouped under, e.g. Standard or Express.

Permission: settings.read
Tools: shipping_option_type_list, shipping_option_type_get
Sorts: created_at, label

Filters on the list:

Filter	Type	Required	Description
`q`	string
`code`	string

`shipping_profile`

A group of products that ship the same way; every shipping option belongs to one profile.

Permission: settings.read
Tools: shipping_profile_list, shipping_profile_get
Sorts: created_at, name

Filters on the list:

Filter	Type	Required	Description
`q`	string
`type`	string

Actions

`shipping_option_create`

Add a delivery or return method to a service zone.

provider_id is the id of a courier from courier_list that is connected to the location of the zone, and data is {"id": <one of its services>}; service_zone_id from shipping_option_list or fulfillment_set_list. Give type_id of an existing shipping option type or a new type, not both. A rule enabled_in_store eq "true" shows it at checkout; is_return eq "true" makes it a return method.

Action key: shipping_option.create
Permission: settings.write
Approval: Waits for approval when the store requires it for this action.
Effect: Changes the live store.
Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Field	Type	Required	Description
`name`	string	yes	at least 1 characters
`service_zone_id`	string	yes
`shipping_profile_id`	string	yes
`provider_id`	string	yes
`price_type`	string	yes	one of "flat", "calculated"
`prices`	list of object, one shape of:	yes	Flat prices per currency or region; empty for calculated
`type_id`	string
`type`	object
`type.label`	string	yes
`type.code`	string	yes
`type.description`	string
`rules`	list of object
`rules[].attribute`	string	yes	e.g. enabled_in_store or is_return
`rules[].operator`	string	yes	one of "in", "eq", "ne", "gt", "gte", "lt", "lte", "nin"
`rules[].value`	string or list of string	yes
`data`	map of string or number or boolean or list of any value or map of any value or null		The provider option chosen

Example input:

{
  "name": "Home delivery",
  "service_zone_id": "019bb6f0-e6c3-7b49-9df3-11f85d8b1249",
  "shipping_profile_id": "019bb73d-bcc5-7993-83c9-5c9a9f7ada5a",
  "provider_id": "manual_manual",
  "price_type": "flat",
  "prices": [
    {
      "currency_code": "huf",
      "amount": 1490
    }
  ],
  "type_id": "019bb738-31cf-70f8-a14c-805d6a641a07",
  "rules": [
    {
      "attribute": "enabled_in_store",
      "operator": "eq",
      "value": "true"
    }
  ]
}

`shipping_option_delete`

Delete a shipping option; customers can no longer pick it.

Action key: shipping_option.delete
Permission: settings.write
Approval: Always waits for a person to approve it.
Effect: Changes the live store.
Destructive: in compact mode it runs with run_destructive_action.
Retries: safe to repeat with the same input.

Field	Type	Required	Description
`shipping_option_id`	string	yes	Shipping option ID (so_…)

Example input:

{
  "shipping_option_id": "019bb70f-16d0-75b7-bdb6-d22f3f99c289"
}

`shipping_option_rules_delete`

Delete rules of a shipping option, which can offer it to more customers.

Read the rule ids with shipping_option_get.

Action key: shipping_option_rules.delete
Permission: settings.write
Approval: Always waits for a person to approve it.
Effect: Changes the live store.
Destructive: in compact mode it runs with run_destructive_action.
Retries: safe to repeat with the same input.

Field	Type	Required	Description
`shipping_option_id`	string	yes	Shipping option ID (so_…)
`rule_ids`	list of string	yes	at least 1 items

Example input:

{
  "shipping_option_id": "019bb70f-16d0-75b7-bdb6-d22f3f99c289",
  "rule_ids": [
    "019bb72d-35a9-7cb6-a1fe-3572dae8ee66"
  ]
}

`shipping_option_type_create`

Add a label to group shipping options under, e.g. Express.

Action key: shipping_option_type.create
Permission: settings.write
Approval: Waits for approval when the store requires it for this action.
Effect: Changes the live store.
Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Field	Type	Required
`label`	string	yes
`code`	string	yes
`description`	string

Example input:

{
  "label": "Express",
  "code": "express"
}

`shipping_option_type_delete`

Delete a shipping option type no shipping option uses.

Action key: shipping_option_type.delete
Permission: settings.write
Approval: Always waits for a person to approve it.
Effect: Changes the live store.
Destructive: in compact mode it runs with run_destructive_action.
Retries: safe to repeat with the same input.

Field	Type	Required	Description
`shipping_option_type_id`	string	yes	Shipping option type ID

Example input:

{
  "shipping_option_type_id": "019bb738-31cf-70f8-a14c-805d6a641a07"
}

`shipping_option_type_update`

Change a shipping option type's label, code or description.

Action key: shipping_option_type.update
Permission: settings.write
Approval: Waits for approval when the store requires it for this action.
Effect: Changes the live store.
Retries: safe to repeat with the same input.

Field	Type	Required	Description
`shipping_option_type_id`	string	yes	Shipping option type ID
`label`	string
`code`	string
`description`	string

Example input:

{
  "shipping_option_type_id": "019bb738-31cf-70f8-a14c-805d6a641a07",
  "label": "Next day"
}

`shipping_option_update`

Change a shipping option's name, prices, profile, type or rules.

prices replaces the price list; pass a price id to keep and change one. rules adds and updates (by id) rules; shipping_option_rules_delete removes them.

Action key: shipping_option.update
Permission: settings.write
Approval: Waits for approval when the store requires it for this action.
Effect: Changes the live store.
Retries: safe to repeat with the same input.

Field	Type	Required	Description
`shipping_option_id`	string	yes	Shipping option ID (so_…)
`name`	string		at least 1 characters
`shipping_profile_id`	string
`price_type`	string		one of "flat", "calculated"
`prices`	list of object
`prices[].id`	string
`prices[].currency_code`	string
`prices[].region_id`	string
`prices[].amount`	number		at least 0
`type_id`	string
`rules`	object
`rules.create`	list of object
`rules.create[].attribute`	string	yes	e.g. enabled_in_store or is_return
`rules.create[].operator`	string	yes	one of "in", "eq", "ne", "gt", "gte", "lt", "lte", "nin"
`rules.create[].value`	string or list of string	yes
`rules.update`	list of object
`rules.update[].attribute`	string	yes	e.g. enabled_in_store or is_return
`rules.update[].operator`	string	yes	one of "in", "eq", "ne", "gt", "gte", "lt", "lte", "nin"
`rules.update[].value`	string or list of string	yes
`rules.update[].id`	string	yes

Example input:

{
  "shipping_option_id": "019bb70f-16d0-75b7-bdb6-d22f3f99c289",
  "prices": [
    {
      "currency_code": "huf",
      "amount": 1990
    }
  ]
}

`shipping_profile_create`

Add a group for products that ship the same way, e.g. bulky items.

Action key: shipping_profile.create
Permission: settings.write
Approval: Waits for approval when the store requires it for this action.
Effect: Changes the live store.
Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Field	Type	Required	Description
`name`	string	yes	at least 1 characters
`type`	string	yes	e.g. default or bulky. at least 1 characters

Example input:

{
  "name": "Bulky items",
  "type": "bulky"
}

`shipping_profile_delete`

Delete a shipping profile that no product or shipping option uses.

Action key: shipping_profile.delete
Permission: settings.write
Approval: Always waits for a person to approve it.
Effect: Changes the live store.
Destructive: in compact mode it runs with run_destructive_action.
Retries: safe to repeat with the same input.

Field	Type	Required	Description
`shipping_profile_id`	string	yes	Shipping profile ID (sp_…)

Example input:

{
  "shipping_profile_id": "019bb73d-bcc5-7993-83c9-5c9a9f7ada5a"
}

`shipping_profile_update`

Rename a shipping profile or change its type.

Action key: shipping_profile.update
Permission: settings.write
Approval: Waits for approval when the store requires it for this action.
Effect: Changes the live store.
Retries: safe to repeat with the same input.

Field	Type	Required	Description
`shipping_profile_id`	string	yes	Shipping profile ID (sp_…)
`name`	string		at least 1 characters
`type`	string		at least 1 characters

Example input:

{
  "shipping_profile_id": "019bb73d-bcc5-7993-83c9-5c9a9f7ada5a",
  "name": "Furniture"
}

AI

Shipping

Records

`courier`

`fulfillment_provider`

`shipping_option`

`shipping_option_type`

`shipping_profile`

Actions

`shipping_option_create`

`shipping_option_delete`

`shipping_option_rules_delete`

`shipping_option_type_create`

`shipping_option_type_delete`

`shipping_option_type_update`

`shipping_option_update`

`shipping_profile_create`

`shipping_profile_delete`

`shipping_profile_update`

Shipping

RecordsCopy Anchor Link

courierCopy Anchor Link

fulfillment_providerCopy Anchor Link

shipping_optionCopy Anchor Link

shipping_option_typeCopy Anchor Link

shipping_profileCopy Anchor Link

ActionsCopy Anchor Link

shipping_option_createCopy Anchor Link

shipping_option_deleteCopy Anchor Link

shipping_option_rules_deleteCopy Anchor Link

shipping_option_type_createCopy Anchor Link

shipping_option_type_deleteCopy Anchor Link

shipping_option_type_updateCopy Anchor Link

shipping_option_updateCopy Anchor Link

shipping_profile_createCopy Anchor Link

shipping_profile_deleteCopy Anchor Link

shipping_profile_updateCopy Anchor Link

Records

`courier`

`fulfillment_provider`

`shipping_option`

`shipping_option_type`

`shipping_profile`

Actions

`shipping_option_create`

`shipping_option_delete`

`shipping_option_rules_delete`

`shipping_option_type_create`

`shipping_option_type_delete`

`shipping_option_type_update`

`shipping_option_update`

`shipping_profile_create`

`shipping_profile_delete`

`shipping_profile_update`