Skip to main content
DraftSprite
Start free beta

Technical documentation

How DraftSprite uses the Etsy API

Written for Etsy's review team and for any seller who wants to know exactly what this tool can and cannot reach in their shop. Every statement here describes the code as deployed.

Last updated 22 August 2026

What DraftSprite does today

A seller uploads artwork they own. DraftSprite prepares A-size artwork, realistic room-scene mock-ups, one listing video and proposed listing copy from that artwork and the seller's own settings. The seller reviews and edits every part before approval.

Etsy access is restricted server-side during Personal App development. Only configured developer test accounts can create an unpublished draft through the API. Other accounts cannot authorise the integration or store Etsy credentials while wider Commercial Access remains disabled.

What the approved Personal App integration adds

For the initial Commercial Access seller rollout, one capability: sending a listing the seller has already reviewed to their own authenticated shop as an unpublished draft.

  1. The seller completes and reviews the listing in DraftSprite.
  2. They explicitly choose “Create Etsy draft”.
  3. Etsy handles authorisation through OAuth 2.0 with PKCE.
  4. DraftSprite reads only that shop's own sections and delivery profiles, which are required fields when creating a listing.
  5. It creates one new unpublished draft from the reviewed content.
  6. It uploads the images, or for a digital product the seller's own files, selected for that draft.
  7. The seller reviews the draft in Etsy and decides whether to publish it.

DraftSprite does not publish a seller's listing

Seller listings are created through createDraftListing with no state field, so Etsy creates an unpublished draft. No seller-facing code path sends state: "active". Publishing a draft is only ever done by the seller, in Etsy's own interface.

During Personal Access testing, the configured developer account can edit, change images and renew listings in its own allowlisted shop. When DraftSprite moves to Commercial Access, those routes pause by default and remain unavailable to commercial customers unless Etsy separately approves that functionality and the corresponding owner-tool rollout switch is deliberately enabled.

Permissions requested

  • shops_r — identify the authorised shop and read its own sections and delivery profiles.
  • listings_r — load listings chosen by the configured Personal Access shop owner for editing, image changes or renewal.
  • listings_w — create a new unpublished draft, attach selected media or digital files, and during Personal Access owner testing apply explicitly approved changes to the connected test shop's selected listings.

The restricted Personal Access owner connection requests listings_r. When Commercial Access is enabled, new seller connections omit that scope unless Etsy separately approves existing-listing functionality and the corresponding rollout switch is deliberately enabled.

DraftSprite does not request listings_d, transactions_r, or any order, payment, buyer, address, review, favourite or billing scope. It holds no permission to delete a listing.

Personal testing and Commercial Access rollout

The codebase contains an owner-only existing-listing tool, a Canva Content Publisher workflow and a multi-draft submission route. Owner tools and Canva remain available to the configured developer account during Personal Access testing, while access to the Etsy API remains restricted to that account and its allowlisted shops.

The existing-listing tool is controlled four ways:

  • middleware rejects every /admin request from a non-administrator before the page renders;
  • each underlying API route independently re-checks administrator status server-side;
  • when ETSY_COMMERCIAL_ACCESS is enabled, each route pauses unless Etsy has separately approved the wider functionality and ETSY_OWNER_LISTING_TOOLS_APPROVED is also deliberately enabled;
  • while Commercial Access stays disabled, only configured developer accounts can authorise an Etsy connection at all.

Canva follows the same transition rule. It remains available to the configured Personal Access developer account, then pauses when Commercial Access is enabled and remains unavailable to commercial customers unless Etsy separately approves that workflow and ETSY_CANVA_PUBLISHING_APPROVED is deliberately enabled.

Bulk generation and seller-controlled bulk creation of unpublished Etsy drafts are part of DraftSprite's approved Application Purpose. Every item still requires seller review, and nothing is automatically published.

Prohibited functionality

The following prohibited behaviours are not available:

  • competitor search and cross-seller price comparison;
  • shop sales, favourites, review and listing-performance analytics;
  • reading any shop other than the one the account has authorised;
  • duplicate-title checks against other sellers' listings;
  • importing or cloning an existing Etsy listing into a new draft;
  • the browser extension and all Etsy page automation;
  • using Etsy API content as AI input: the existing-listing editor requires an independently uploaded original artwork file, batch editing no longer imports photo 1 or derives prompts from Etsy titles, and Etsy-hosted images are blocked by the URL importer.

Access during Personal App development

Authorisation is restricted server-side to configured developer accounts and, once configured, specific numeric shop IDs. Other accounts are rejected and no credentials are stored for them. Wider access stays disabled unless Etsy later approves Commercial Access and it is deliberately enabled.

Physical listings include Etsy's readiness_state_id processing-profile field, which Etsy's Open API now requires for every physical listing. DraftSprite resolves it automatically from the connected shop's own existing processing profiles, or asks the seller to set one up if none exists yet. Digital listings do not use processing profiles.

Security and data handling

  • OAuth 2.0 with PKCE and a short-lived, single-use state record.
  • Sellers never create, enter or share Etsy API credentials.
  • Access and refresh tokens are encrypted with AES-256-GCM before storage.
  • Token writes fail closed: if the encryption key is missing or malformed, the credential is refused rather than stored in plain text.
  • Tokens stay server-side and are never sent to the browser or to any third party.
  • Etsy requests are rate-limited with backoff on 429 responses.
  • Etsy data is scoped to the account it belongs to and is never shared between accounts.
  • Etsy data is not supplied to an AI model and is not used for model training.
  • Existing listing data is fetched live rather than retained as a DraftSprite catalogue. Other displayed Etsy content is refreshed within 24 hours; stale sections, shop names and icons are withheld while a background refresh runs and remain withheld if it fails.

Fees

DraftSprite allowances apply to its value-added generation work, including mock-ups, video and listing copy. Sending an already-generated, seller-reviewed pack through an approved Etsy connection does not consume another allowance, and DraftSprite does not charge separately for Etsy's own listing-management operation.

Independence

DraftSprite is an independent product operated by Ava Lily Studio in the United Kingdom. The term ‘Etsy’ is a trademark of Etsy, Inc. This Application uses Etsy's API, but is not endorsed or certified by Etsy.