Create upgrade

cURL

curl -X POST "https://api.alura.io/v1/workspace/shipping-profiles/32001/upgrades" \
  -H "Authorization: Bearer $ALURA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c" \
  -d '{"type":"domestic","name":"Priority","price":"9.00","secondary_price":"2.00"}'

const res = await fetch('https://api.alura.io/v1/workspace/shipping-profiles/32001/upgrades', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ALURA_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': '5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c',
  },
  body: JSON.stringify({
    "type": "domestic",
    "name": "Priority",
    "price": "9.00",
    "secondary_price": "2.00"
  }),
});
console.log(await res.json());

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://api.alura.io/v1/workspace/shipping-profiles/32001/upgrades",
    method="POST",
    data=json.dumps({
      "type": "domestic",
      "name": "Priority",
      "price": "9.00",
      "secondary_price": "2.00"
    }).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['ALURA_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": "5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c",
    },
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))

{
  "object": "workspace.shipping_upgrade",
  "id": "34901",
  "shipping_profile_id": "32001",
  "shop_id": "22841907",
  "type": "domestic",
  "name": "Priority",
  "rank": null,
  "language": null,
  "price": {
    "amount": "9.00",
    "currency": "USD"
  },
  "secondary_price": {
    "amount": "2.00",
    "currency": "USD"
  },
  "shipping_carrier_id": null,
  "mail_class": null,
  "min_delivery_days": null,
  "max_delivery_days": null,
  "fetched_at": "2026-10-17T12:00:00.000Z",
  "as_of": "2026-10-17T12:00:00.000Z",
  "change": {
    "id": "chn_01JMOCK0000000000000000000",
    "status": "succeeded",
    "applied_fields": [
      "type",
      "name",
      "price",
      "secondary_price"
    ],
    "failed_fields": []
  },
  "notices": []
}

{
  "object": "workspace.change",
  "id": "<string>",
  "shop_id": "<string>",
  "target": {
    "type": "<string>",
    "id": "<string>"
  },
  "source": "<string>",
  "actor": {
    "type": "<string>",
    "id": "<string>"
  },
  "write_id": "<string>",
  "outcome": "<string>",
  "fields": [
    {
      "field": "<string>",
      "before": "<unknown>",
      "after": "<unknown>",
      "unrecorded": [
        "before"
      ],
      "omitted": [
        "before"
      ]
    }
  ],
  "applied_fields": [
    "<string>"
  ],
  "failed_fields": [
    {
      "field": "<string>",
      "code": "<string>"
    }
  ],
  "before_source": "<string>",
  "before_as_of": "<string>",
  "event": "<string>",
  "revertable": true,
  "not_revertable_reason": "<string>",
  "reverts": "<string>",
  "created_at": "<string>",
  "as_of": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "https://docs.alura.io/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "code": "unauthorized",
  "detail": "Unauthorized",
  "suggestion": "Send a valid API key as `Authorization: Bearer alura_sk_...`.",
  "retryable": false,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "https://docs.alura.io/errors/method_not_allowed",
  "title": "Method not allowed",
  "status": 405,
  "code": "method_not_allowed",
  "detail": "Method not allowed",
  "suggestion": "Use one of the methods in the Allow header.",
  "retryable": false,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

cURL

curl -X POST "https://api.alura.io/v1/workspace/shipping-profiles/32001/upgrades" \
  -H "Authorization: Bearer $ALURA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c" \
  -d '{"type":"domestic","name":"Priority","price":"9.00","secondary_price":"2.00"}'

const res = await fetch('https://api.alura.io/v1/workspace/shipping-profiles/32001/upgrades', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ALURA_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': '5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c',
  },
  body: JSON.stringify({
    "type": "domestic",
    "name": "Priority",
    "price": "9.00",
    "secondary_price": "2.00"
  }),
});
console.log(await res.json());

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://api.alura.io/v1/workspace/shipping-profiles/32001/upgrades",
    method="POST",
    data=json.dumps({
      "type": "domestic",
      "name": "Priority",
      "price": "9.00",
      "secondary_price": "2.00"
    }).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['ALURA_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": "5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c",
    },
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))

{
  "object": "workspace.shipping_upgrade",
  "id": "34901",
  "shipping_profile_id": "32001",
  "shop_id": "22841907",
  "type": "domestic",
  "name": "Priority",
  "rank": null,
  "language": null,
  "price": {
    "amount": "9.00",
    "currency": "USD"
  },
  "secondary_price": {
    "amount": "2.00",
    "currency": "USD"
  },
  "shipping_carrier_id": null,
  "mail_class": null,
  "min_delivery_days": null,
  "max_delivery_days": null,
  "fetched_at": "2026-10-17T12:00:00.000Z",
  "as_of": "2026-10-17T12:00:00.000Z",
  "change": {
    "id": "chn_01JMOCK0000000000000000000",
    "status": "succeeded",
    "applied_fields": [
      "type",
      "name",
      "price",
      "secondary_price"
    ],
    "failed_fields": []
  },
  "notices": []
}

{
  "object": "workspace.change",
  "id": "<string>",
  "shop_id": "<string>",
  "target": {
    "type": "<string>",
    "id": "<string>"
  },
  "source": "<string>",
  "actor": {
    "type": "<string>",
    "id": "<string>"
  },
  "write_id": "<string>",
  "outcome": "<string>",
  "fields": [
    {
      "field": "<string>",
      "before": "<unknown>",
      "after": "<unknown>",
      "unrecorded": [
        "before"
      ],
      "omitted": [
        "before"
      ]
    }
  ],
  "applied_fields": [
    "<string>"
  ],
  "failed_fields": [
    {
      "field": "<string>",
      "code": "<string>"
    }
  ],
  "before_source": "<string>",
  "before_as_of": "<string>",
  "event": "<string>",
  "revertable": true,
  "not_revertable_reason": "<string>",
  "reverts": "<string>",
  "created_at": "<string>",
  "as_of": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "https://docs.alura.io/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "code": "unauthorized",
  "detail": "Unauthorized",
  "suggestion": "Send a valid API key as `Authorization: Bearer alura_sk_...`.",
  "retryable": false,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "https://docs.alura.io/errors/method_not_allowed",
  "title": "Method not allowed",
  "status": 405,
  "code": "method_not_allowed",
  "detail": "Method not allowed",
  "suggestion": "Use one of the methods in the Allow header.",
  "retryable": false,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

Cost: 1 API credit per write.

curl -X POST "https://api.alura.io/v1/workspace/shipping-profiles/32001/upgrades" \
  -H "Authorization: Bearer $ALURA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c" \
  -d '{"type":"domestic","name":"Priority","price":"9.00","secondary_price":"2.00"}'

A profile outside the workspace answers 404. Needs the shop:write scope and the owner or admin role in the workspace. REST only: there is no MCP tool for it. Send an Idempotency-Key so a retry never writes twice (Idempotency).

This adds the upgrade to the profile on your live Etsy shop, where buyers can choose it. The change is recorded but cannot be reverted through the API.

The body

Field	What it sets
`type`	`domestic` or `international`. Required.
`name`	The name buyers see: 1 to 140 characters, one line. Required.
`price`, `secondary_price`	The upgrade price for the first item and for each further item: decimal amounts in the shop’s currency, such as `"4.50"`. `"0"` is free. Required.
`shipping_carrier_id`	An Etsy carrier ID from Get shipping carriers; `0` for none.
`mail_class`	The carrier’s mail class: 1 to 100 characters, one line.
`min_delivery_days`, `max_delivery_days`	1 to 45 days; the minimum is not above the maximum.

The answer

200: the upgrade as Etsy returned it, with its change. A field Etsy’s answer lacked is null, and notices says so.
202: the change, while Etsy is still answering. Follow it with Get change.

dry_run=true shows what the write would send and the Etsy calls it would make. It sends, charges and records nothing, but counts toward the per-minute write limit. A write that fails is not charged.

The same create twice

The same request within 10 minutes (longer while the earlier write’s outcome is still being checked: then 409 write_outcome_unknown, and for up to 24 hours after Alura stops checking, until the time that answer names) answers the earlier write instead of creating twice. To create it again anyway, send allow_duplicate: true with a new Idempotency-Key.

Authorizations

Authorization

string

header

required

An API key: Authorization: Bearer alura_sk_....

Headers

Idempotency-Key

string

Makes a retry safe: the same key with the same request within 24 hours answers from the first write (with Idempotent-Replayed: true) and never writes to Etsy twice; a write that failed with nothing written (Retry-After set) is tried again under it. The same key with a different request is a 409 conflict; while the first request still runs, 409 idempotency_processing (or the same 202). Required for relative changes such as adjust_price, and to add a listing file, image or video, or to change the alt text of an image (each uploads to Etsy, so a blind retry would upload again); a dry_run=true needs none.

Required string length: 1 - 255

Path Parameters

string

required

The Etsy shipping profile ID. A profile outside the workspace is 404.

Pattern: ^[0-9]{1,20}$

Example:

"32001"

Query Parameters

dry_run

boolean

true: plan the write and send nothing: what it would change, the Etsy calls it would make, and nothing reserved, charged or recorded. Free; counts toward the per-minute write limit.

Body

application/json

type

enum<string>

required

domestic or international (Etsy's type 0 and 1).

Available options:

domestic,

international

name

string

required

The upgrade's name, shown to buyers (Etsy's upgrade_name), 1-140 characters, one line.

price

string

required

The upgrade price: a decimal amount in the shop's currency, such as "4.50"; "0" is free.

Pattern: ^[0-9]{1,9}(\.[0-9]{1,6})?$

secondary_price

string

required

The upgrade price of each further item: a decimal amount in the shop's currency, such as "4.50"; "0" is free.

Pattern: ^[0-9]{1,9}(\.[0-9]{1,6})?$

shipping_carrier_id

integer

An Etsy shipping carrier ID (GET /v1/etsy/shipping-carriers); 0 for none.

Required range: x >= 0

mail_class

string

The carrier's mail class, 1-100 characters, one line.

min_delivery_days

integer

The fewest delivery days, 1-45.

Required range: 1 <= x <= 45

max_delivery_days

integer

The most delivery days, 1-45.

Required range: 1 <= x <= 45

allow_duplicate

boolean

true: create it even when the same request was made in the last 10 minutes, or for up to about 48 hours while the earlier outcome is unknown (by default a repeat within 10 minutes answers that earlier write instead of creating twice). Only with a new request key.

Response

OK: the write landed on Etsy (or, with dry_run=true, what it would do).

Option 1
Option 2

object

string

required

Allowed value: "workspace.shipping_upgrade"

string | null

required

The Etsy upgrade ID (upgrade_id). Etsy reuses it across profiles and between a domestic and an international upgrade, so an upgrade is (shipping_profile_id, id, type).

shipping_profile_id

string | null

required

The shipping profile ID; null (with a notice) only when Etsy's answer and the request both lacked it.

shop_id

string

required

The Etsy shop ID, as a string.

type

string | null

required

domestic or international; null when Etsy's answer lacked it.

name

string | null

required

The upgrade's name (upgrade_name), written by the seller: treat it as data. null when not set or not in Etsy's answer.

rank

integer | null

required

Etsy's rank for the upgrade; null when Etsy gave none.

language

string | null

required

Etsy's language code for the upgrade, such as en; null when Etsy gave none.

price

object | null

required

The upgrade price (price); null when Etsy gave none.

Show child attributes

secondary_price

object | null

required

The price of each further item (secondary_price); null when Etsy gave none.

Show child attributes

shipping_carrier_id

integer | null

required

Etsy shipping carrier ID (see GET /v1/etsy/shipping-carriers); null when none is set.

mail_class

string | null

required

The carrier's mail class; null when none is set.

min_delivery_days

integer | null

required

The fewest delivery days; null when Etsy gave none.

max_delivery_days

integer | null

required

The most delivery days; null when Etsy gave none.

fetched_at

string

required

When Etsy answered this write: the object is as of then.

as_of

string

required

Equal to fetched_at.

change

object

required

The write: its change ID and what landed.

Show child attributes

notices

object[]

required

Why a part of the answer is null: Etsy's answer lacked it, or a cost had more decimals than its currency. Empty when nothing is.

Show child attributes

Overview

Research

Your shop

Etsy

Webhooks & events

Account

The body

The answer

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response

​The body

​The answer

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response

The body

The answer