How to create Sharetribe discount codes with production controls

Last substantive review: August 2026.

A promotion failure rarely stays inside the coupon box. A code passes in the checkout preview but disappears when the transaction starts. Two retries consume two uses. A platform-funded offer reduces the provider payout because the line item applies to the wrong party. A cancelled booking returns money but leaves the promotion exhausted. Support sees a code, finance sees a different total, and engineering cannot reconstruct which rule version authorized the price.

This guide is for an operating Sharetribe marketplace adding or repairing a bounded promotion-control service. It owns eligibility, funding allocation, line-item invariants, trusted authorization, limits, abuse controls, cancellation and refund policy, reporting, reconciliation, operator tools, tests, release, and acceptance evidence. It does not choose a Sharetribe plan, select the platform, make a marketing-outcome promise, or replace the Sharetribe payments guide. The broader application structure belongs in the custom Sharetribe marketplace app guide.

Horizon Labs can deliver this as a bounded full-stack product tranche: promotion service, checkout integration, operator interface, QA, launch support, and handoff at $100–120 per hour. Qualifying code is covered by the six-month warranty only when the signed statement of work names the covered deliverables, acceptance criteria, exclusions, and warranty terms. If an inherited transaction process, payout path, or money model first needs senior reconstruction, that work belongs in the $150–200 per hour specialist lane. Neither lane promises a launch date, a campaign result, or error-free operation.

Write the promotion contract before changing checkout

The code string is only a lookup key. The real product is a versioned decision about who may receive a price adjustment, what amount it changes, who funds it, when a use becomes final, and how operators repair exceptions. Write that decision in ordinary language and in data before touching the order panel.

Keep the approved contract beside examples that finance, support, product, and engineering can all check. One example should show the normal transaction without a promotion. Others should show each funding model, a cap, an ineligible user, an expired campaign, a concurrent last use, and a cancellation. If stakeholders cannot agree on those examples, implementation is not ready.

Separate eligibility, price calculation, and redemption

These operations answer different questions and should not share an ambiguous “apply coupon” endpoint.

• Eligibility answers whether a campaign rule applies to the current authoritative facts. It is read-only.
• Quote returns the rule version, eligible base, promotion amount, funding allocation, expiry, and a server reference that can be checked later. It does not consume inventory.
• Reservation temporarily holds a limited use during the narrow checkout window if the business requires that protection.
• Commit links one promotion use to one initiated Sharetribe transaction and its final promotion line item.
• Release or adjustment records why a reservation or committed use changed. It never deletes the original history.

Endpoint names such as /promotion-quotes, /promotion-reservations, /promotion-commits, and /promotion-releases are illustrative. The important boundary is behavioral. A preview can be repeated. A reservation expires. A commit is unique. A correction is additive and attributable.

Put pricing authority behind the server boundary

Sharetribe’s current privileged-transition documentation uses discount coupons as an example of logic that needs trusted server-side validation. A privileged transition can invoke sensitive pricing actions, including privileged-set-line-items, from a secure context. A normal browser token cannot be the authority for the discount amount or line items.

A safe request path looks like this:

1. The browser sends the entered code, listing ID, intended transaction type, and checkout inputs. It does not send an authoritative amount, funding party, eligibility flag, or remaining-use count.
2. The backend normalizes the code, resolves the authenticated user, retrieves the listing and campaign version, and loads any durable facts required by the rule.
3. The promotion service evaluates eligibility and returns a server-side quote record with an expiry and input fingerprint.
4. The pricing backend reconstructs the normal line items from authoritative marketplace data, adds the approved promotion line item, and validates the full invariant set.
5. At initiation, the backend rechecks the quote, current campaign state, limits, and pricing inputs, then invokes the privileged transaction transition.
6. The service commits the promotion against the resulting transaction ID or records a retryable exception for reconciliation.

Sharetribe’s pricing customization tutorial likewise constructs pricing on the backend and retrieves trusted marketplace data rather than accepting a fee amount from the frontend. Keep the Sharetribe client secret and promotion-store credentials out of browsers and mobile apps. The Authentication API reference explicitly says client secrets must not be exposed to untrusted devices.

Make eligibility reproducible

An eligibility decision needs a named rule version and a complete input snapshot. Record the campaign ID and version, normalized user ID, listing and provider IDs, transaction process name and version when known, currency, eligible subtotal, relevant booking or quantity facts, evaluation time, prior committed-use count, and the decision reason. Store only the personal data the rule genuinely needs.

Define edge behavior instead of relying on convenient defaults. Which clock decides the start and end? Is the end instant inclusive? Does “first transaction” mean first initiated, first paid, first completed, or first not later cancelled? Are guest and registered identities treated differently? Does a provider-specific offer remain valid if the listing changes before initiation? What happens when history is temporarily unavailable?

Fail closed for an input that can change money when the service cannot establish eligibility. Return a specific reason code that the UI can translate into a useful message. Do not turn a database timeout into “invalid code,” because support then cannot distinguish a customer mistake from an operating failure.

Encode the funding party in line-item invariants

Sharetribe defines payin as the sum of line items applying to the customer and payout as the sum applying to the provider. Its pricing documentation says line-item codes start with line-item/, money amounts use integer minor units with a currency, line totals can be negative, and includeFor determines whether an item applies to the customer, provider, or both. Those mechanics make a promotion possible; they do not decide the marketplace’s funding policy.

Validate the complete line-item array, not just the negative item. Use a stable promotion code, one currency, integer amounts, deterministic rounding, an allowed includeFor set, a non-positive promotion amount, and an approved eligible base. Assert the expected payin, payout, and platform difference. Reject an adjustment that exceeds its cap, crosses the minimum payable amount, produces a disallowed platform contribution, or changes a non-promotional fee.

Persist the campaign ID, rule version, quote ID, funding model, eligible base, promotion amount, and calculation fingerprint in your promotion ledger and in an approved Sharetribe transaction data location. Keep the line item itself readable. An operator should not need the original source code to understand what changed the receipt.

Control limits and abuse under concurrency

Global and per-user limits fail when they are implemented as “read count, then write count.” Two requests can observe the same remaining use. Put the limit check and reservation in one atomic database operation or enforce a unique constraint that makes the losing request explicit. Key commit operations by campaign, user or eligibility subject, Sharetribe transaction, and operation type as the contract requires.

Use a stable command ID for reserve, commit, release, and adjustment. Repeating the same command returns the existing result; it does not create a new ledger row. A different command that tries to commit the same transaction must conflict. Run an expiry worker for abandoned reservations, but preserve the expiry event and original quote.

Abuse controls should match the exposed surface. Normalize codes before lookup. Rate-limit repeated guesses by account and risk context. Avoid logging raw credentials or unnecessary personal data. Alert on sharp changes in invalid attempts, reservation churn, manual overrides, and funding totals. Do not block a whole shared network merely because one address produced failures; give support a review path for false positives.

Stacking needs an explicit compatibility matrix. Define whether two campaigns may combine, which order applies, whether caps are individual or aggregate, and which rule wins if the same code belongs to multiple campaigns. The simplest safe launch is one promotion per transaction unless the approved contract requires more.

Follow cancellations and refunds as state changes

A committed promotion does not become irrelevant after payment. The campaign policy must say whether a failed initiation releases a reservation, whether a customer cancellation restores a use, whether an operator cancellation keeps it consumed, and how a refund or dispute affects the funding allocation. These are operating decisions, not consequences to invent inside an error handler.

Sharetribe transaction processes combine states, transitions, actors, and actions. The current transaction-process guide shows cancellation transitions that cancel a booking, calculate a refund, and issue the payment refund. Sharetribe’s current pricing guide says its built-in full-refund calculation reverses prior line items and can run once. Confirm the actual process and version used by the marketplace rather than assuming every transaction follows the example.

The official cancellation and refund guidance warns that issuing refunds directly in the payment dashboard can leave Sharetribe transaction state out of sync. Route ordinary operator actions through the approved Sharetribe process. If an exceptional payment-side action is unavoidable, create a reconciliation case instead of silently marking the promotion repaired.

Model promotion aftercare with additive records: reservation_released, redemption_restored, redemption_retained, or manual_adjustment. Each record references the original redemption, Sharetribe transaction, triggering transition or incident, policy version, actor, timestamp, and reason. This history lets support explain why a code can or cannot be used again.

Build reporting from three records, then reconcile them

Promotion reporting is not the count in the campaign table. Reconcile three sources: the promotion ledger, the Sharetribe transaction with its process version and line items, and the payment or payout records owned by the marketplace’s financial operations. The marketplace payout guide owns the provider-neutral money lifecycle; this page only specifies the promotion references it needs.

Sharetribe’s Integration API exposes transactions, line items, payin and payout totals, process information, metadata, and ordered events. Its event sequence IDs provide strict ordering, but the reference notes that events may be delayed and retains them for a limited window. Persist your checkpoint, consume forward by sequence ID, and run periodic transaction queries so a stalled consumer or expired event window does not create a permanent blind spot.

Store the reconciliation window, source checkpoints, counts, exceptions, and dispositions. A zero-exception dashboard means little if the consumer has not advanced. For a broader migration or replay design, use the webhook and API reconciliation guide.

Give operators a control plane, not direct database access

A bounded admin surface should let authorized operators draft a campaign, preview examples, submit it for approval, schedule activation, pause new quotes, inspect uses, release eligible reservations, and create reasoned adjustments. Published rule versions are immutable. A change creates a new version with a future activation point; it does not rewrite how an existing transaction was priced.

Separate roles for authoring, approving, operating, and investigating when the risk warrants it. Display who funds the campaign, the maximum exposure, current committed and reserved counts, expiry policy, last reconciliation checkpoint, and unresolved exceptions. High-consequence overrides need a second review or a tightly scoped permission. Exported reports should use the same ledger queries as the screen.

Record every admin command with actor, before and after state, reason, request ID, and result. Mask secrets and unnecessary personal data. If a promotion-related customer case becomes a dispute, the marketplace dispute admin guide owns the broader evidence, decision, and appeal workflow.

Test the failures that change money or inventory

Use representative transaction process versions and fixtures. A mocked success response cannot prove that Sharetribe accepted the intended line items or that the internal team can diagnose a mismatch. Keep a small set of end-to-end test campaigns with clearly non-production limits and accounts.

Roll out one campaign with a stop path

Start with a shadow phase that calculates and records the proposed promotion without changing the Sharetribe price. Compare the normal and proposed line items, funding allocation, and eligibility reasons. Then enable one internal or tightly identified cohort, one transaction process, one currency, one funding model, and one campaign version.

Name stop conditions before launch: invariant rejection, duplicate commit, unexplained funding mismatch, reconciliation checkpoint lag, elevated privileged-transition failures, or an operator unable to pause the campaign. The first rollback is to stop new quotes and reservations. Existing committed transactions remain historical facts; repair them through the approved transaction and adjustment paths.

Capture the feature flag, decision owner, cohort query, campaign version, deployment version, observed transactions, exception count, and last safe routing rollback point. Rehearse pause, reservation expiry, reconciliation replay, and one aftercare decision before opening the cohort.

Accept a working control system, not a coupon input

The statement of work should name the transaction processes, campaign types, currencies, funding models, environments, admin roles, integrations, deliverables, exclusions, access, acceptance tests, launch responsibility, support window, and receiving owners. The product-team lane is appropriate when these decisions are settled and the work is a bounded build. Use the specialist lane when the team must first reconstruct inherited pricing or transaction behavior.

If a promotion backlog is blocked because nobody can prove who funds the adjustment or what happens after cancellation, contact Horizon Labs with one proposed campaign and one representative transaction. Those two records are enough to scope a useful first tranche.

Frequently asked questions

How should a Sharetribe discount code be applied safely?

Treat the browser as a request surface, not a pricing authority. Send the code and checkout inputs to a trusted backend, load the authoritative campaign, listing, user, and transaction data there, evaluate eligibility, calculate the promotion line item, and invoke the pricing transition from the secure context. Re-evaluate the same rule version when the transaction is initiated so a stale preview cannot authorize a different price.

Who should fund a marketplace promotion?

Choose the funding party in the promotion contract before implementation. A provider-funded promotion changes the provider economics, a platform-funded promotion changes the marketplace economics, and a shared promotion needs an explicit allocation. Encode that choice in line-item inclusion and validate the resulting payin, payout, and platform amount against the approved policy for every transaction type.

When should a promotion use be counted?

A price preview should not consume a use. Reserve capacity only when checkout reaches the agreed commitment point, and commit the redemption when the Sharetribe transaction and promotion record can be linked. Give reserve, commit, and release commands stable idempotency keys so retries do not create extra uses. Expired or failed reservations need a scheduled release path.

What happens to a discount after a cancellation or refund?

The answer comes from the campaign policy and the actual transaction state. Decide whether a committed use remains consumed, becomes reusable, or requires a manual adjustment. Link any release or adjustment to the original transaction, line items, cancellation or refund transition, operator, and reason. Do not infer promotion state from a payment-provider dashboard alone.

What evidence shows a Sharetribe promotion build is ready to launch?

Require an approved campaign and funding contract; reviewed server-side authorization; deterministic line-item tests; concurrency and retry tests; cancellation and refund cases; an operator console with audit history and safe pause controls; reconciliation that detects seeded exceptions; a limited rollout with stop conditions; a rehearsed rollback or repair path; and a handoff in which the internal team can operate the scoped promotion.

Sources

• https://www.sharetribe.com/docs/concepts/pricing-and-commissions/pricing/
• https://www.sharetribe.com/docs/concepts/transactions/privileged-transitions/
• https://www.sharetribe.com/docs/tutorial/customize-pricing/
• https://www.sharetribe.com/docs/concepts/transactions/transaction-process/
• https://www.sharetribe.com/api-reference/integration.html
• https://www.sharetribe.com/api-reference/authentication.html
• https://www.sharetribe.com/help/en/articles/8825461-how-to-cancel-a-transaction-and-issue-a-refund