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. 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 calculations	1 scenario	30 requests	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	10,000 calculations	1 scenario	120 requests	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 30 requests per minute.
- Max: 10,000 calculations per day, up to 120 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}'