Create a shipping method

POST/v1/api/store/{team_slug}/setting/shipping_type

v1Operation ID v1_public_shipping_type_store

Creates a shipping method and returns it. An integration method uses one service of a connected carrier integration; the others are your own.

The team's first shipping method becomes its default. default in the body doesn't change the default when the team already has one; update the method with default: true afterwards.

Shipping methods say how a shipment goes out: by courier, your own delivery, customer pick-up, or a service of a connected carrier integration such as UPS or FedEx. Each shipment names its method with shipping_type_id. YoPrint makes the GoShippo and Shopify fulfillment methods itself.

Permission

Needs the Manage Settings permission.

Business rules

type is courier, self_delivery, pick_up or integration. GoShippo and Shopify fulfillment methods cannot be created.
An integration method needs external_integration_id (a shipping integration), a service_code that integration offers, price_percent and min_price.
Percentages are whole numbers (a percentage ×1000: 8250 is 8.25%). Prices are whole numbers in thousandths (12500 is 12.50).
The type cannot be changed later.

Path parameters

team_slugstringrequired
Your team slug, shown as Team ID next to your API key in Profile.
- Example your-team

Request body

application/json, required.

What kind of method?

Send one of these 2 bodies.

Your own method Carrier integration service

Your own method

Courier, your own delivery, or pick-up.

namestringrequired
typestringrequired
- One of: "courier", "self_delivery", "pick_up"
defaultboolean
Has no effect when the team already has a default.
min_priceinteger
The Minimum Price. Send a whole number of thousandths: 12500 is 12.50. Defaults to 0.
price_percentinteger
The Markup Percentage or Margin Percentage. Send a whole number as a percentage ×1000: 8250 is 8.25%, 10000 is 10%. Defaults to 0.
price_typestring
Pricing calculation type: markup (markup percentage on carrier cost) or margin (profit margin percentage). Defaults to markup. Stored with the method; the API does not apply this calculation to shipment prices.
- One of: "markup", "margin"

Example request

curl

curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/setting/shipping_type' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "name": "Local delivery",    "type": "self_delivery"  }'

Carrier integration service

One service of a connected shipping integration.

typestringrequired
- Always "integration"
external_integration_idstringrequired
The id of a connected shipping integration (Settings, Apps).
min_priceintegerrequired
The Minimum Price. Send a whole number of thousandths: 12500 is 12.50. Defaults to 0.
namestringrequired
price_percentintegerrequired
The Markup Percentage or Margin Percentage. Send a whole number as a percentage ×1000: 8250 is 8.25%, 10000 is 10%. Defaults to 0.
service_codestringrequired
A service code the integration offers.
defaultboolean
Has no effect when the team already has a default.
price_typestring
Pricing calculation type: markup (markup percentage on carrier cost) or margin (profit margin percentage). Defaults to markup. Stored with the method; the API does not apply this calculation to shipment prices.
- One of: "markup", "margin"

Example request

curl

curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/setting/shipping_type' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "external_integration_id": "bHTF18MXCEJwKc",    "min_price": 5000,    "name": "UPS Ground",    "price_percent": 10000,    "price_type": "markup",    "service_code": "ground",    "type": "integration"  }'

Response

200Successful response.

dataobjectrequired
Child fields (10)
- defaultbooleanrequired
  Whether it is the team's default shipping method.
- external_integration_idstring | nullrequired
  The carrier integration, for integration methods.
- idstringrequired
- min_priceintegerrequired
  The Minimum Price. Thousandths, an older encoding: 12500 is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities. Stored only, like price_type.
- namestringrequired
- price_percentintegerrequired
  The Markup Percentage or Margin Percentage as a percentage ×1000: 8250 is 8.25%, 10000 is 10%. Stored only, like price_type.
- price_typestringrequired
  Pricing calculation type: markup (markup percentage on carrier cost) or margin (profit margin percentage). Stored and displayed in the web app; the API does not apply this calculation to shipment prices.
  - One of: "markup", "margin"
- service_codestring | nullrequired
  The carrier's service code, for integration methods.
- trashedbooleanrequired
  True for a deleted shipping method.
- typestringrequired
  courier, self_delivery, pick_up: your own methods. integration: a service of a connected carrier integration. integration_shippo and shopify_fulfillment are made by YoPrint.
  - One of: "courier", "self_delivery", "pick_up", "integration", "integration_shippo", "shopify_fulfillment"
statusintegerrequired
successbooleanrequired

Errors

401The API key is missing or wrong (unauthenticated).
When
The API key is missing or wrong.
Fix
Send your personal API key as Authorization: Bearer YOUR_API_KEY.
403You are not allowed to do this. api_access_not_in_plan: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only {"message": "Insufficient Permission"}. Other refusals use the error envelope, with unauthorized or user_is_not_authorized.
When
Your permission group lacks Manage Settings. This 403 has a short body, {"message": "Insufficient Permission"}, without success or error.
Fix
Ask the team owner to give your permission group Manage Settings.
404Not found. page_not_found: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. code: null, with a message that starts "No query results for": there is no record with that id.
When
external_integration_id names no integration of this team, for example a deleted one (error.code null, "No query results…").
Fix
Use an id from List integrations.
422The request was refused and changed nothing. validation_failed lists what to fix in error.fields; other codes name a business rule, explained in error.message. A few checks answer with only {"message": "..."}. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer connect_timeout ("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.
When
A required field is missing, type is not allowed, external_integration_id is not a hash id, or a number is not a whole number. error.code is validation_failed, and error.fields names each field with its messages.
Fix
Fix the fields listed in error.fields and send the request again.
500A business rule refused the request (see the operation's errors), or something failed inside YoPrint. Refusals use the error envelope with a code such as action_not_allowed; an unexpected failure answers {"message": "Server Error"}. Repeating a refusal gets the same answer; after an unexpected failure, read the record back before you retry a change.
When
The integration is not a shipping integration, or doesn't offer service_code. YoPrint answers with a generic server error ({"message": "Server Error"}) that doesn't say which; nothing is created.
Fix
Check that the id is a connected shipping integration and that it offers the service code, then try again.

PATCHMake a shipping method the default/v1/api/store/{team_slug}/setting/shipping_type/{hash_id}
GETList integrations/v1/api/store/{team_slug}/setting/external_integration

Example request: Your own method

curl

curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/setting/shipping_type' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "name": "Local delivery",    "type": "self_delivery"  }'

curl

curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/setting/shipping_type' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "external_integration_id": "bHTF18MXCEJwKc",    "min_price": 5000,    "name": "UPS Ground",    "price_percent": 10000,    "price_type": "markup",    "service_code": "ground",    "type": "integration"  }'

Example response 200

{
  "data": {
    "default": false,
    "external_integration_id": null,
    "id": "u16QRJNTkBfHZF",
    "min_price": 0,
    "name": "Local delivery",
    "price_percent": 0,
    "price_type": "markup",
    "service_code": null,
    "trashed": false,
    "type": "self_delivery"
  },
  "status": 200,
  "success": true
}

AI agents: read /llms.txt; add .md to any page URL for its Markdown. Guides and concepts in one file: /llms-full.txt.

Download the OpenAPI spec Support: support@yoprint.com yoprint.com

Create a shipping method

Permission

Business rules

Path parameters

Request body

Your own method

Carrier integration service

Response

Errors

Related