External (0.0.1)

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Creates a new Shopify delivery profile with custom shipping zones, rates, and methods. Delivery profiles control which shipping options are available to customers at checkout for subscription orders.

What is a Delivery Profile? A delivery profile defines shipping configurations (zones, rates, methods) for specific products or locations. Subscription memberships can have dedicated delivery profiles with custom shipping pricing (free shipping for VIPs, regional rates, express delivery options, etc.).

Request Body Structure (CreateShippingProfileRequestV2):

{
  "profileName": "VIP Membership Free Shipping",
  "locationInfos": [
    {
      "locationId": "gid://shopify/Location/12345",
      "countryInfos": [
        {
          "countryCode": "US",
          "provinceCodeInfoList": ["CA", "NY", "TX"],
          "deliveryMethodInfo": [
            {
              "name": "Standard Shipping",
              "amount": 0.00,
              "currencyCode": "USD",
              "minWeight": null,
              "maxWeight": null,
              "description": "Free for members"
            },
            {
              "name": "Express Shipping",
              "amount": 9.99,
              "currencyCode": "USD",
              "description": "2-day delivery"
            }
          ]
        }
      ]
    }
  ]
}

Field Explanations:

profileName (string, required):

• Unique name for the delivery profile
• Visible in Shopify admin
• Examples: "Premium Member Shipping", "International Free Shipping", "Express Delivery Profile"
• Max length: 255 characters

locationInfos (array, required):

• Array of store locations this profile applies to
• Get location IDs via Shopify Admin API or /data/locations endpoint
• Can configure different shipping for each warehouse/store
• locationId format: gid://shopify/Location/{numeric_id}

countryInfos (array, required):

• Shipping configuration per country
• countryCode: ISO 3166-1 alpha-2 code ("US", "CA", "GB", etc.)
• provinceCodeInfoList: Optional state/province filtering (e.g., ["CA", "NY"] for US states)
  • Omit to include all provinces/states
  • Use ISO 3166-2 province codes (e.g., "CA" for California, "ON" for Ontario)

deliveryMethodInfo (array, required):

• Shipping methods available for this zone
• name: Method display name ("Standard", "Express", "Overnight")
• amount: Shipping cost (0.00 for free shipping)
• currencyCode: Auto-set to shop currency (do not manually specify)
• minWeight / maxWeight: Optional weight restrictions in grams
• description: Optional customer-facing description

Common Use Cases & Examples:

1. Free Shipping for VIP Members

{
  "profileName": "VIP Free Shipping",
  "locationInfos": [{
    "locationId": "gid://shopify/Location/67890",
    "countryInfos": [{
      "countryCode": "US",
      "deliveryMethodInfo": [{
        "name": "Free Standard Shipping",
        "amount": 0.00,
        "description": "Included with VIP membership"
      }]
    }]
  }]
}

2. Regional Pricing (Different Rates per State)

{
  "profileName": "Regional Shipping",
  "locationInfos": [{
    "locationId": "gid://shopify/Location/12345",
    "countryInfos": [
      {
        "countryCode": "US",
        "provinceCodeInfoList": ["CA", "OR", "WA"],
        "deliveryMethodInfo": [{
          "name": "West Coast Shipping",
          "amount": 4.99
        }]
      },
      {
        "countryCode": "US",
        "provinceCodeInfoList": ["NY", "NJ", "CT"],
        "deliveryMethodInfo": [{
          "name": "East Coast Shipping",
          "amount": 5.99
        }]
      }
    ]
  }]
}

3. Tiered Shipping (Standard + Express)

{
  "profileName": "Multi-Speed Shipping",
  "locationInfos": [{
    "locationId": "gid://shopify/Location/12345",
    "countryInfos": [{
      "countryCode": "US",
      "deliveryMethodInfo": [
        {
          "name": "Standard (5-7 days)",
          "amount": 0.00,
          "description": "Free standard shipping"
        },
        {
          "name": "Express (2-3 days)",
          "amount": 9.99,
          "description": "Faster delivery"
        },
        {
          "name": "Overnight",
          "amount": 24.99,
          "description": "Next business day"
        }
      ]
    }]
  }]
}

Validation Rules:

• profileName: Required, non-empty, max 255 characters
• locationInfos: Must contain at least 1 location
• countryCode: Must be valid ISO 3166-1 alpha-2 code
• provinceCodeInfoList: Optional, must be valid province codes for the country
• deliveryMethodInfo: Must have at least 1 method per country
• amount: Must be >= 0 (cannot be negative)
• locationId: Must exist in Shopify and be active

Common Errors:

400 - Invalid Country Code:

{"error": "Invalid country code 'USA'. Use 'US' instead (ISO 3166-1 alpha-2)"}

Solution: Use 2-letter codes (US, CA, GB, AU, etc.)

400 - Invalid Location ID:

{"error": "Location not found: gid://shopify/Location/99999"}

Solution: Verify location exists via /data/locations endpoint

400 - Missing Delivery Methods:

{"error": "Country US has no delivery methods configured"}

Solution: Add at least one delivery method to each country

400 - Invalid Province Code:

{"error": "Province code 'California' invalid for US. Use 'CA'"}

Solution: Use 2-letter state codes (CA, NY, TX), not full names

500 - Shopify API Error: Shopify's delivery profile API rejected the request. Common reasons:

• Duplicate profile name
• Missing required Shopify permissions
• Shopify API rate limit exceeded
• Invalid zone configuration

Response (DeliveryProfileDTO): Returns created profile with:

• id: Shopify delivery profile ID
• profileName: Confirmed profile name
• active: Whether profile is active (true by default)
• locationGroupId: Shopify internal location group ID

How to Get Location IDs:

GET /api/data/locations
Response:
{
  "locations": {
    "nodes": [
      {
        "id": "gid://shopify/Location/12345",
        "name": "Main Warehouse"
      }
    ]
  }
}

Best Practices:

1. Test with One Country First: Start with single country, add more after validation
2. Use Descriptive Names: "VIP Free Shipping" better than "Profile 1"
3. Verify Location IDs: Always fetch current locations before creating profile
4. Set Reasonable Rates: Research competitor shipping prices
5. Provide Descriptions: Help customers understand shipping options
6. Weight Limits: Use for heavy items requiring freight shipping

Authentication: Requires API key authentication via X-API-Key header or api_key parameter

Creates a new Shopify delivery profile with shipping zones and rates using the legacy V1 format. For new integrations, prefer the V2 endpoint which supports more advanced configuration.

Key Features:

• Single Location: Configure shipping for primary store location
• Country-Based Zones: Define shipping zones by country
• Fixed Rates: Set flat shipping costs per zone
• Simple Configuration: Straightforward setup for basic shipping needs

Configuration Structure:

• Profile Name: Unique identifier for the delivery profile
• Country Codes: List of countries in the shipping zone
• Shipping Rate: Fixed price for the zone
• Method Name: Display name for the shipping option

Use Cases:

• Simple country-based flat rate shipping
• Basic free shipping configuration
• Legacy system migrations
• Single-warehouse operations

Migration Note: Consider using the V2 endpoint (/api/external/v2/delivery-profiles/v2/create-shipping-profile) for enhanced features like multi-location support, province targeting, and flexible rate types.

Authentication: Requires API key authentication via X-API-Key header or api_key parameter