Change a custom package to an envelope
Description
Change a saved custom package from a box to an envelope by setting its `type` to `ENVELOPE`. Shopify sets an envelope's height to 0.75 inches, whatever height you submit.
Query
mutation shippingPackageUpdate($id: ID!, $shippingPackage: CustomShippingPackageInput!) {
shippingPackageUpdate(id: $id, shippingPackage: $shippingPackage) {
userErrors {
field
message
}
}
}
Variables
{
"id": "gid://shopify/ShippingPackageV2/1071084921",
"shippingPackage": {
"name": "Envelope test",
"type": "ENVELOPE",
"weight": {
"value": 15,
"unit": "GRAMS"
},
"dimensions": {
"length": 2,
"width": 1,
"height": 5,
"unit": "INCHES"
}
}
}
cURL
curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation shippingPackageUpdate($id: ID!, $shippingPackage: CustomShippingPackageInput!) { shippingPackageUpdate(id: $id, shippingPackage: $shippingPackage) { userErrors { field message } } }",
"variables": {
"id": "gid://shopify/ShippingPackageV2/1071084921",
"shippingPackage": {
"name": "Envelope test",
"type": "ENVELOPE",
"weight": {
"value": 15,
"unit": "GRAMS"
},
"dimensions": {
"length": 2,
"width": 1,
"height": 5,
"unit": "INCHES"
}
}
}
}'
React Router
import { authenticate } from "../shopify.server";
export const loader = async ({request}) => {
const { admin } = await authenticate.admin(request);
const response = await admin.graphql(
`#graphql
mutation shippingPackageUpdate($id: ID!, $shippingPackage: CustomShippingPackageInput!) {
shippingPackageUpdate(id: $id, shippingPackage: $shippingPackage) {
userErrors {
field
message
}
}
}`,
{
variables: {
"id": "gid://shopify/ShippingPackageV2/1071084921",
"shippingPackage": {
"name": "Envelope test",
"type": "ENVELOPE",
"weight": {
"value": 15,
"unit": "GRAMS"
},
"dimensions": {
"length": 2,
"width": 1,
"height": 5,
"unit": "INCHES"
}
}
},
},
);
const json = await response.json();
return json.data;
}
Ruby
session = ShopifyAPI::Auth::Session.new(
shop: "your-development-store.myshopify.com",
access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
session: session
)
query = <<~QUERY
mutation shippingPackageUpdate($id: ID!, $shippingPackage: CustomShippingPackageInput!) {
shippingPackageUpdate(id: $id, shippingPackage: $shippingPackage) {
userErrors {
field
message
}
}
}
QUERY
variables = {
"id": "gid://shopify/ShippingPackageV2/1071084921",
"shippingPackage": {
"name": "Envelope test",
"type": "ENVELOPE",
"weight": {
"value": 15,
"unit": "GRAMS"
},
"dimensions": {
"length": 2,
"width": 1,
"height": 5,
"unit": "INCHES"
}
}
}
response = client.query(query: query, variables: variables)
Node.js
const client = new shopify.clients.Graphql({session});
const data = await client.query({
data: {
"query": `mutation shippingPackageUpdate($id: ID!, $shippingPackage: CustomShippingPackageInput!) {
shippingPackageUpdate(id: $id, shippingPackage: $shippingPackage) {
userErrors {
field
message
}
}
}`,
"variables": {
"id": "gid://shopify/ShippingPackageV2/1071084921",
"shippingPackage": {
"name": "Envelope test",
"type": "ENVELOPE",
"weight": {
"value": 15,
"unit": "GRAMS"
},
"dimensions": {
"length": 2,
"width": 1,
"height": 5,
"unit": "INCHES"
}
}
},
},
});
Shopify CLI
shopify app execute \
--query \
'mutation shippingPackageUpdate($id: ID!, $shippingPackage: CustomShippingPackageInput!) {
shippingPackageUpdate(id: $id, shippingPackage: $shippingPackage) {
userErrors {
field
message
}
}
}' \
--variables \
'{
"id": "gid://shopify/ShippingPackageV2/1071084921",
"shippingPackage": {
"name": "Envelope test",
"type": "ENVELOPE",
"weight": {
"value": 15,
"unit": "GRAMS"
},
"dimensions": {
"length": 2,
"width": 1,
"height": 5,
"unit": "INCHES"
}
}
}'
Direct API Access
const response = await fetch('shopify:admin/api/2026-10/graphql.json', {
method: 'POST',
body: JSON.stringify({
query: `
mutation shippingPackageUpdate($id: ID!, $shippingPackage: CustomShippingPackageInput!) {
shippingPackageUpdate(id: $id, shippingPackage: $shippingPackage) {
userErrors {
field
message
}
}
}
`,
variables: {
"id": "gid://shopify/ShippingPackageV2/1071084921",
"shippingPackage": {
"name": "Envelope test",
"type": "ENVELOPE",
"weight": {
"value": 15,
"unit": "GRAMS"
},
"dimensions": {
"length": 2,
"width": 1,
"height": 5,
"unit": "INCHES"
}
}
},
}),
});
const { data } = await response.json();
console.log(data);
Response
{
"shippingPackageUpdate": {
"userErrors": []
}
}
Update a custom package and make it the default
Description
A saved shipping package is a box or envelope that a shop uses to calculate shipping rates at checkout and to buy shipping labels. Rename a custom package, set its empty weight and outside dimensions, and make it the default package, the one that checkout uses. Only custom packages can be updated this way: a carrier package's dimensions can't be changed.
Query
mutation shippingPackageUpdate($id: ID!, $shippingPackage: CustomShippingPackageInput!) {
shippingPackageUpdate(id: $id, shippingPackage: $shippingPackage) {
userErrors {
field
message
}
}
}
Variables
{
"id": "gid://shopify/ShippingPackageV2/1071084921",
"shippingPackage": {
"name": "Custom box test",
"default": true,
"weight": {
"value": 15,
"unit": "GRAMS"
},
"dimensions": {
"length": 2,
"width": 1,
"height": 1,
"unit": "CENTIMETERS"
}
}
}
cURL
curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation shippingPackageUpdate($id: ID!, $shippingPackage: CustomShippingPackageInput!) { shippingPackageUpdate(id: $id, shippingPackage: $shippingPackage) { userErrors { field message } } }",
"variables": {
"id": "gid://shopify/ShippingPackageV2/1071084921",
"shippingPackage": {
"name": "Custom box test",
"default": true,
"weight": {
"value": 15,
"unit": "GRAMS"
},
"dimensions": {
"length": 2,
"width": 1,
"height": 1,
"unit": "CENTIMETERS"
}
}
}
}'
React Router
import { authenticate } from "../shopify.server";
export const loader = async ({request}) => {
const { admin } = await authenticate.admin(request);
const response = await admin.graphql(
`#graphql
mutation shippingPackageUpdate($id: ID!, $shippingPackage: CustomShippingPackageInput!) {
shippingPackageUpdate(id: $id, shippingPackage: $shippingPackage) {
userErrors {
field
message
}
}
}`,
{
variables: {
"id": "gid://shopify/ShippingPackageV2/1071084921",
"shippingPackage": {
"name": "Custom box test",
"default": true,
"weight": {
"value": 15,
"unit": "GRAMS"
},
"dimensions": {
"length": 2,
"width": 1,
"height": 1,
"unit": "CENTIMETERS"
}
}
},
},
);
const json = await response.json();
return json.data;
}
Ruby
session = ShopifyAPI::Auth::Session.new(
shop: "your-development-store.myshopify.com",
access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
session: session
)
query = <<~QUERY
mutation shippingPackageUpdate($id: ID!, $shippingPackage: CustomShippingPackageInput!) {
shippingPackageUpdate(id: $id, shippingPackage: $shippingPackage) {
userErrors {
field
message
}
}
}
QUERY
variables = {
"id": "gid://shopify/ShippingPackageV2/1071084921",
"shippingPackage": {
"name": "Custom box test",
"default": true,
"weight": {
"value": 15,
"unit": "GRAMS"
},
"dimensions": {
"length": 2,
"width": 1,
"height": 1,
"unit": "CENTIMETERS"
}
}
}
response = client.query(query: query, variables: variables)
Node.js
const client = new shopify.clients.Graphql({session});
const data = await client.query({
data: {
"query": `mutation shippingPackageUpdate($id: ID!, $shippingPackage: CustomShippingPackageInput!) {
shippingPackageUpdate(id: $id, shippingPackage: $shippingPackage) {
userErrors {
field
message
}
}
}`,
"variables": {
"id": "gid://shopify/ShippingPackageV2/1071084921",
"shippingPackage": {
"name": "Custom box test",
"default": true,
"weight": {
"value": 15,
"unit": "GRAMS"
},
"dimensions": {
"length": 2,
"width": 1,
"height": 1,
"unit": "CENTIMETERS"
}
}
},
},
});
Shopify CLI
shopify app execute \
--query \
'mutation shippingPackageUpdate($id: ID!, $shippingPackage: CustomShippingPackageInput!) {
shippingPackageUpdate(id: $id, shippingPackage: $shippingPackage) {
userErrors {
field
message
}
}
}' \
--variables \
'{
"id": "gid://shopify/ShippingPackageV2/1071084921",
"shippingPackage": {
"name": "Custom box test",
"default": true,
"weight": {
"value": 15,
"unit": "GRAMS"
},
"dimensions": {
"length": 2,
"width": 1,
"height": 1,
"unit": "CENTIMETERS"
}
}
}'
Direct API Access
const response = await fetch('shopify:admin/api/2026-10/graphql.json', {
method: 'POST',
body: JSON.stringify({
query: `
mutation shippingPackageUpdate($id: ID!, $shippingPackage: CustomShippingPackageInput!) {
shippingPackageUpdate(id: $id, shippingPackage: $shippingPackage) {
userErrors {
field
message
}
}
}
`,
variables: {
"id": "gid://shopify/ShippingPackageV2/1071084921",
"shippingPackage": {
"name": "Custom box test",
"default": true,
"weight": {
"value": 15,
"unit": "GRAMS"
},
"dimensions": {
"length": 2,
"width": 1,
"height": 1,
"unit": "CENTIMETERS"
}
}
},
}),
});
const { data } = await response.json();
console.log(data);
Response
{
"shippingPackageUpdate": {
"userErrors": []
}
}