Developer : Shipping groups

Manage applications

The /shipping_groups resource contains a list of the store's shipping groups and their available shipping options. Products that belong to a shipping group may be shipped using one of the group's available options.

Resource URI

/api/v1/shipping_groups

Method Scope Required
GET, POST admin

Shipping Group Properties

Property Methods Description
id GET The shipping group's unique id
name GET, PUT, POST The shipping group's name
options GET, PUT, POST A list of the available shipping options in the group. PUT and POST must be a JSON-formatted string. See Shipping Option Properties below

Shipping Option Properties

Property Methods Description
id GET The shipping option's unique id
currency GET The flat per-cart rate and flat per-item rates are in this currency
destinations GET, POST A list of dictionaries representing destinations. POST must be a JSON-formatted string. See Destination Properties below
name GET, POST Name of the shipping option
per_cart_type GET, POST The type of calculation applied to the cart as a whole. One of flat_fee or percentage
per_cart_rate GET The shipping amount (either percentage or flat fee) as a formatted string
per_cart_rate_raw GET, POST The shipping amount in float format
per_item_type GET The type of calculation applied to each item in the cart. One of none (individual items do not affect shipping), flat_per_item (a flat fee is charged for every item), quantity_ranges (a per-item fee is calculated based on the quantity of each line item), or price_ranges (a per-item fee is calculated based on the price of each line item)
price_range_rates GET, POST (For price_ranges per-item types) A list of dictionaries containing item price ranges and their corresponding shipping rates. POST must be a JSON-formatted string. See Shipping Rule Properties below
quantity_range_rates GET, POST (For quantity_ranges per-item types) A list of dictionaries containing item quantity ranges and their corresponding shipping rates. POST must be a JSON-formatted string. See Shipping Rule Properties below
weight_range_rates GET, POST (For weight_ranges per-item types) A list of dictionaries containing item weight ranges and their corresponding shipping rates. POST must be a JSON-formatted string. See Shipping Rule Properties below
per_item_rate GET (For flat_per_item per-item types) The per-item shipping fee as a formatted string
per_item_rate_raw GET, POST (For flat_per_irem per-item types) The per-item shipping fee in float format

Shipping Rule Properties

Property Methods Description
currency GET The currency in which the fee is paid
range_max GET, POST The maximum number this range covers, inclusive
rate GET The fee for this range as a formatted string
rate_raw GET, POST The fee for this range in float format

Subresources

Methods Path Description
GET, PUT, DELETE /api/v1/shipping_groups/{id} A shipping group
GET, POST /api/v1/shipping_groups/{group_id}/options Endpoint for viewing or creating shipping options. When creating shipping options, all shipping options for this group must be passed to the options parameter in a list of dictionaries. Others will be deleted
GET, DELETE /api/v1/shipping_groups/{group_id}/options/{option_id} Endpoint for viewing or deleting a shipping option

Destination Properties

Property Methods Description
allowed GET, POST True if allowed to ship to this destination, False otherwise
country GET, POST A 2-letter ISO country code - e.g. "US" or "CA"
region GET, POST A region/state/province of the passed country formatted as a 2-letter abbreviation for US states and a camel-cased string otherwise

Example Read

curl -H "Authorization: Bearer ba125ac086" \
    https://goodsie.com/api/v1/shipping_groups
[
    {
        "id": 2,
        "name": "UPS Ground",
        "options": [
            {
                "destinations": [
                    {
                        "allowed": true,
                        "country": "CA",
                        "region": "Alberta"
                    }
                ],
                "id": 1,
                "name": "Quick shipping",
                "per_cart_rate": "2%",
                "per_cart_rate_raw": 2.0,
                "per_cart_type": "percentage",
                "per_item_type": "none"
            },
            {
                "currency": "USD",
                "id": 3,
                "name": "Slow shipping",
                "per_cart_rate": "$5.00",
                "per_cart_rate_raw": 5.0,
                "per_cart_type": "flat_fee",
                "per_item_type": "none"
            }
        ]
    },
    {
        "id": 3,
        "name": "Fedex Ground",
        "options": [
            {
                "currency": "USD",
                "id": 4,
                "name": "Yet another shipping rule",
                "per_cart_rate": "$3.00",
                "per_cart_rate_raw": 3.0,
                "per_cart_type": "flat_fee",
                "per_item_rate": "$1.00",
                "per_item_rate_raw": 1.0,
                "per_item_type": "flat_per_item"
            }
        ]
    },
    {
        "id": 8,
        "name": "Custom Shipping",
        "options": [
            {
                "id": 6,
                "name": "Price range rates",
                "per_cart_rate": "10%",
                "per_cart_rate_raw": 10.0,
                "per_cart_type": "percentage",
                "per_item_type": "price_ranges",
                "price_range_rates": [
                    {
                        "currency": "USD",
                        "range_max": 10.0,
                        "rate": "$3.00",
                        "rate_raw": 3.0
                    },
                    {
                        "currency": "USD",
                        "range_max": null,
                        "rate": "$5.00",
                        "rate_raw": 5.0
                    }
                ]
            }
        ]
    }
]

Example Create

curl -H "Authorization: Bearer 9fbad18d9f" -X POST \
    -F name='api-group' \
    -F options='[{"name": "Option Name", "per_cart_rate_raw": 10.0, "per_cart_type": "percentage", "price_range_rates": [{"rate_raw": 3, "range_max": 15}, {"rate_raw": 2, "range_max": null}]}, {"name": "Option Name 2", "per_cart_rate_raw": 15.0, "per_cart_type": "percentage", "price_range_rates": [{"rate_raw": 6, "range_max": null}], "destinations": [{"allowed": true, "country": "US", "region": "WI"}, {"allowed": false, "country": "CA"}]}]' \
    http://beta.goodsie.com/api/v1/shipping_groups

[
    ... shipping group result ...
]