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.
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 returns403 Forbidden, and details.requiredScopes names the scopes that would open it. Add any one of them to the key under Edit access.
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
- Open Settings → Integrations & API and press Create key in the API keys section.
- Enter an API key label that names the integration, and pick when the key Expires. Choose No expiration for an integration that runs unattended.
- 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.
- Press Create API key and copy the key. The full value is shown once.
- Add the key to your integration as the
X-API-KEYrequest header.
- 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.
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 is2025-06.
Send the version in the X-API-Version header to pin a request to it:
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.
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.
Related articles
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.