Grow and track
Promotions, price, fees, Ads, metrics and finance.
With the catalog published and sales going, the seller wants to sell more and know how much they made. This phase covers both.
1. Promotions
A promotion is a discount with a deadline on a Connection. It comes from two places:
- From the seller (
origin: seller): you create it through the API. Discount, coupon, buy-more-pay-less, flash sale. - From the marketplace (
origin: marketplace): a campaign invitation. You only decide whether to join, untiljoinDeadlineAt.
Each offer joins the promotion through an entry, with its promotional price, the discount in bps and, if you want, a stock limit. Before adding an offer, look at its eligibilities: they say which promotions the offer can join and why it cannot join the others.
sellerShareBps says how much of the discount the seller pays. 5000 means half.
Renewal. No marketplace renews a promotion on its own. With a renewal rule, marketapi creates the promotion again before it ends, with the same entries. promotion.renewed arrives.
2. Price and fees
- Estimate fees: send a price and get, in cents, the commission, the fixed fee, shipping and the net. It is a job. Use it before publishing a new price.
- Competitive price: where several sellers sell the same product, see whether the offer is winning, the price to win and the suggested price.
3. Ads
The sponsored ad campaigns of each Connection show up in one format: impressions, clicks, spend (spendInCents), CTR and ROAS, both in bps. You can pause, activate or change the budget, when the marketplace allows it. marketapi syncs the numbers every day, and you can ask for a sync of a period.
The marketplace revises the numbers of the last few days. So a recent day may change.
4. Metrics
Per product and per offer: visits, units sold, revenue (revenueInCents) and conversion (conversionBps). Every series has period, granularity (day, week or month) and timezone. Sales are computed from the imported orders, without cancelled orders.
null is not zero: it means the marketplace does not report that number.
5. Finance
What the marketplace paid and charged the seller:
| Resource | What it shows |
|---|---|
| Transactions | each credit and debit, with marketapi's type and the marketplace's |
| Settlements | the money that landed in the seller's account |
| Fee statements | the fees charged per period |
| Balances | the available and pending balance at the marketplace |
The data arrives once a day. Use it to reconcile, not to decide on the spot: an entry from today may only show up tomorrow. A credit is positive, a debit is negative.
Endpoints in this phase
| To | Endpoint |
|---|---|
| Create promotions | List · Create · Replace entries |
| Put an offer in a promotion | Eligibilities · Offer's promotions · Create for the offer |
| Renew | Renewal rules · Create rule |
| Price | Estimate fees · Competitive price |
| Ads | Campaigns · Metrics · Actions · Sync |
| Metrics | Product · Offer · Visits |
| Finance | Transactions · Settlements · Fees · Balances |
Webhooks in this phase: promotion.created, promotion.updated, promotion.entry_updated and promotion.renewed. Ads, metrics and finance have no webhook: read them when you need them.