Skip to main content
POST
/
service-groups
cURL
curl -X POST https://api.goshippo.com/service-groups  \
-H "Authorization: ShippoToken <API_TOKEN>" \
-H "Content-Type: application/json"  \
-d '{
        "name": "UPS shipping",
        "description": "UPS shipping options",
        "flat_rate": "5",
        "flat_rate_currency": "USD",
        "type": "LIVE_RATE",
        "rate_adjustment": 15,
        "service_levels": [
            {
                "account_object_id": "80feb1633d4a43c898f0058506cfd82d",
                "service_level_token": "ups_next_day_air_saver"
            },
            {
                "account_object_id": "80feb1633d4a43c898f0058506cfd82d",
                "service_level_token": "ups_ground"
            }
        ]
    }'
{
  "description": "USPS shipping options",
  "name": "USPS Shipping",
  "type": "FLAT_RATE",
  "object_id": "80feb1633d4a43c898f005850",
  "service_levels": [
    {
      "account_object_id": "80feb1633d4a43c898f0058506cfd82d",
      "service_level_token": "ups_next_day_air_saver"
    }
  ],
  "flat_rate": "5",
  "flat_rate_currency": "USD",
  "free_shipping_threshold_currency": "USD",
  "free_shipping_threshold_min": "5",
  "rate_adjustment": 15,
  "is_active": true
}

Authorizations

​
Authorization
string
header
default:ShippoToken shippo_test_d41a6f04796998570c521a50828eae8e3cccf0eb
required

API key authentication using the ShippoToken scheme. Format: Authorization: ShippoToken <API_TOKEN> Example: Authorization: ShippoToken shippo_live_abc123

Headers

​
SHIPPO-API-VERSION
string
default:2018-02-08

Optional string used to pick a non-default API version to use. See our API version guide.

Example:

"2018-02-08"

Body

application/json
​
description
string
required

Description for the service group

Example:

"USPS shipping options"

​
name
string
required

Name for the service group that will be shown to customers in the response

Example:

"USPS Shipping"

​
type
enum<string>
required

The type of the service group.
LIVE_RATE - Shippo will make a rating request and return real-time rates for the shipping group, only falling back to the specified flat rate amount if no rates match a service level in the service group.
FLAT_RATE - Returns a shipping option with the specified flat rate amount.
FREE_SHIPPING - Returns a shipping option with a price of $0 only if the total cost of items exceeds the amount defined by free_shipping_threshold_min

Available options:
LIVE_RATE,
FLAT_RATE,
FREE_SHIPPING
Example:

"FLAT_RATE"

​
service_levels
object[]
required
​
flat_rate
string

String representation of an amount to be returned as the flat rate if 1. The service group is of type LIVE_RATE and no matching rates were found; or 2. The service group is of type FLAT_RATE. Either integers or decimals are accepted. Required unless type is FREE_SHIPPING

Example:

"5"

​
flat_rate_currency
string

required unless type is FREE_SHIPPING. (ISO 4217 currency)

Example:

"USD"

​
free_shipping_threshold_currency
string

optional unless type is FREE_SHIPPING. (ISO 4217 currency)

Example:

"USD"

​
free_shipping_threshold_min
string

For service groups of type FREE_SHIPPING, this field must be required to configure the minimum cart total (total cost of items in the cart) for this service group to be returned for rates at checkout. Optional unless type is FREE_SHIPPING

Example:

"5"

​
rate_adjustment
integer<int64>

The amount in percent (%) that the service group's returned rate should be adjusted. For example, if this field is set to 5 and the matched rate price is $5.00, the returned value of the service group will be $5.25. Negative integers are also accepted and will discount the rate price by the defined percentage amount.

Example:

15

Response

Service group

​
description
string
required

Description for the service group

Example:

"USPS shipping options"

​
name
string
required

Name for the service group that will be shown to customers in the response

Example:

"USPS Shipping"

​
type
enum<string>
required

The type of the service group.
LIVE_RATE - Shippo will make a rating request and return real-time rates for the shipping group, only falling back to the specified flat rate amount if no rates match a service level in the service group.
FLAT_RATE - Returns a shipping option with the specified flat rate amount.
FREE_SHIPPING - Returns a shipping option with a price of $0 only if the total cost of items exceeds the amount defined by free_shipping_threshold_min

Available options:
LIVE_RATE,
FLAT_RATE,
FREE_SHIPPING
Example:

"FLAT_RATE"

​
object_id
string
required

The unique identifier of the given Service Group object.

Example:

"80feb1633d4a43c898f005850"

​
service_levels
object[]
required
​
flat_rate
string

String representation of an amount to be returned as the flat rate if 1. The service group is of type LIVE_RATE and no matching rates were found; or 2. The service group is of type FLAT_RATE. Either integers or decimals are accepted. Required unless type is FREE_SHIPPING

Example:

"5"

​
flat_rate_currency
string

required unless type is FREE_SHIPPING. (ISO 4217 currency)

Example:

"USD"

​
free_shipping_threshold_currency
string

optional unless type is FREE_SHIPPING. (ISO 4217 currency)

Example:

"USD"

​
free_shipping_threshold_min
string

For service groups of type FREE_SHIPPING, this field must be required to configure the minimum cart total (total cost of items in the cart) for this service group to be returned for rates at checkout. Optional unless type is FREE_SHIPPING

Example:

"5"

​
rate_adjustment
integer<int64>

The amount in percent (%) that the service group's returned rate should be adjusted. For example, if this field is set to 5 and the matched rate price is $5.00, the returned value of the service group will be $5.25. Negative integers are also accepted and will discount the rate price by the defined percentage amount.

Example:

15

​
is_active
boolean

True if the service group is enabled, false otherwise.

Example:

true