GTIN API

Generate GTIN-14 numbers in batches. Quota is counted by generated numbers.

Authentication

Create an API key from settings. The full secret is shown once, so copy it into your agent or secret manager. Later views only show a masked key.

Authorization: Bearer ecw_live_...
X-API-Key: ecw_live_...

Quota And Rate Limits

API usage is tracked separately. Responses include quota and rate-limit headers so your agent can decide whether to continue.

X-Quota-Limit: 1000
X-Quota-Remaining: 997
X-RateLimit-Limit: 30

Safe Retries

If a request times out or your agent retries automatically, send the same Idempotency-Key. The same request key and body reuse the result without duplicate generation or quota usage.

Idempotency-Key: order-sync-2026-06-14-001

Current Plan Limits

Limits are calculated from the current membership tier of the API key owner. Send requests sequentially; the quota and rateLimit fields in each response are the source of truth for your agent.

Plan	API access	Daily quota	Per request	Per minute	How to use it
Basic	Not included in API access today	Unavailable	Unavailable	Unavailable	If the API returns membership_required, stop and check the account plan.
Pro	Included	1,000 GTINs	Up to 100 GTINs	30 requests	quantity is the number of GTINs to generate. quantity=10 consumes 10 GTIN units. Stop or split the request when quota.remaining is lower than quantity.
Max	Included	10,000 GTINs	Up to 500 GTINs	120 requests	quantity is the number of GTINs to generate. quantity=10 consumes 10 GTIN units. Stop or split the request when quota.remaining is lower than quantity.

Send Requests Sequentially

For the same API key and tool, Ecomwith handles one request at a time. If the API returns 429 concurrency_limited, wait for the previous request to finish and retry with the same Idempotency-Key.

Copy This To Your Agent

Give this instruction to your automation agent so it knows how to authenticate, request, handle quota, rate limits, and safe retries.

You are my automation agent. Use the Ecomwith Tool API to call the GTIN API, and never print the full API key in logs, chat, or error messages.

Authentication:
- Read the secret from the ECOMWITH_API_KEY environment variable.
- Send Authorization: Bearer <ECOMWITH_API_KEY>.

Request:
- Endpoint: POST https://ecomwith.com/api/v1/tools/gtin/generate
- Headers: Content-Type: application/json
- Body example: {"quantity": 10}
- quantity is the number of GTINs to generate. quantity=10 consumes 10 GTIN units.

Current limits:
- Pro: 1,000 GTINs per day, up to 100 GTINs per request, up to 30 requests per minute.
- Max: 10,000 GTINs per day, up to 500 GTINs per request, up to 120 requests per minute.
- Basic does not include API access today. If the API returns membership_required, stop and ask me to check the plan.

Quota and rate-limit handling:
- Read quota.remaining and rateLimit.remaining from every response.
- If quota.remaining is lower than the next quantity, stop or split the request.
- Do not call the same tool concurrently. Wait for the previous request to finish before sending the next one.
- If the API returns 429 concurrency_limited, wait for the previous request to finish and retry with the same Idempotency-Key.
- If the API returns 429 rate_limited, wait before retrying. If it returns 429 quota_exceeded, stop and report that quota is exhausted.

Safe retries:
- Generate one stable Idempotency-Key for each business task, for example gtin-order-123-batch-1.
- On a network timeout or 5xx response, retry with the same Idempotency-Key. Do not switch to a new key.
- Do not automatically retry 400, 401, or 403 responses.
- If the API returns 409 idempotency_conflict, the same key was used with a different request body. Stop and ask me to confirm.

    On success, return the gtins list, quantity, quota.remaining, and rateLimit.remaining.

Example Requests

curl -X POST https://ecomwith.com/api/v1/tools/gtin/generate \
  -H "Authorization: Bearer $ECOMWITH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: gtin-batch-001" \
  -d '{"quantity": 10}'