Back to Break-even ROAS toolAPI

Break-even ROAS API

Calculate break-even ROAS, target-profit ROAS, and CPA guardrails from price, costs, fees, and refund reserve.

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. Successful and limit responses expose quota.remaining and rateLimit.remaining (plus the matching X-* headers). Minute limits use a UTC minute window and are counted per API key and tool; requests beyond the limit return 429 rate_limited, so wait for Retry-After before retrying.
X-Quota-Limit: 1000
X-Quota-Remaining: 997
X-RateLimit-Limit: 30
Safe Retries
When a request times out or your agent retries automatically, reuse the same Idempotency-Key. The same key and body reuse the result; a different body returns idempotency_conflict, while an active request returns idempotency_in_progress.
Idempotency-Key: order-sync-2026-06-14-001
Grant the smallest scope
Choose only the tool scope each API key needs, such as tools:gtin:generate. A scope limits tools; it does not increase the owner membership tier, quota, or rate limit.
Scope: tools:gtin:generate
Keep the API key secret
The full API key is shown only once. Store it in an environment variable or secret manager; never put it in code, URLs, logs, screenshots, or chat. Delete and recreate it if you suspect exposure.
ECOMWITH_API_KEY=ecw_live_...

Errors And Recovery

Error responses use error.code and error.message. Handle the status and code first, then decide whether to wait or retry the same business request with its original Idempotency-Key.

400invalid_request

Fix the JSON body before sending again; do not repeat an unchanged request.

401authentication_required / invalid_api_key

Check Authorization: Bearer or X-API-Key; never put the full key in error logs.

403membership_required / insufficient_scope

Check the current plan and the key scope; a scope cannot increase membership quota.

409idempotency_conflict / idempotency_in_progress

Keep one key for the same business request; stop on conflict, or wait and retry an active request with the same key.

413payload_too_large

Reduce the request body to the current plan payload limit before sending again.

429quota_exceeded / rate_limited / concurrency_limited

Read X-Quota-*, X-RateLimit-*, and Retry-After; stop at zero quota and wait for rate or concurrency limits.

Error response shape

{"object":"tool_api.error","error":{"code":"invalid_request","message":"Request body must be a JSON object."}}

Current Plan Limits

Limits are calculated from the current membership tier of the API key owner. Minute limits are counted separately for each API key and tool; requests beyond the limit return 429 rate_limited. Send requests sequentially and treat quota and rateLimit in each response as the source of truth.

Basic

Not included in API access today
Daily quota
Unavailable
Per request
Unavailable
Per minute
Unavailable
How to use it
If the API returns membership_required, stop and check the account plan.

Pro

Included
Daily quota
1,000 calculations
Per request
1 scenario
Per minute
60 requests
How to use it
One request calculates one product or scenario and does not use a quantity field. Use it to keep ad sheets, product sheets, or internal agents on the same profit formula.

Max

Included
Daily quota
10,000 calculations
Per request
1 scenario
Per minute
200 requests
How to use it
One request calculates one product or scenario and does not use a quantity field. Use it to keep ad sheets, product sheets, or internal agents on the same profit formula.

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 Break-even ROAS API, and never print the full API key.

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

Request:
- Endpoint: POST https://ecomwith.com/api/v1/tools/break-even-roas/calculate
- Body example: {"price":49,"productCost":14,"shippingCost":6,"paymentFeeRate":4,"refundRate":5,"targetProfit":8}
- One request calculates one product or scenario and consumes 1 calculation unit.

Current limits:
- Pro: 1,000 calculations per day, up to 60 requests per minute.
- Max: 10,000 calculations per day, up to 200 requests per minute.

Rules:
- Send requests sequentially. Do not call the same tool concurrently.
- Use one stable Idempotency-Key per product or scenario, for example break-even-sku-123.
- Handle concurrency_limited, rate_limited, quota_exceeded, and idempotency_conflict by stopping or retrying according to the code.

On success, return result.breakEvenRoas, result.targetProfitRoas, result.maxCpa, result.targetCpa, quota.remaining, and rateLimit.remaining.

Example Requests

curl -X POST https://ecomwith.com/api/v1/tools/break-even-roas/calculate \
  -H "Authorization: Bearer $ECOMWITH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: break-even-sku-001" \
  -d '{"price":49,"productCost":14,"shippingCost":6,"paymentFeeRate":4,"refundRate":5,"targetProfit":8}'