REST API Reference

The ShipRules AI REST API lets you manage your shipping configuration programmatically. All endpoints return JSON and require an API key in the Authorization header.

Base URL: https://shiprules.ai/api

All request bodies use Content-Type: application/json. Prices are always in cents. Weights are in grams.

Zones

List zones

GET /api/zones

Returns all zones for your shop, including subzones.

Response:

{
  "zones": [
    {
      "id": "zone_abc123",
      "name": "United States",
      "countries": ["US"],
      "subzones": [
        {
          "id": "sub_xyz789",
          "name": "Alaska & Hawaii",
          "postalCodes": "99*,96*"
        }
      ]
    }
  ]
}

Product Groups

List product groups

GET /api/groups

Create product group

POST /api/groups

{
  "name": "Heavy Items",
  "isDefault": false
}

Update product group

PUT /api/groups

Delete product group

DELETE /api/groups

Shipping Methods

List methods

GET /api/methods

Query parameters:

zoneId — filter by zone
productGroupId — filter by product group

Get method

GET /api/methods/:id

Returns the method with its rate configuration and rules.

Create method

POST /api/methods

{
  "name": "Standard Shipping",
  "subtitle": "5-7 business days",
  "zoneId": "zone_abc123",
  "productGroupId": "group_def456",
  "rateType": "flat",
  "config": { "price": 999 },
  "enabled": true,
  "freeShippingThreshold": 10000
}

Rate type configurations:

{
  "rateType": "flat",
  "config": { "price": 999 }
}

{
  "rateType": "free",
  "config": {}
}

{
  "rateType": "by_weight_table",
  "config": {
    "weightUnit": "kg",
    "tiers": [
      { "minWeight": 0, "maxWeight": 1, "price": 500 },
      { "minWeight": 1, "maxWeight": 5, "price": 1000 },
      { "minWeight": 5, "maxWeight": 20, "price": 2000 }
    ]
  }
}

{
  "rateType": "by_price_table",
  "config": {
    "tiers": [
      { "minPrice": 0, "maxPrice": 5000, "price": 800 },
      { "minPrice": 5000, "maxPrice": 10000, "price": 500 },
      { "minPrice": 10000, "maxPrice": 99999999, "price": 0 }
    ]
  }
}

{
  "rateType": "by_items",
  "config": {
    "firstItemPrice": 500,
    "additionalItemPrice": 200
  }
}

{
  "rateType": "by_price_percentage",
  "config": {
    "percentage": 5,
    "minCharge": 300,
    "maxCharge": 2000
  }
}

Update method

PUT /api/methods

Delete method

DELETE /api/methods

Rules

List rules for a method

GET /api/rules?methodId=:methodId

Create rule

POST /api/rules

{
  "action": "hide",
  "conditions": [
    {
      "conditionType": "destination_state",
      "operator": "equals",
      "value": "AK,HI",
      "scope": "any_product_in_order"
    }
  ]
}

Available actions: hide, show, free, adjust_add, adjust_subtract

For adjustment actions, also include:

{
  "action": "adjust_add",
  "adjustmentValue": 500,
  "adjustmentType": "flat",
  "conditions": [...]
}

Update rule

PUT /api/rules

Delete rule

DELETE /api/rules

Blended Rates

List blended rates

GET /api/blended

Create blended rate

POST /api/blended

{
  "name": "Combined Shipping",
  "subtitle": "Calculated from all product groups",
  "zoneId": "zone_abc123",
  "freeShippingThreshold": 20000,
  "preferences": [
    { "productGroupId": "group_default", "preferredMethodId": "method_std" },
    { "productGroupId": "group_heavy", "preferredMethodId": null }
  ]
}

When preferredMethodId is null, the lowest available rate for that group is used.

Update blended rate

PUT /api/blended

Delete blended rate

DELETE /api/blended

Versions

List versions

GET /api/versions?limit=20&cursor=version_abc123

Query parameters:

limit — number of versions to return (default: 20)
cursor — pagination cursor (version ID)
includeBatched — if true, show individual batch versions instead of collapsing them

Get version

GET /api/versions/:id

Compare versions

POST /api/versions

{
  "action": "compare",
  "versionA": "version_abc",
  "versionB": "version_xyz"
}

Returns { added: [...], modified: [...], removed: [...] }.

Rollback

POST /api/versions

{
  "action": "rollback",
  "targetVersionId": "version_abc123"
}

Restores the configuration to the state at this version. Creates a new version with createdBy “rollback”.

Staging (Shadow Mode)

Enter staging

POST /api/staging

{ "action": "enter" }

Get shadow results

GET /api/staging

Returns shadow comparison results from the active staging changeset.

Promote staged changes

POST /api/staging

{ "action": "promote" }

Discard staged changes

POST /api/staging

{ "action": "discard" }

Configuration Export/Import

Export configuration

GET /api/config

Returns the full shop configuration as a JSON snapshot.

Import configuration (preview)

POST /api/config

{
  "action": "preview",
  "data": { "productGroups": [...], "zones": [...], "methods": [...], "blendedRates": [...] }
}

Returns a preview of what would change without applying.

Import configuration (execute)

POST /api/config

{
  "action": "execute",
  "data": { "productGroups": [...], "zones": [...], "methods": [...], "blendedRates": [...] }
}

Replaces the current configuration. A version record is created automatically.

Rate Simulation

POST /api/simulate

See Rate Simulation for full details on the simulation endpoint.

Error format

All errors follow this format:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Shipping method method_abc123 not found"
  }
}

Status	Code	Meaning
400	`VALIDATION_ERROR`	Invalid request body or parameters
401	`UNAUTHORIZED`	Missing or invalid API key
403	`FORBIDDEN`	Insufficient permissions
404	`NOT_FOUND`	Resource not found
409	`CONFLICT`	Conflict (e.g., trying to enter staging when already in staging)
422	`PLAN_LIMIT_EXCEEDED`	Operation exceeds your plan’s limits
429	`RATE_LIMITED`	Too many requests
500	`INTERNAL_ERROR`	Something went wrong on our end