Search Documentation

Search for a documentation page...

Shipping API

REST API endpoints for managing shipping methods shown at checkout.

Shipping methods are the delivery options customers choose at checkout. Each method has a delivery type, a price, optional free-shipping threshold and delivery-time estimates, country restrictions, an associated tax rate, and per-currency price overrides for multi-currency stores.

List Shipping Methods

GET /api/v1/shipping

Query Parameters

ParameterTypeDefaultDescription
limitnumber10Methods per page (1-100)
offsetnumber0Methods to skip
querystring—Search by method name or description

Response

{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "name": "Standard courier",
      "description": "Delivered within 3-5 business days",
      "type": "courier",
      "price": 9.99,
      "freeShippingThreshold": 100,
      "minShippingTime": 3,
      "maxShippingTime": 5,
      "countries": ["US", "CA"],
      "position": 0,
      "taxRateId": "0191abc0-0000-7000-8000-000000000200",
      "currencyPrices": {},
      "createdAt": "2024-05-20T10:30:00.000Z",
      "updatedAt": "2024-05-20T10:30:00.000Z"
    }
  ],
  "meta": {
    "count": 1
  }
}

Create Shipping Method

POST /api/v1/shipping

Creates a checkout delivery option. Prices are in the store's primary currency; use currencyPrices to override per currency on multi-currency stores.

Request Body

FieldTypeRequiredDescription
namestringYesDisplay name shown at checkout, e.g. Standard courier
descriptionstringNoOptional description shown at checkout
type"courier" | "parcel" | "pickup_point" | "in_store"YesDelivery type
pricenumberYesShipping price in the store's primary currency
freeShippingThresholdnumberNoOrder subtotal above which this method is free (store currency)
minShippingTimenumberNoMinimum delivery time in days
maxShippingTimenumberNoMaximum delivery time in days
countriesstring[]NoISO country codes this method ships to (empty = all)
taxRateIdstringNoTax rate UUID to apply to this shipping method
positionnumberNoSort order at checkout (lower shows first)
currencyPricesobjectNoPer-currency overrides ({ "EUR": { "price": 9, "freeShippingThreshold": 90 } })
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Standard courier", "type": "courier", "price": 9.99, "freeShippingThreshold": 100, "countries": ["US", "CA"]}' \
  https://your-store.yns.store/api/v1/shipping

Response (201)

{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "name": "Standard courier",
  "description": null,
  "type": "courier",
  "price": 9.99,
  "freeShippingThreshold": 100,
  "minShippingTime": null,
  "maxShippingTime": null,
  "countries": ["US", "CA"],
  "position": 0,
  "taxRateId": null,
  "currencyPrices": {},
  "createdAt": "2024-06-15T10:30:00.000Z",
  "updatedAt": "2024-06-15T10:30:00.000Z"
}

Get Shipping Method

GET /api/v1/shipping/:id

Returns a single shipping method by UUID, including its tax rate and per-currency prices.

Response

{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "name": "Standard courier",
  "description": "Delivered within 3-5 business days",
  "type": "courier",
  "price": 9.99,
  "freeShippingThreshold": 100,
  "minShippingTime": 3,
  "maxShippingTime": 5,
  "countries": ["US", "CA"],
  "position": 0,
  "taxRateId": "0191abc0-0000-7000-8000-000000000200",
  "currencyPrices": {
    "EUR": {
      "price": 8.99,
      "freeShippingThreshold": 90
    }
  },
  "createdAt": "2024-05-20T10:30:00.000Z",
  "updatedAt": "2024-05-20T10:30:00.000Z"
}

Update Shipping Method

PATCH /api/v1/shipping/:id

Replaces the shipping method's fields. Uses the same body as Create Shipping Method.

Request Body

Same fields as Create Shipping Method.

curl -X PATCH \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Express courier", "type": "courier", "price": 14.99, "minShippingTime": 1, "maxShippingTime": 2}' \
  https://your-store.yns.store/api/v1/shipping/0191abc0-1234-7def-8000-000000000001

Response (200)

{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "name": "Express courier",
  "description": null,
  "type": "courier",
  "price": 14.99,
  "freeShippingThreshold": null,
  "minShippingTime": 1,
  "maxShippingTime": 2,
  "countries": [],
  "position": 0,
  "taxRateId": null,
  "currencyPrices": {},
  "createdAt": "2024-05-20T10:30:00.000Z",
  "updatedAt": "2024-06-15T11:00:00.000Z"
}

Delete Shipping Method

DELETE /api/v1/shipping/:id

Hard-deletes the shipping method by UUID.

curl -X DELETE \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/shipping/0191abc0-1234-7def-8000-000000000001

Response

{
  "ok": true,
  "deleted": 1
}
PreviousLoyaltyAPI ReferenceNextTax RatesAPI Reference