DoctorX logoDoctorX Get an API key

Etsy

Etsy shipping, return and processing profiles, shop sections, personalization templates and carriers.

Every profile grouped by kind, plus publish readiness. publishReady is false until shipping, return AND processing each have a default, and missingForPublish names which are absent. Read this instead of inferring readiness from a failed publish.

Parameters

NameInTypeDescription
shopIdrequired
querystring

DoctorX resource id: a UUID in canonical 8-4-4-4-12 hex form. Version and variant bits are not constrained.

pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Responses

200EtsyConfigResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X GET 'https://api.doctorx.vn/api/public/v1/etsy/config?shopId=string' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"

Mirrors the shipping profiles, return policies, processing profiles and sections the seller has on Etsy into DoctorX. Idempotent by the id each profile has on the marketplace connection, so it is safe to repeat, and it never overwrites a default you chose. Each source is best-effort: a partial failure still returns the rest and names what failed in syncSummary.failed.

Request body

shopIdstringrequired

DoctorX resource id: a UUID in canonical 8-4-4-4-12 hex form. Version and variant bits are not constrained.

pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Responses

200EtsyConfigResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X POST 'https://api.doctorx.vn/api/public/v1/etsy/sync' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "shopId": "string"
}'

The carriers valid for a shipping profile destination in a given ORIGIN country, each with its mail classes. Per country because Etsy validates a profile against its origin. A destination names EITHER a mail class OR a delivery-day window, never both.

Parameters

NameInTypeDescription
shopIdrequired
querystring

DoctorX resource id: a UUID in canonical 8-4-4-4-12 hex form. Version and variant bits are not constrained.

pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

country
querystring

ISO 3166-1 alpha-2. Carriers are per country because Etsy validates a shipping profile against the ORIGIN country.

min length 2 · max length 2 · default "US"

Responses

200EtsyShippingCarrierListResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X GET 'https://api.doctorx.vn/api/public/v1/etsy/carriers?shopId=string' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
GET/etsy/policies

Flat list across all four kinds for one shop. data carries the profile as the marketplace connection returns it, including a shipping profile's destinations and per-region costs. Filter with ?type=shipping|return|processing|section.

Parameters

NameInTypeDescription
shopIdrequired
querystring

DoctorX resource id: a UUID in canonical 8-4-4-4-12 hex form. Version and variant bits are not constrained.

pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

type
querystring

Restrict to one kind. Omit for all four.

One of: "shipping", "return", "processing", "section"

Responses

200EtsyProfileListResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X GET 'https://api.doctorx.vn/api/public/v1/etsy/policies?shopId=string' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
GET/etsy/policies/{id}

Same shape as a row in the list, but data is fetched LIVE from the marketplace rather than served from the mirror. Use it to settle whether a single profile has changed on Etsy without re-syncing the whole shop; the list is mirror-backed and can lag an edit a seller made on Etsy directly. Works for all four kinds. Degrades to the mirrored payload rather than erroring if the live read fails, and serves the mirrored payload with no live read while the shop is paused.

Parameters

NameInTypeDescription
idrequired
pathstring
shopIdrequired
querystring

DoctorX resource id: a UUID in canonical 8-4-4-4-12 hex form. Version and variant bits are not constrained.

pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Responses

200EtsyProfileResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X GET 'https://api.doctorx.vn/api/public/v1/etsy/policies/string?shopId=string' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
DELETE/etsy/policies/{id}

Removed from Etsy and from DoctorX. Shop SECTIONS cannot be deleted through DoctorX, so this answers channel_not_supported for one rather than a remote 404 you have to interpret. Deleting the default of a required kind leaves the shop unable to publish until another is made default.

Parameters

NameInTypeDescription
idrequired
pathstring
shopIdrequired
querystring

DoctorX resource id: a UUID in canonical 8-4-4-4-12 hex form. Version and variant bits are not constrained.

pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Responses

200EtsyDeleteResultResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X DELETE 'https://api.doctorx.vn/api/public/v1/etsy/policies/string?shopId=string' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
POST/etsy/policies/shipping

Created on Etsy and mirrored locally. Note the time unit enum here is (business_days, weeks), which differs from the processing profile's (days, weeks): sending "days" is rejected by Etsy. Each destination must name either a mail class or a delivery-day window, checked here rather than left to Etsy.

Request body

shopIdstringrequired

DoctorX resource id: a UUID in canonical 8-4-4-4-12 hex form. Version and variant bits are not constrained.

pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

titlestring

min length 1 · max length 200

originCountryIsostringrequired

ISO 3166-1 alpha-2, e.g. US.

min length 2 · max length 2

originPostalCodestringrequired

Etsy validates this against the origin country.

min length 1 · max length 20

minProcessingDaysintegerrequired

min 0 · max 90

maxProcessingDaysintegerrequired

min 0 · max 90

processingDaysUnitstringrequired

The SHIPPING profile's unit enum. Note it differs from the PROCESSING profile's, which is (days, weeks): sending days here is rejected by Etsy.

One of: "business_days", "weeks"

At least one destination; Etsy rejects an empty profile.

min items 1

Responses

201EtsyProfileResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X POST 'https://api.doctorx.vn/api/public/v1/etsy/policies/shipping' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "shopId": "string",
  "originCountryIso": "string",
  "originPostalCode": "string",
  "minProcessingDays": 0,
  "maxProcessingDays": 0,
  "processingDaysUnit": "business_days",
  "destinations": [
    {
      "shippingCarrierId": -9007199254740991,
      "originCountryIso": "string",
      "destinationCountryIso": "string",
      "primaryCost": 0,
      "secondaryCost": 0,
      "isDomestic": false,
      "mailClass": "string",
      "minDeliveryDays": 0,
      "maxDeliveryDays": 0
    }
  ]
}'
PUT/etsy/policies/shipping/{id}

Changes apply to every listing already using the profile, because the listing references it rather than copying it.

Parameters

NameInTypeDescription
idrequired
pathstring

Request body

shopIdstringrequired

DoctorX resource id: a UUID in canonical 8-4-4-4-12 hex form. Version and variant bits are not constrained.

pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

titlestring

min length 1 · max length 200

originCountryIsostringrequired

ISO 3166-1 alpha-2, e.g. US.

min length 2 · max length 2

originPostalCodestringrequired

Etsy validates this against the origin country.

min length 1 · max length 20

minProcessingDaysintegerrequired

min 0 · max 90

maxProcessingDaysintegerrequired

min 0 · max 90

processingDaysUnitstringrequired

The SHIPPING profile's unit enum. Note it differs from the PROCESSING profile's, which is (days, weeks): sending days here is rejected by Etsy.

One of: "business_days", "weeks"

At least one destination; Etsy rejects an empty profile.

min items 1

Responses

200EtsyProfileResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X PUT 'https://api.doctorx.vn/api/public/v1/etsy/policies/shipping/string' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "shopId": "string",
  "originCountryIso": "string",
  "originPostalCode": "string",
  "minProcessingDays": 0,
  "maxProcessingDays": 0,
  "processingDaysUnit": "business_days",
  "destinations": [
    {
      "shippingCarrierId": -9007199254740991,
      "originCountryIso": "string",
      "destinationCountryIso": "string",
      "primaryCost": 0,
      "secondaryCost": 0,
      "isDomestic": false,
      "mailClass": "string",
      "minDeliveryDays": 0,
      "maxDeliveryDays": 0
    }
  ]
}'
POST/etsy/policies/return

returnDeadline is required once returns or exchanges are accepted, checked here so the failure names the field.

Request body

shopIdstringrequired

DoctorX resource id: a UUID in canonical 8-4-4-4-12 hex form. Version and variant bits are not constrained.

pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

namestring

min length 1 · max length 200

acceptsReturnsboolean
acceptsExchangesboolean
returnDeadlineinteger

Days the buyer has to return. Ignored when acceptsReturns and acceptsExchanges are both false.

min 0 · max 90

Responses

201EtsyProfileResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X POST 'https://api.doctorx.vn/api/public/v1/etsy/policies/return' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "shopId": "string"
}'
PUT/etsy/policies/return/{id}

Parameters

NameInTypeDescription
idrequired
pathstring

Request body

shopIdstringrequired

DoctorX resource id: a UUID in canonical 8-4-4-4-12 hex form. Version and variant bits are not constrained.

pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

namestring

min length 1 · max length 200

acceptsReturnsboolean
acceptsExchangesboolean
returnDeadlineinteger

Days the buyer has to return. Ignored when acceptsReturns and acceptsExchanges are both false.

min 0 · max 90

Responses

200EtsyProfileResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X PUT 'https://api.doctorx.vn/api/public/v1/etsy/policies/return/string' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "shopId": "string"
}'
POST/etsy/policies/processing

The time unit enum here is (days, weeks), which differs from the shipping profile's (business_days, weeks). readinessState is not unique within a shop, so use the returned externalId as the key, never the name.

Request body

shopIdstringrequired

DoctorX resource id: a UUID in canonical 8-4-4-4-12 hex form. Version and variant bits are not constrained.

pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

readinessStatestringrequired

Etsy accepts these two only. Not unique within a shop, so the returned externalId (readiness_state_id) is the key, never this.

One of: "ready_to_ship", "made_to_order"

minProcessingTimeintegerrequired

min 1 · max 10

maxProcessingTimeintegerrequired

min 1 · max 10

processingTimeUnitstringrequired

The PROCESSING profile's unit enum. Differs from the SHIPPING profile's, which is (business_days, weeks).

One of: "days", "weeks"

isDefaultboolean

Responses

201EtsyProfileResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X POST 'https://api.doctorx.vn/api/public/v1/etsy/policies/processing' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "shopId": "string",
  "readinessState": "ready_to_ship",
  "minProcessingTime": 1,
  "maxProcessingTime": 1,
  "processingTimeUnit": "days"
}'
PUT/etsy/policies/processing/{id}

Prefer this over delete-and-recreate: a recreate mints a NEW id, and every template still pointing at the old one silently stops resolving.

Parameters

NameInTypeDescription
idrequired
pathstring

Request body

shopIdstringrequired

DoctorX resource id: a UUID in canonical 8-4-4-4-12 hex form. Version and variant bits are not constrained.

pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

readinessStatestringrequired

Etsy accepts these two only. Not unique within a shop, so the returned externalId (readiness_state_id) is the key, never this.

One of: "ready_to_ship", "made_to_order"

minProcessingTimeintegerrequired

min 1 · max 10

maxProcessingTimeintegerrequired

min 1 · max 10

processingTimeUnitstringrequired

The PROCESSING profile's unit enum. Differs from the SHIPPING profile's, which is (business_days, weeks).

One of: "days", "weeks"

isDefaultboolean

Responses

200EtsyProfileResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X PUT 'https://api.doctorx.vn/api/public/v1/etsy/policies/processing/string' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "shopId": "string",
  "readinessState": "ready_to_ship",
  "minProcessingTime": 1,
  "maxProcessingTime": 1,
  "processingTimeUnit": "days"
}'
POST/etsy/policies/section

Optional organisation, never a publish precondition. Never becomes a default automatically, so a listing is not filed under an arbitrary section.

Request body

shopIdstringrequired

DoctorX resource id: a UUID in canonical 8-4-4-4-12 hex form. Version and variant bits are not constrained.

pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

titlestringrequired

Etsy caps a shop section name at 24 characters: 25 answers "Your shop section name is too long." Refused here so the limit is visible in the spec rather than discovered from a remote 400.

min length 1 · max length 24

Responses

201EtsyProfileResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X POST 'https://api.doctorx.vn/api/public/v1/etsy/policies/section' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "shopId": "string",
  "title": "string"
}'
PUT/etsy/policies/section/{id}

Parameters

NameInTypeDescription
idrequired
pathstring

Request body

shopIdstringrequired

DoctorX resource id: a UUID in canonical 8-4-4-4-12 hex form. Version and variant bits are not constrained.

pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

titlestringrequired

Etsy caps a shop section name at 24 characters: 25 answers "Your shop section name is too long." Refused here so the limit is visible in the spec rather than discovered from a remote 400.

min length 1 · max length 24

Responses

200EtsyProfileResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X PUT 'https://api.doctorx.vn/api/public/v1/etsy/policies/section/string' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "shopId": "string",
  "title": "string"
}'
PATCH/etsy/policies/{id}/default

At most one default per (shop, kind), enforced atomically. This is the most consequential edit in the domain: it decides which profile every future publish binds, and it is what flips a shop between publish-ready and not.

Parameters

NameInTypeDescription
idrequired
pathstring

Request body

shopIdstringrequired

DoctorX resource id: a UUID in canonical 8-4-4-4-12 hex form. Version and variant bits are not constrained.

pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Responses

200EtsyProfileResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X PATCH 'https://api.doctorx.vn/api/public/v1/etsy/policies/string/default' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "shopId": "string"
}'
GET/etsy/personalizations

The templates your workspace owns. Takes no shopId: templates are workspace-scoped rather than shop-scoped, and only your own are returned.

Responses

200EtsyPersonalizationListResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X GET 'https://api.doctorx.vn/api/public/v1/etsy/personalizations' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
POST/etsy/personalizations

A dropdown template REQUIRES options and rejects charCountMax; a text_input one is the reverse. Both rules are enforced here rather than left to Etsy.

Request body

namestringrequired

min length 1 · max length 200

instructionsstring

Prompt shown to the buyer. Falls back to the name.

max length 2000

charCountMaxinteger

Free-text length limit. Ignored for a dropdown.

min 1 · max 1024

isRequiredboolean
isActiveboolean
questionTypestring

Defaults to text_input. A dropdown REQUIRES options and rejects charCountMax; text_input is the reverse.

One of: "text_input", "dropdown"

optionsstring[]

Dropdown choices, 1 to 30 of them, each at most 20 characters.

min items 1 · max items 30

Responses

201EtsyPersonalizationResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X POST 'https://api.doctorx.vn/api/public/v1/etsy/personalizations' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string"
}'
PUT/etsy/personalizations/{id}

Parameters

NameInTypeDescription
idrequired
pathstring

Request body

namestringrequired

min length 1 · max length 200

instructionsstring

Prompt shown to the buyer. Falls back to the name.

max length 2000

charCountMaxinteger

Free-text length limit. Ignored for a dropdown.

min 1 · max 1024

isRequiredboolean
isActiveboolean
questionTypestring

Defaults to text_input. A dropdown REQUIRES options and rejects charCountMax; text_input is the reverse.

One of: "text_input", "dropdown"

optionsstring[]

Dropdown choices, 1 to 30 of them, each at most 20 characters.

min items 1 · max items 30

Responses

200EtsyPersonalizationResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X PUT 'https://api.doctorx.vn/api/public/v1/etsy/personalizations/string' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string"
}'
DELETE/etsy/personalizations/{id}

Listings already carrying the template are unaffected.

Parameters

NameInTypeDescription
idrequired
pathstring

Responses

200EtsyDeleteResultResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X DELETE 'https://api.doctorx.vn/api/public/v1/etsy/personalizations/string' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"