Dev Backup and Restore file format
Location Backups File Format
Latest version: 1.0
The Parcelify location backup format is a list o JSON-style fields, objects (maps/dict), and arrays which compose a single location in Parcelify. It is read from top to bottom and, where applicable, each proceeding line contributes to the structure above.
Pseudo example:
(version information)
Zone 1 (countries, provinces, and restrictions for zone 1)
Rate A (restrictions and prices for this rate)
Rate B (restrictions and prices for this rate)
Zone 2
Rate C
Zones belong to locations, rates belong to zones, and price objects are contained by their corresponding rates. So in the example above, Zone 1 belongs to the Location, Rate A and B belong to the first zone, Zone 2 belongs to the location, and rate C belongs to Zone 2.
Here is a code example demonstrating a single location, zone, and price:
{"version":"0.1"}
{"type":"zone","zone":{"name":"Domestic"},"zone_countries":[{"country_code":"CA","zone_provinces":[{"province_code":"ON"}]}],"zone_product_restrictions":[]}
{"type":"shipping_rate","shipping_rate":{"name":"Standard","code":"std"},"restrictions":{},"product_restrictions":{},"pricing_strategies":[{"price_strategy":"flat_rate","subject":"products","price":9.99,"value_restriction":{}}]}
Example file
For a more complete example featuring multiple zones, fields, and restrictions, you may download and inspect the following file locally:
[Backup Sample File]
Backup and Restore field definitions
Below are a list of all fields, objects and arrays that may appear in a location backup file, along with some examples of how the information should be formatted. This should prove useful to scrappy customers who wish to edit their backup data or run into errors during import:
Note: Some “required” fields are only required if their context is present. If a zone does not have any product restrictions for example, then restriction_strategy, restriction_value, and restriction_context are not required despite being marked as such. They are only required if the optional key (zone_product_restrictions) is present.
Zones
Zone fields
| Name | Type | Required | Description | |
|---|---|---|---|---|
| type | String | Yes | Must be "zone" | |
| zone | Object | Yes | Zone attributes (see below) | |
| zone_countries | Array | Yes | Countries and provinces in the zone (see below) | |
| zone_product_restrictions | Array | Optional | Product/option restrictions for the zone (see below). Can be empty [] | |
Zone objects
zone
| Name | Type | Required | Description | |
|---|---|---|---|---|
| id | Number | Optional | Zone ID from the backing store. When present on restore, an existing zone with this id is updated instead of creating a new zone | |
| name | String | Yes | Zone name | |
Zone arrays
zone_countries
| Name | Type | Required | Description | |
|---|---|---|---|---|
| country_code | String | Yes | ISO country code (e.g. "CA", "US") | |
| zone_provinces | Array | Optional | Provinces/states in that country | |
zone_provinces
| Name | Type | Required | Description | |
|---|---|---|---|---|
| province_code | String | Yes | Province/state code (e.g. "ON", "NY") | |
zone_product_restrictions
| Name | Type | Required | Description | |
|---|---|---|---|---|
| ID | Number | Optional | ID when updating existing zone restrictions | |
| restriction_strategy | String | Yes | How restricted products should be identified (e.g. product_tag_is) | |
| restriction_value | String | Yes | Value of the strategy (e.g. comma-separated list of tag names) | |
| restriction_context | String | Optional | Legacy placeholder, may be removed in future schema | |
| product_options_restrictions | Array | Optional | Option-level restrictions | |
product_option_restrictions
| Name | Type | Required | Description | |
|---|---|---|---|---|
| context | String | Yes | Option context (e.g. "size") | |
| restriction_strategy | String | Yes | How restricted options should be identified (e.g. product_option_is) | |
| restriction_value | String | Yes | Value of this option field (e.g. comma-separated list of product sizes) | |
Rates
Rate fields
| Name | Type | Required | Description | |
|---|---|---|---|---|
| type | String | Yes | Must be "shipping_rate" | |
| shipping_rate | Object | Yes | Rate attributes (name, code, delivery, etc) | |
| restrictions | Object | Optional | Rate-level restrictions (price, weight, customer). Can be empty {} | |
| product_restrictions | Object | Optional | Product/option restrictions on the rate. Can be empty {} | |
| pricing_strategies | Array | Optional | One or more pricing strategies. Can be empty [] | |
Rate objects
shipping_rate
| Name | Type | Required | Description | |
|---|---|---|---|---|
| id | Number | Optional | Rate ID from backing store. When present on restore, an existing rate with this ID is updated instead of creating a new rate | |
| zone_id | Number | Optional | The Zone ID this rate belongs to. Used when rate lines appear out-of-zone-order so restore can attribute the rate to the correct zone | |
| name | String | Yes | Rate name | |
| description | String | Optional | The rate description | |
| code | String | Optional | The Rate service code (must be unique) | |
| disabled | Boolean | Optional | Whether the rate is disabled | |
| delivery_time | Number | Optional | The minimum delivery time | |
| max_delivery_time | Number | Optional | The maximum delivery time | |
| delivery_interval | String | Optional | What periodicity the delivery times represent (e.g. "business_days") | |
| rate_type | String | Optional | "delivery" or "pickup" as applicable | |
restrictions
| Name | Type | Required | Description | |
|---|---|---|---|---|
| postal_code_is | Object | Optional | A key value-pair representing where this rate is valid (e.g. { "value": "M5V 1A1" }) | |
| shipment_weight_kg | Object | Optional | A key-value pair representing the weight range for this rate (e.g. { "start_value": 10, "end_value": 30 }) | |
| shipment_value | Object | Optional | A key-value pair representing the total order price this rate is allowed (e.g. { "start_value": 10, "end_value": 500 }) | |
| customer_tag_is | Object | Optional | A key-value pair representing what customers this order applies to (e.g. { "value": "VIP" } | |
product_restrictions
| Name | Type | Required | Description | |
|---|---|---|---|---|
| ID | Number | Optional | ID when updating existing zone restrictions | |
| restriction_strategy | String | Yes | How restricted products should be identified (e.g. product_tag_is) | |
| restriction_value | String | Yes | Value of the strategy (e.g. comma-separated list of tag names) | |
| restriction_context | String | Optional | Legacy placeholder, may be removed in future schema | |
| product_options_restrictions | Array | Optional | Option-level restrictions | |
| all_must_match | Boolean | Optional | True if every product must match this restriction | |
Pricing Strategies
Pricing strategies are a unique kind of rate array in that they can have many different possible strategies and field shapes. We will cover all of the most common ones here with examples.
Fields available in all pricing strategies:
| Name | Example | ||
|---|---|---|---|
| value_restriction | {"start_value":"1","end_value":"10"} |
||
| destination_restriction | {"restriction_strategy":"postcode_is","restriction_value":"90210"} |
||
| customer_restriction | {"restriction_strategy":"customer_is_not","restriction_value":"wholesale"} |
||
| product_restrictions | [{"restriction_strategy":"product_tag_is","restriction_value":"LTL, Freight"}] |
||
single-price
Subject: products
Possible types for this price strategy:
-
flat_rate
-
flat-one_price
-
weight-one_price
-
price-one_price
-
item-one_price
-
volumetric-one_price
Example:
[{"price_strategy":"flat_rate","subject":"products","price":9.99","value_restriction":{}}]
tiered
Subject: tiered_prices
Possible types for this price strategy:
-
weight-tiered_prices
-
price-tiered_prices
-
item-tiered_prices
-
volumetric-tiered_prices
Example:
[{"price_strategy":"item-tiered_prices","subject":"tiered_prices","tiered_prices":
[{"start_value":"1","end_value":"10","price":"5"},
{"start_value":"11","end_value":"15","price":"20"}],"value_restriction":{}}]
tiered-by-destination
Subject: tiered_destination_prices
Possible types for this price strategy:
-
weight-tiered_destination_prices
-
price-tiered_destination_prices
-
item-tiered_destination_prices
Example:
[{"price_strategy":"weight-tiered_destination_prices","subject":"tiered_destination_prices",
"tiered_destination_prices":[{"restriction_strategy":"postcode_is", "restriction_value":"90210", "tiered_prices":
[{"start_value":"1","end_value":"10","price":"5"},
{"start_value":"11","end_value":"15","price":"20"}]}],"value_restriction":{}}]