Skip to main content
Create an API key for each integration, script or headless storefront, and give it only the access that integration needs. Send the key in the X-API-KEY header. It authenticates against the same API the admin uses.
The TWICE Admin API is in alpha. Endpoints and schemas can change without notice. Pin an API version (see API versions) and check the reference before you upgrade an integration.

How it works

A key has either Full access or Limited access:
  • Full access reaches every endpoint a key can reach, including endpoints added later.
  • Limited access reaches only the areas you set, each at Read or Write. Write includes read.
An area covers everything under it, including anything added to it later. Catalog at Read reads listings, collections, price tables and discounts. Each area you set is stored on the key as a scope: the area’s path and its level, such as orders.details.read or inventory.stock_items.write. Every endpoint in the API reference names the scopes that open it, and any one of them is enough. A key reads what it is scoped for, along with whatever that data embeds. A key that reads orders receives the listing, customer and location details an order carries, without holding those scopes.
Keys created before scoped access shipped keep Full access until you change them. Narrow each one under Edit access to the areas its integration uses.

Areas a key can be given

Order details and Payments are separate on purpose. A key with Order details reads and creates orders without seeing payment transactions, and a key with Payments takes payments without reading or creating orders. The areas under Account settings: Give Payment accounts only to an integration you trust to decide where your money settles. Any Account or Account settings area also reads your account profile: currency, timezone and languages.

Areas no key can reach

These stay with people signed in to the admin. No key reaches them, Full access included:
  • API keys and connectors under Settings → Integrations & API
  • Users and roles
  • Sign-in security
  • Opening and closing your account
  • Your subscription plan and billing
  • A signed-in person’s own profile and saved table views

Read a refused request

A request the key is not scoped for returns 403 Forbidden, and details.requiredScopes names the scopes that would open it. Add any one of them to the key under Edit access.
An empty requiredScopes list means no key can make that call. A request body that changes fields belonging to another area returns details.deniedFields instead: each entry names its fields and their requiredScopes, and the key needs one scope from every entry. A change to a key’s access usually applies from the integration’s next request, and always within five minutes.

Usage

  1. Open Settings → Integrations & API and press Create key in the API keys section.
  2. Enter an API key label that names the integration, and pick when the key Expires. Choose No expiration for an integration that runs unattended.
  3. Under Access, pick Limited access and set each area the integration uses to Read or Write. Pick Full access only for an integration that needs every area.
  4. Press Create API key and copy the key. The full value is shown once.
  5. Add the key to your integration as the X-API-KEY request header.
Store every key as a secret and never commit it to source control. A key with Write on orders, payments or settings can change them across your account.
Manage a key from the menu on its row:
  • Edit access changes the areas the key reaches.
  • Duplicate creates a new key with the same label and access and a new secret. The original keeps working until it expires or you delete it. Use it to replace a leaked or expiring key: switch the integration to the copy, then delete the original.
  • Delete opens the Delete API key dialog. Every integration authenticating with that key stops working the moment you confirm, and deleting cannot be undone.
A key can expire after 1 or 6 hours, or after 1, 3, 7, 14, 30, 60, 90, 180 or 365 days. Every response to an expiring key carries its expiry in the X-Api-Key-Expires-At header, and the Expires column highlights a key in its last 14 days. An expired key returns 401 with the message “This API key has expired”. A lifetime cannot be extended, so replace the key with Duplicate. Send the key on every request to https://server.twicecommerce.com. Merchant-facing endpoints, the TWICE Admin API, live under /v1/admin/. For example, list your catalog items with a key that holds catalog.listings.read:

API versions

The API is versioned by date. The current version is 2025-06. Send the version in the X-API-Version header to pin a request to it:
A request that sends no version header, or a version the API does not recognise, targets the latest version. Pin the header on an integration you do not want moving under you when a new version ships. Webhooks are pinned separately: each webhook keeps the version that was latest when you created it, so a new API version never changes a payload you already receive. See Webhooks.
Integrations written against the older https://server.twicecommerce.com/internal/… paths keep working, because those URLs resolve onto /v1/admin/. Write new integrations against /v1/admin/.

Rate limits

The API limits requests in three layers:
  • Per IP: pre-authentication protection. Each client IP has a per-minute request budget. Requests with missing or bot-like user agents consume more of the budget per call.
  • Per account: all authenticated traffic on your account, admin dashboard and API keys combined, shares a per-minute limit that scales with your plan.
  • Per API key: each key has a sustained requests-per-second rate, a short-term burst allowance, and a monthly request cap. All three scale with your plan; the monthly cap is the API call allowance that pools across all your locations.
Responses carry rate limit headers: When a request exceeds a limit, the API returns 429 Too Many Requests. Wait for Retry-After seconds before retrying. Crossing the monthly cap does not always return 429. Accounts with overage enabled get the request served and billed as overage instead; accounts without it get 429 on every call past the cap. A request the burst limit rejects never reaches the monthly cap, so it is not counted against it. See pricing for the allowances on each plan.

API reference

Browse every endpoint and the scopes it takes.

Webhooks

Receive events when data changes.

Bulk creation

Create many records in one call instead of a loop.

Integrations settings

Manage keys and connected systems.